openapi: 3.1.0
info:
  title: Sirv AI Studio API
  description: AI-powered image and video processing tools for background removal, upscaling, generation, and more.
  version: 1.0.0
  contact:
    name: Sirv AI Studio
    url: https://www.sirv.studio
servers:
  - url: https://www.sirv.studio
    description: Production server

paths:
  /api/fal/remove-background:
    post:
      operationId: removeBackground
      summary: Remove background from image
      description: Remove the background from an image, leaving only the foreground subject with transparency. Perfect for product photos and portraits.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to process
                provider:
                  type: string
                  enum: [birefnet, bria]
                  default: birefnet
                  description: Background removal provider
                model:
                  type: string
                  enum:
                    - General Use (Light)
                    - General Use (Heavy)
                    - Portrait
                    - Matting
                  default: General Use (Heavy)
                  description: Model variant for quality/speed tradeoff
                operating_resolution:
                  type: string
                  enum: ["1024x1024", "2048x2048", "2304x2304"]
                  default: "1024x1024"
                  description: Processing resolution
      responses:
        "200":
          description: Successfully removed background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/upscale:
    post:
      operationId: upscaleImage
      summary: Upscale image resolution
      description: Upscale an image to a higher resolution (2x, 3x, or 4x) using AI-powered super-resolution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to upscale
                scale:
                  type: integer
                  enum: [2, 3, 4]
                  default: 2
                  description: Upscale factor
                model:
                  type: string
                  enum: [esrgan, clarity, topaz]
                  default: esrgan
                  description: Upscaler model
                prompt:
                  type: string
                  description: Optional prompt to guide upscaling (clarity model only)
                creativity:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Creativity level for clarity model
      responses:
        "200":
          description: Successfully upscaled image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/generate:
    post:
      operationId: generateImage
      summary: Generate image from text
      description: Generate images from a text description using AI image generation models.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 2000
                  description: Text description of the image to generate
                model:
                  type: string
                  enum: [flux2, zimage, gemini, seedream]
                  default: zimage
                  description: Generation model
                aspect_ratio:
                  type: string
                  enum: ["1:1", "16:9", "9:16", "4:3", "3:4", "21:9"]
                  default: "1:1"
                  description: Output aspect ratio
                num_images:
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 1
                  description: Number of images to generate
      responses:
        "200":
          description: Successfully generated images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/image-to-image:
    post:
      operationId: imageToImage
      summary: Transform image with text prompt
      description: Transform an existing image based on a text prompt while preserving the original composition.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - prompt
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the source image
                prompt:
                  type: string
                  maxLength: 2000
                  description: Description of the desired transformation
                strength:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.75
                  description: Transformation strength (higher = more change)
                model:
                  type: string
                  enum: [flux2-lora, reve-fast-edit, qwen-integrate-product]
                  default: reve-fast-edit
                  description: Transformation model
      responses:
        "200":
          description: Successfully transformed image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/background-replace:
    post:
      operationId: replaceBackground
      summary: Replace image background
      description: Replace the background of an image while keeping the foreground subject intact.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to process
                prompt:
                  type: string
                  description: Description of the new background
                ref_image_url:
                  type: string
                  format: uri
                  description: Reference image for the new background style
                model:
                  type: string
                  enum: [bria, flux-kontext, nano-banana]
                  default: bria
                  description: Background replacement model
      responses:
        "200":
          description: Successfully replaced background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/object-removal:
    post:
      operationId: removeObjects
      summary: Remove objects from image
      description: Remove unwanted objects from an image using AI inpainting with a mask.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - mask_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to edit
                mask_url:
                  type: string
                  format: uri
                  description: URL of mask image (white areas = objects to remove)
      responses:
        "200":
          description: Successfully removed objects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/alt-text:
    post:
      operationId: generateAltText
      summary: Generate alt text for image
      description: Generate descriptive alt text for an image using AI vision models.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to describe
                detail_level:
                  type: string
                  enum: [caption, detailed-caption, more-detailed-caption]
                  default: detailed-caption
                  description: Level of detail in the description
      responses:
        "200":
          description: Successfully generated alt text
          content:
            application/json:
              schema:
                type: object
                properties:
                  caption:
                    type: string
                    description: The generated alt text
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/depth-map:
    post:
      operationId: generateDepthMap
      summary: Generate depth map (FREE)
      description: Generate a depth map from an image showing relative distances. Lighter areas are closer, darker are farther.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to analyze
      responses:
        "200":
          description: Successfully generated depth map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/fal/product-lifestyle:
    post:
      operationId: createProductLifestyle
      summary: Create product lifestyle shot
      description: Place a product in a realistic lifestyle scene for marketing and e-commerce.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the product image (ideally with transparent background)
                scene_description:
                  type: string
                  description: Description of the lifestyle scene
                ref_image_url:
                  type: string
                  format: uri
                  description: Reference image for the scene style
                placement_type:
                  type: string
                  enum: [original, automatic, manual_placement, manual_padding]
                  default: automatic
                  description: How to place the product in the scene
                num_results:
                  type: integer
                  minimum: 1
                  maximum: 4
                  default: 1
                  description: Number of variations to generate
      responses:
        "200":
          description: Successfully created lifestyle shots
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/virtual-try-on:
    post:
      operationId: virtualTryOn
      summary: Virtual clothing try-on
      description: Virtually try clothing on a person using AI.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - person_image_url
                - garment_image_url
              properties:
                person_image_url:
                  type: string
                  format: uri
                  description: URL of the person/model image
                garment_image_url:
                  type: string
                  format: uri
                  description: URL of the clothing item image
      responses:
        "200":
          description: Successfully generated try-on image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/image-to-3d:
    post:
      operationId: imageTo3D
      summary: Convert image to 3D model
      description: Convert a 2D image into a 3D model using AI. Returns GLB, OBJ, FBX, and USDZ formats.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
              properties:
                image_url:
                  type: string
                  format: uri
                  description: URL of the image to convert
                model:
                  type: string
                  enum: [meshy, meshy-multi, seed3d, trellis, trellis2, hunyuan3d]
                  default: meshy
                  description: 3D generation model
                topology:
                  type: string
                  enum: [triangle, quad]
                  default: triangle
                  description: Mesh topology type
                target_polycount:
                  type: integer
                  minimum: 1000
                  maximum: 200000
                  description: Target polygon count
                enable_pbr:
                  type: boolean
                  default: true
                  description: Enable PBR textures
      responses:
        "200":
          description: Successfully generated 3D model
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Model3DResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/fal/video-generation:
    post:
      operationId: generateVideo
      summary: Generate video from text/image
      description: Generate a video from a text prompt or starting image using AI.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  maxLength: 2000
                  description: Description of the video to generate
                image_url:
                  type: string
                  format: uri
                  description: Optional starting image for image-to-video
                model:
                  type: string
                  enum: [veo31, ltx, kling]
                  default: veo31
                  description: Video generation model
                duration:
                  type: string
                  description: Video duration in seconds
                resolution:
                  type: string
                  enum: [720p, 1080p, 1440p, 2160p]
                  description: Video resolution
                aspect_ratio:
                  type: string
                  enum: [auto, "16:9", "9:16", "1:1"]
                  description: Video aspect ratio
                generate_audio:
                  type: boolean
                  default: false
                  description: Generate audio for the video
      responses:
        "200":
          description: Successfully generated video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"

  /api/user/usage/stats:
    get:
      operationId: getUsageStats
      summary: Get usage statistics
      description: Get current credit usage statistics for the account.
      responses:
        "200":
          description: Successfully retrieved usage stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    type: object
                    properties:
                      used:
                        type: integer
                        description: Credits used this period
                      remaining:
                        type: integer
                        description: Credits remaining
                      total:
                        type: integer
                        description: Total credits for the period
                      tier:
                        type: string
                        description: Subscription tier name
        "401":
          $ref: "#/components/responses/Unauthorized"

components:
  schemas:
    ImageResponse:
      type: object
      properties:
        image:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: URL of the processed image

    MultiImageResponse:
      type: object
      properties:
        images:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: URL of a generated image

    VideoResponse:
      type: object
      properties:
        video:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: URL of the generated video

    Model3DResponse:
      type: object
      properties:
        glb:
          type: object
          properties:
            url:
              type: string
              format: uri
        obj:
          type: object
          properties:
            url:
              type: string
              format: uri
        fbx:
          type: object
          properties:
            url:
              type: string
              format: uri
        usdz:
          type: object
          properties:
            url:
              type: string
              format: uri
        thumbnail:
          type: object
          properties:
            url:
              type: string
              format: uri

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

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InsufficientCredits:
      description: Insufficient credits
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth access token

security:
  - bearerAuth: []