Create docs/api/openai.yaml

docs/api/openai.yaml

@@ -0,0 +1,596 @@
+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'