openapi: 3.0.3
info:
  title: BackgroundFX Pro API
  description: |
    AI-powered background removal and replacement API.
    
    ## Authentication
    All API requests require authentication using Bearer tokens.
    
    ## Rate Limiting
    - Free tier: 100 requests/hour
    - Pro tier: 1000 requests/hour
    - Enterprise: Unlimited
    
    ## File Limits
    - Images: 50MB max
    - Videos: 500MB max
    - Batch: 100 files max
  version: 1.0.0
  contact:
    email: api@backgroundfx.pro
    url: https://backgroundfx.pro
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.backgroundfx.pro/v1
    description: Production server
  - url: https://staging-api.backgroundfx.pro/v1
    description: Staging server
  - url: http://localhost:8000/v1
    description: Local development

security:
  - BearerAuth: []

tags:
  - name: Authentication
    description: User authentication and authorization
  - name: Processing
    description: Image and video processing operations
  - name: Projects
    description: Project management
  - name: Backgrounds
    description: Background library and generation
  - name: Users
    description: User profile and settings
  - name: Webhooks
    description: Webhook management

paths:
  /auth/login:
    post:
      tags: [Authentication]
      summary: User login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
      responses:
        200:
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        401:
          $ref: '#/components/responses/Unauthorized'

  /auth/register:
    post:
      tags: [Authentication]
      summary: Register new user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, name]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                name:
                  type: string
                  minLength: 2
      responses:
        201:
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        400:
          $ref: '#/components/responses/BadRequest'

  /process/remove-background:
    post:
      tags: [Processing]
      summary: Remove background from image
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file (PNG, JPG, WebP)
                model:
                  type: string
                  enum: [rembg, u2net, deeplab, custom]
                  default: rembg
                quality:
                  type: string
                  enum: [low, medium, high, ultra]
                  default: high
                return_mask:
                  type: boolean
                  default: false
                edge_refinement:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 50
      responses:
        200:
          description: Background removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingResult'
        400:
          $ref: '#/components/responses/BadRequest'
        413:
          $ref: '#/components/responses/PayloadTooLarge'

  /process/batch:
    post:
      tags: [Processing]
      summary: Process multiple files
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files]
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  maxItems: 100
                options:
                  type: string
                  description: JSON string of processing options
      responses:
        202:
          description: Batch job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJob'

  /process/jobs/{jobId}:
    get:
      tags: [Processing]
      summary: Get batch job status
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Job status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJob'
        404:
          $ref: '#/components/responses/NotFound'

  /process/replace-background:
    post:
      tags: [Processing]
      summary: Replace image background
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [image_id, background_id]
              properties:
                image_id:
                  type: string
                background_id:
                  type: string
                blend_mode:
                  type: string
                  enum: [normal, multiply, screen, overlay]
                  default: normal
      responses:
        200:
          description: Background replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingResult'

  /backgrounds:
    get:
      tags: [Backgrounds]
      summary: List available backgrounds
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [solid, gradient, pattern, nature, abstract, custom]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        200:
          description: List of backgrounds
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Background'
                  total:
                    type: integer
                  page:
                    type: integer
                  pages:
                    type: integer

  /backgrounds/generate:
    post:
      tags: [Backgrounds]
      summary: Generate AI background
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  minLength: 3
                  maxLength: 500
                style:
                  type: string
                  enum: [realistic, artistic, abstract, gradient]
                  default: realistic
                width:
                  type: integer
                  default: 1920
                height:
                  type: integer
                  default: 1080
      responses:
        201:
          description: Background generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Background'

  /projects:
    get:
      tags: [Projects]
      summary: List user projects
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: search
          in: query
          schema:
            type: string
      responses:
        200:
          description: List of projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  total:
                    type: integer

    post:
      tags: [Projects]
      summary: Create new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type]
              properties:
                name:
                  type: string
                type:
                  type: string
                  enum: [image, video, batch]
                description:
                  type: string
      responses:
        201:
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'

  /webhooks:
    post:
      tags: [Webhooks]
      summary: Register webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum: [job.completed, job.failed, project.created]
                secret:
                  type: string
      responses:
        201:
          description: Webhook registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100

  schemas:
    AuthResponse:
      type: object
      properties:
        token:
          type: string
        refresh_token:
          type: string
        user:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        plan:
          type: string
          enum: [free, pro, enterprise]
        created_at:
          type: string
          format: date-time

    ProcessingResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        image:
          type: string
          format: uri
        mask:
          type: string
          format: uri
        metadata:
          type: object
          properties:
            width:
              type: integer
            height:
              type: integer
            format:
              type: string
            processing_time:
              type: number

    BatchJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, processing, completed, failed]
        progress:
          type: number
          minimum: 0
          maximum: 100
        total_files:
          type: integer
        processed_files:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProcessingResult'
        created_at:
          type: string
          format: date-time

    Background:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        thumbnail:
          type: string
          format: uri
        category:
          type: string
        tags:
          type: array
          items:
            type: string

    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum: [image, video, batch]
        status:
          type: string
          enum: [draft, processing, completed]
        files_count:
          type: integer
        created_at:
          type: string
          format: date-time

    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        active:
          type: boolean
        created_at:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    PayloadTooLarge:
      description: File too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'