openapi: 3.1.0
info:
  title: Sirv AI Studio API
  description: AI-powered image, video, and commerce-creative processing endpoints for Sirv AI Studio.
  version: 1.0.0
  contact:
    name: Sirv AI Studio
    url: https://www.sirv.studio
servers:
  - url: https://www.sirv.studio
    description: Production server
tags:
  - name: Account
    description: Authenticated account and usage endpoints.
  - name: AI 3D tools
    description: AI 3D tools endpoints.
  - name: AI image tools
    description: Image processing, generation, editing, and commerce-creative endpoints.
  - name: AI text tools
    description: Text generation and product-copy endpoints.
  - name: AI video tools
    description: Video generation and motion endpoints.
  - name: Assets
    description: Asset library endpoints for DAM search, metadata, and bulk operations.
  - name: Products
    description: Product catalog endpoints for PIM search, assets, and bulk operations.
  - name: Supplier publishing
    description: Supplier publishing endpoints.
  - name: Zapier automation
    description: Automation endpoints used by Zapier, n8n, and compatible workflow tools.
paths:
  /api/vendor/products:
    get:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations.
      operationId: listSupplierProducts
      parameters:
        - name: limit
          description: Page size
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 1000
            default: 200
        - name: offset
          description: Page offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: search
          description: Product name or SKU
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierProductsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: List assigned products
      tags:
        - Supplier publishing
  /api/vendor/products/{productId}/slots:
    get:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations.
      operationId: getSupplierProductSlots
      parameters:
        - name: productId
          description: Assigned product ID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierSlotsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Read shots and upload requirements
      tags:
        - Supplier publishing
  /api/vendor/batch-upload/resolve:
    post:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations.
      operationId: resolveSupplierFilenames
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                files:
                  minItems: 1
                  maxItems: 10000
                  type: array
                  items:
                    type: object
                    properties:
                      clientFileId:
                        type: string
                        minLength: 1
                        maxLength: 200
                      filename:
                        type: string
                        minLength: 1
                        maxLength: 500
                    required:
                      - clientFileId
                      - filename
                    additionalProperties: false
                strategy:
                  default: auto
                  type: string
                  enum:
                    - auto
                    - csv
                csvData:
                  type: string
                  maxLength: 5000000
                csvMapping:
                  type: object
                  properties:
                    filename:
                      type: string
                      minLength: 1
                      maxLength: 200
                    sku:
                      type: string
                      minLength: 1
                      maxLength: 200
                    ean:
                      type: string
                      minLength: 1
                      maxLength: 200
                    role:
                      type: string
                      minLength: 1
                      maxLength: 200
                    position:
                      type: string
                      minLength: 1
                      maxLength: 200
                  additionalProperties: false
              required:
                - files
              additionalProperties: false
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierResolveResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Resolve supplier filenames
      tags:
        - Supplier publishing
  /api/vendor/products/{productId}/upload/presign:
    post:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations.
        Ordinary new uploads to occupied shots return SLOT_OCCUPIED (409); explicit parent
        resubmission retains server validation. VENDOR_FILE_TOO_LARGE (413) uses the limits returned
        by the slots endpoint. Preview writes return VENDOR_PREVIEW_READ_ONLY (403).
      operationId: presignSupplierUpload
      parameters:
        - name: productId
          description: Assigned product ID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentAssetId:
                  anyOf:
                    - type: string
                    - type: "null"
                metadataTemplateId:
                  anyOf:
                    - type: string
                    - type: "null"
                role:
                  type: string
                  enum:
                    - main
                    - gallery
                    - lifestyle
                    - detail
                    - swatch
                position:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                customMetadata:
                  anyOf:
                    - type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                    - type: "null"
                filename:
                  type: string
                  minLength: 1
                size:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                type:
                  default: application/octet-stream
                  type: string
                  minLength: 1
                hasPreview:
                  type: boolean
                previewSize:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 2097152
              required:
                - filename
                - size
              additionalProperties: false
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierPresignResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Supplier upload rejected; inspect the stable code and error message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "413":
          description: Supplier upload rejected; inspect the stable code and error message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Prepare supplier upload
      tags:
        - Supplier publishing
  /api/vendor/products/{productId}/upload/confirm:
    post:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations.
        committed=true means persisted, not approved. Processing and review may still reject the
        submission. VENDOR_STALE_CONFIRM (409) is not proof that an earlier attempt did not commit;
        reconcile the known ID through submission status. VENDOR_DUPLICATE_ASSET (409) does not
        disclose a canonical asset ID. Concurrent last-slot losers return SLOT_OCCUPIED; no
        overwrite.
      operationId: confirmSupplierUpload
      parameters:
        - name: productId
          description: Assigned product ID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentAssetId:
                  anyOf:
                    - type: string
                    - type: "null"
                metadataTemplateId:
                  anyOf:
                    - type: string
                    - type: "null"
                role:
                  type: string
                  enum:
                    - main
                    - gallery
                    - lifestyle
                    - detail
                    - swatch
                position:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                customMetadata:
                  anyOf:
                    - type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                    - type: "null"
                assetId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                r2Key:
                  type: string
                  minLength: 1
                filename:
                  type: string
                  minLength: 1
                size:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                type:
                  default: application/octet-stream
                  type: string
                  minLength: 1
                previewR2Key:
                  type: string
                  minLength: 1
                  maxLength: 500
                contentHash:
                  anyOf:
                    - type: string
                      pattern: ^[a-f0-9]{64}$
                    - type: "null"
                clientItemId:
                  type: string
                  minLength: 1
                  maxLength: 200
              required:
                - assetId
                - r2Key
                - filename
                - size
              additionalProperties: false
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierConfirmResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Supplier upload rejected; inspect the stable code and error message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "413":
          description: Supplier upload rejected; inspect the stable code and error message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Confirm uploaded supplier file
      tags:
        - Supplier publishing
  /api/vendor/submissions/{assetId}:
    get:
      description: Supplier V1 contract. Uses current supplier permissions and live workspace/product
        assignment checks. Capture One grants use supplier:read for product/shot/submission reads
        and filename resolution, and supplier:upload for presign/confirm. Other REST and MCP
        operations reject supplier grants. Availability reads are advisory, not reservations. Reads
        only this supplier's submission in this workspace. A 404 can mean hidden or missing; it does
        not prove an uncertain upload never committed.
      operationId: getSupplierSubmission
      parameters:
        - name: assetId
          description: Owned submission ID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Supplier operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupplierSubmissionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Read an owned submission
      tags:
        - Supplier publishing
  /api/zapier/me:
    get:
      description: Verify a Zapier or compatible automation API key and return the authenticated user
        profile used for connector authentication tests.
      operationId: zapierGetAuthenticatedUser
      responses:
        "200":
          description: Authenticated Zapier user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierAuthenticatedUserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - zapierApiKey: []
      summary: Get authenticated Zapier user
      tags:
        - Zapier automation
  /api/zapier/sirv/search:
    post:
      description: Search files in the connected Sirv account using Sirv search syntax for Zapier and
        automation workflows.
      operationId: zapierSirvSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                from:
                  type: integer
                  minimum: 0
                  maximum: 1000
                size:
                  default: 100
                  type: integer
                  minimum: 1
                  maximum: 100
                sort_field:
                  type: string
                  enum:
                    - filename.raw
                    - basename.raw
                    - dirname.raw
                    - contentType.raw
                    - mtime
                    - ctime
                    - size
                sort_order:
                  type: string
                  enum:
                    - asc
                    - desc
              required:
                - query
              additionalProperties: false
      responses:
        "200":
          description: Successfully searched Sirv files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Search Sirv files
      tags:
        - Zapier automation
  /api/zapier/sirv/get-metadata:
    post:
      description: Fetch reviewed metadata fields and file information for one file in the connected Sirv
        account.
      operationId: zapierSirvGetMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_path:
                  type: string
                  minLength: 1
              required:
                - file_path
              additionalProperties: false
      responses:
        "200":
          description: Successfully fetched Sirv file metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvGetMetadataResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Get Sirv file metadata
      tags:
        - Zapier automation
  /api/zapier/sirv/file:
    post:
      description: Queue a Sirv file rename, copy, or delete operation for the connected workspace account.
      operationId: zapierSirvFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - rename
                    - copy
                    - delete
                file_path:
                  type: string
                  minLength: 1
                target_path:
                  type: string
                  minLength: 1
              required:
                - action
                - file_path
              additionalProperties: false
              anyOf:
                - properties:
                    action:
                      const: delete
                  required:
                    - action
                    - file_path
                - required:
                    - action
                    - file_path
                    - target_path
      responses:
        "200":
          description: Successfully queued Sirv file operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvFileOperationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Queue Sirv file operation
      tags:
        - Zapier automation
  /api/zapier/sirv/folder:
    post:
      description: Create a Sirv folder or list folder contents in the connected workspace account.
      operationId: zapierSirvFolder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - create
                    - list
                folder_path:
                  type: string
                  minLength: 1
                continuation:
                  type: string
                  minLength: 1
              required:
                - action
                - folder_path
              additionalProperties: false
      responses:
        "200":
          description: Successfully performed Sirv folder operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvFolderOperationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Perform Sirv folder operation
      tags:
        - Zapier automation
  /api/zapier/sirv/upload:
    post:
      description: Fetch a remote file URL into the connected Sirv account for Zapier and automation workflows.
      operationId: zapierSirvUpload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                  maxLength: 1024
                filename:
                  type: string
                  minLength: 1
                  maxLength: 1024
                folder:
                  type: string
                  default: /ai-tools
                  minLength: 0
                  maxLength: 1024
                target_path:
                  type: string
                  minLength: 1
                  maxLength: 1024
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully uploaded remote file to Sirv
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvUploadResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Upload remote file to Sirv
      tags:
        - Zapier automation
  /api/zapier/sirv/metadata:
    post:
      description: Queue a Sirv file metadata update for the connected workspace account.
      operationId: zapierSirvMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_path:
                  type: string
                  minLength: 1
                description:
                  type: string
                  maxLength: 1024
                title:
                  type: string
                  maxLength: 256
                tags:
                  minItems: 1
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 32
                product:
                  type: object
                  minProperties: 1
                  properties:
                    id:
                      type: string
                      maxLength: 256
                    name:
                      type: string
                      maxLength: 256
                    brand:
                      type: string
                      maxLength: 256
                    category1:
                      type: string
                      maxLength: 256
                    category2:
                      type: string
                      maxLength: 256
                  additionalProperties: false
              required:
                - file_path
              additionalProperties: false
              anyOf:
                - required:
                    - description
                - required:
                    - title
                - required:
                    - tags
                - required:
                    - product
      responses:
        "200":
          description: Successfully queued Sirv metadata update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvMetadataUpdateResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Queue Sirv file metadata update
      tags:
        - Zapier automation
  /api/zapier/sirv/tags:
    post:
      description: Queue a Sirv file tag add or remove operation for the connected workspace account.
      operationId: zapierSirvTags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_path:
                  type: string
                  minLength: 1
                action:
                  default: add
                  type: string
                  enum:
                    - add
                    - remove
                tags:
                  minItems: 1
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 32
              required:
                - file_path
                - tags
              additionalProperties: false
      responses:
        "200":
          description: Successfully queued Sirv tag update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierSirvTagsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/WorkspaceCapabilityRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - zapierApiKey: []
      summary: Queue Sirv file tag update
      tags:
        - Zapier automation
  /api/zapier/remove-bg:
    post:
      description: Remove the background from an image for Zapier and automation workflows.
      operationId: zapierRemoveBackground
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                model:
                  default: birefnet
                  type: string
                  enum:
                    - birefnet
                    - birefnet-v2
                    - bria
                operating_resolution:
                  default: 1024x1024
                  type: string
                  enum:
                    - 1024x1024
                    - 2048x2048
                    - 2304x2304
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully removed background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Remove background from image
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/replace-bg:
    post:
      description: Replace the background of an image for Zapier and automation workflows.
      operationId: zapierReplaceBackground
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                prompt:
                  type: string
                ref_image_url:
                  type: string
                  format: uri
                color:
                  type: string
                  pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
                color_mode:
                  default: smart
                  type: string
                  enum:
                    - smart
                    - simple
                model:
                  default: nano-banana-lite
                  type: string
                  enum:
                    - nano-banana-lite
                    - solid-color
                    - bria
                    - flux-kontext
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully replaced background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Replace image background
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/upscale:
    post:
      description: Enhance image resolution for Zapier and automation workflows.
      operationId: zapierUpscaleImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                scale:
                  default: 2
                  type: number
                  minimum: 1
                  maximum: 10
                model:
                  default: esrgan
                  type: string
                  enum:
                    - esrgan
                    - clarity
                    - topaz
                    - seedvr
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully upscaled image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Upscale image resolution
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/generate:
    post:
      description: Generate images from a text description for Zapier and automation workflows.
      operationId: zapierGenerateImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                model:
                  default: nano-banana-2-lite
                  type: string
                  enum:
                    - nano-banana-2-lite
                    - nano-banana-2
                    - flux2
                    - zimage
                    - gemini
                    - gemini-or
                    - seedream
                    - seedream-or
                    - gpt-image-2
                aspect_ratio:
                  default: landscape_4_3
                  type: string
                  enum:
                    - square_hd
                    - square
                    - portrait_4_3
                    - portrait_16_9
                    - landscape_4_3
                    - landscape_16_9
                    - 1:1
                    - 16:9
                    - 9:16
                    - 4:3
                    - 3:4
                    - 21:9
                num_images:
                  default: 1
                  type: integer
                  minimum: 1
                  maximum: 4
              required:
                - prompt
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate image from text
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/image-to-image:
    post:
      description: Transform an image based on a text prompt for Zapier and automation workflows.
      operationId: zapierImageToImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                prompt:
                  type: string
                model:
                  default: nano-banana-lite-edit
                  type: string
                  enum:
                    - nano-banana-lite-edit
                    - nano-banana-2-edit
                    - reve-fast-edit
                    - zimage-i2i
                    - flux2-edit
                    - qwen-integrate-product
                    - qwen-multiple-angles
                    - qwen-remove-lighting
                    - seedream-edit
                    - gpt-image-2-edit
                strength:
                  default: 0.85
                  type: number
                  minimum: 0
                  maximum: 1
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully transformed image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Transform image with text prompt
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/image-translation:
    post:
      description: Translate visible text in an image while preserving the surrounding image style for
        Zapier and automation workflows.
      operationId: zapierTranslateImageText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                target_language:
                  type: string
                  minLength: 1
                source_language:
                  type: string
                model:
                  default: nano-banana-lite-edit
                  type: string
                  enum:
                    - nano-banana-lite-edit
                    - gemini
                    - gpt-image-2-edit
                    - seedream-edit
              required:
                - image_url
                - target_language
              additionalProperties: false
      responses:
        "200":
          description: Successfully translated image text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierImageTranslationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Translate text in image
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/image-review:
    post:
      description: Run product-image quality checks for Zapier and automation workflows, including
        dimensions, white background, watermark, centering, and unwanted shadow checks. The endpoint
        is charged as one image-review operation per request.
      operationId: zapierReviewImageQuality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                check_background:
                  default: true
                  type: boolean
                check_watermark:
                  default: true
                  type: boolean
                check_centered:
                  default: false
                  type: boolean
                check_shadows:
                  default: false
                  type: boolean
                min_width:
                  type: number
                min_height:
                  type: number
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully reviewed image quality
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierImageReviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Review image quality
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/product-description:
    post:
      description: Generate product copy for Zapier and automation workflows from product details, an
        optional product image, and writing controls.
      operationId: zapierGenerateProductDescription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  pattern: \S
                image_url:
                  type: string
                  format: uri
                brand:
                  type: string
                category:
                  type: string
                features:
                  type: string
                language:
                  default: en
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                    - pt
                    - nl
                    - pl
                    - uk
                    - ja
                    - zh
                    - ko
                length:
                  default: medium
                  type: string
                  enum:
                    - short
                    - medium
                    - long
                price:
                  type: string
                specs:
                  type: string
                style:
                  default: professional
                  type: string
                  enum:
                    - professional
                    - casual
                    - luxury
                    - technical
                target_audience:
                  type: string
              additionalProperties: false
              anyOf:
                - required:
                    - name
                - required:
                    - image_url
      responses:
        "200":
          description: Successfully generated product description
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZapierProductDescriptionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate product description
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/alt-text:
    post:
      description: Generate descriptive alt text for Zapier and automation workflows.
      operationId: zapierGenerateAltText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                detail_level:
                  default: detailed-caption
                  type: string
                  enum:
                    - caption
                    - detailed-caption
                    - more-detailed-caption
                model:
                  default: florence
                  type: string
                  enum:
                    - florence
                    - gemini-flash
                    - gemini-3-flash
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated alt text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AltTextResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate alt text for image
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/depth-map:
    post:
      description: Generate a depth map from an image for Zapier and automation workflows.
      operationId: zapierGenerateDepthMap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated depth map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate depth map
      tags:
        - Zapier automation
  /api/zapier/object-removal:
    post:
      description: Remove objects from an image for Zapier and automation workflows.
      operationId: zapierRemoveObjects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                mask_url:
                  type: string
                  format: uri
              required:
                - image_url
                - mask_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully removed objects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Remove objects from image
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/product-lifestyle:
    post:
      description: Place a product in a lifestyle scene for Zapier and automation workflows.
      operationId: zapierCreateProductLifestyle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                scene_description:
                  type: string
                ref_image_url:
                  type: string
                  format: uri
                model:
                  default: nano-banana-lite
                  type: string
                  enum:
                    - nano-banana-lite
                    - gemini
                    - gpt-image-2
                    - bria
                    - seedream
                    - flux2
                placement_type:
                  default: manual_placement
                  type: string
                  enum:
                    - original
                    - automatic
                    - manual_placement
                    - manual_padding
                position:
                  default: bottom_center
                  type: string
                  enum:
                    - bottom_center
                    - bottom_left
                    - bottom_right
                    - upper_center
                    - upper_left
                    - upper_right
                    - center_vertical
                    - center_horizontal
                    - left_center
                    - right_center
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully created lifestyle shots
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Create product lifestyle shot
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/virtual-try-on:
    post:
      description: Virtually try clothing on a person for Zapier and automation workflows.
      operationId: zapierVirtualTryOn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_image_url:
                  type: string
                  format: uri
                garment_image_url:
                  type: string
                  format: uri
                model:
                  default: fal
                  type: string
                  const: fal
              required:
                - person_image_url
                - garment_image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated try-on image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Virtual clothing try-on
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/image-to-3d:
    post:
      description: Generate a 3D model from an image for Zapier and automation workflows.
      operationId: zapierImageTo3d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                image_urls:
                  minItems: 1
                  maxItems: 4
                  type: array
                  items:
                    type: string
                    format: uri
                model:
                  default: meshy
                  type: string
                  enum:
                    - meshy
                    - meshy-multi
                    - seed3d
                    - trellis
                    - trellis2
                    - hunyuan3d
                topology:
                  default: triangle
                  type: string
                  enum:
                    - triangle
                    - quad
                enable_pbr:
                  default: true
                  type: boolean
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated 3D model
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Model3DResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Convert image to 3D model
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/zapier/video-generation:
    post:
      description: Generate a video from text or image input for Zapier and automation workflows.
      operationId: zapierGenerateVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                image_urls:
                  type: array
                  items:
                    type: string
                    format: uri
                prompt:
                  type: string
                  minLength: 1
                model:
                  default: veo31
                  type: string
                  enum:
                    - veo31
                    - veo31ref
                    - ltx
                    - kling
                    - kling-v3
                    - kling-v3-pro
                    - seedance-2-fast
                    - h3-max
                duration:
                  type: string
                resolution:
                  type: string
                aspect_ratio:
                  default: auto
                  type: string
                  enum:
                    - auto
                    - 21:9
                    - 16:9
                    - 4:3
                    - 9:16
                    - 3:4
                    - 1:1
                generate_audio:
                  default: true
                  type: boolean
              required:
                - prompt
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate video from text or image
      tags:
        - Zapier automation
      x-sirv-credits:
        required: true
  /api/assets:
    get:
      description: List assets in the DAM library with filtering, sorting, and pagination.
      operationId: listAssets
      parameters:
        - name: search
          in: query
          description: Filter assets by filename search.
          required: false
          schema:
            type: string
        - name: favorite
          in: query
          description: Filter by favorite status.
          required: false
          schema:
            type: boolean
        - name: tags
          in: query
          description: Comma-separated tag IDs to filter by.
          required: false
          schema:
            type: string
        - name: folderId
          in: query
          description: Folder ID, or root for the root level.
          required: false
          schema:
            type: string
        - name: productId
          in: query
          description: Linked product ID to filter by.
          required: false
          schema:
            type: string
        - name: sortBy
          in: query
          description: Sort field.
          required: false
          schema:
            type: string
            enum:
              - created_at
              - filename
            default: created_at
        - name: sortOrder
          in: query
          description: Sort direction.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: limit
          in: query
          description: Maximum number of assets to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: Successfully listed assets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: List assets
      tags:
        - Assets
  /api/assets/search:
    get:
      description: Full-text search across assets using ranked matching.
      operationId: searchAssets
      parameters:
        - name: q
          in: query
          description: Full-text search query.
          required: true
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          description: Maximum number of search hits to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
        - name: mimeType
          in: query
          description: Filter by MIME type.
          required: false
          schema:
            type: string
        - name: sourceTool
          in: query
          description: Filter by source tool.
          required: false
          schema:
            type: string
        - name: isFavorite
          in: query
          description: Filter by favorite status.
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Successfully searched assets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Search assets
      tags:
        - Assets
  /api/assets/{id}:
    get:
      description: Get a single asset by ID with its stored asset details.
      operationId: getAsset
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      responses:
        "200":
          description: Successfully retrieved asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Get asset
      tags:
        - Assets
    patch:
      description: Update editable asset fields such as filename, alt text, and favorite state.
      operationId: updateAsset
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isFavorite:
                  type: boolean
                filename:
                  type: string
                  minLength: 1
                  maxLength: 200
                sirvPath:
                  type: string
                url:
                  type: string
                  format: uri
                parentAssetId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: "null"
                showInLibrary:
                  type: boolean
                altText:
                  anyOf:
                    - type: string
                    - type: "null"
              additionalProperties: false
      responses:
        "200":
          description: Successfully updated asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Update asset
      tags:
        - Assets
    delete:
      description: Soft-delete an asset so it can be restored later.
      operationId: deleteAsset
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      responses:
        "200":
          description: Successfully deleted asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetDeleteResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Delete asset
      tags:
        - Assets
  /api/assets/{id}/metadata:
    get:
      description: Get custom metadata for an asset, including template context when applied.
      operationId: getAssetMetadata
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      responses:
        "200":
          description: Successfully retrieved asset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetMetadataResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Get asset metadata
      tags:
        - Assets
    patch:
      description: Update custom metadata fields on an asset.
      operationId: updateAssetMetadata
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: object
                    properties:
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                          - type: "null"
                      type:
                        type: string
                        enum:
                          - text
                          - number
                          - date
                          - boolean
                          - select
                      label:
                        type: string
                    required:
                      - value
                      - type
                    additionalProperties: false
                templateId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: "null"
              required:
                - metadata
              additionalProperties: false
      responses:
        "200":
          description: Successfully updated asset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetMetadataResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Update asset metadata
      tags:
        - Assets
  /api/assets/{id}/alt-text:
    post:
      description: AI-generate alt text for an asset and save it.
      operationId: generateAssetAltText
      parameters:
        - name: id
          in: path
          required: true
          description: Asset identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                detailLevel:
                  default: caption
                  type: string
                  enum:
                    - caption
                    - detailed-caption
                    - more-detailed-caption
                model:
                  type: string
                  enum:
                    - florence
                    - gemini-flash
                    - gemini-3-flash
                    - gpt-4o-mini
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated asset alt text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetAltTextResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate asset alt text
      tags:
        - Assets
      x-sirv-credits:
        required: true
  /api/assets/bulk:
    post:
      description: Perform a bulk operation on multiple assets.
      operationId: bulkAssetOperation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assetIds:
                  minItems: 1
                  maxItems: 1000
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                operation:
                  type: string
                  enum:
                    - favorite
                    - unfavorite
                    - delete
                    - addTags
                    - removeTags
                    - restore
                    - hardDelete
                    - moveToFolder
                    - copyToFolder
                tagIds:
                  maxItems: 100
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                folderId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: "null"
              required:
                - assetIds
                - operation
              additionalProperties: false
      responses:
        "200":
          description: Successfully applied bulk asset operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkAssetOperationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Bulk asset operation
      tags:
        - Assets
  /api/assets/import-url:
    post:
      description: Import an asset from an external URL into the DAM library.
      operationId: importAssetUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 5000
                  format: uri
                filename:
                  type: string
                  minLength: 1
                  maxLength: 1024
                folderId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: "null"
                customMetadata:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: object
                    properties:
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                          - type: "null"
                      type:
                        type: string
                        enum:
                          - text
                          - number
                          - date
                          - boolean
                          - select
                      label:
                        type: string
                    required:
                      - value
                      - type
                    additionalProperties: false
                metadataTemplateId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: "null"
              required:
                - url
                - filename
              additionalProperties: false
      responses:
        "200":
          description: Successfully imported asset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Import asset from URL
      tags:
        - Assets
  /api/products:
    get:
      description: List products in the PIM with filtering, sorting, readiness, and pagination.
      operationId: listProducts
      parameters:
        - name: search
          in: query
          description: Search by product name or SKU.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: nameSearch
          in: query
          description: Search by product name.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: skuSearch
          in: query
          description: Search by product SKU.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: status
          in: query
          description: Filter by product status.
          required: false
          schema:
            type: string
            enum:
              - active
              - draft
              - archived
        - name: externalSource
          in: query
          description: Filter by source system.
          required: false
          schema:
            type: string
            enum:
              - shopify
              - woocommerce
              - manual
              - csv
              - sap
        - name: brand
          in: query
          description: Filter by brand.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: productType
          in: query
          description: Filter by product type.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: categoryId
          in: query
          description: Filter by category ID.
          required: false
          schema:
            type: string
            format: uuid
        - name: tags
          in: query
          description: Comma-separated product tags.
          required: false
          schema:
            type: string
            maxLength: 500
        - name: vendorUserId
          in: query
          description: Filter to products assigned to a vendor user.
          required: false
          schema:
            type: string
            format: uuid
        - name: hasAssets
          in: query
          description: Filter by whether products have linked assets.
          required: false
          schema:
            type: string
            enum:
              - all
              - with_assets
              - without_assets
        - name: slotsFilter
          in: query
          description: Filter by product asset slot completeness.
          required: false
          schema:
            type: string
            enum:
              - complete
              - incomplete
        - name: channelId
          in: query
          description: Channel ID for readiness context.
          required: false
          schema:
            type: string
        - name: channelPresetId
          in: query
          description: Channel preset ID for readiness context.
          required: false
          schema:
            type: string
        - name: market
          in: query
          description: Market code for readiness context.
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Readiness profile ID.
          required: false
          schema:
            type: string
        - name: sourceInstanceId
          in: query
          description: Source instance ID for readiness context.
          required: false
          schema:
            type: string
        - name: readinessGap
          in: query
          description: Readiness gap code to filter by.
          required: false
          schema:
            type: string
        - name: readinessScoreLabel
          in: query
          description: Readiness score label to filter by.
          required: false
          schema:
            type: string
        - name: readinessSmartView
          in: query
          description: Readiness smart view to filter by.
          required: false
          schema:
            type: string
        - name: channelTargeting
          in: query
          description: Filter products by channel targeting decision.
          required: false
          schema:
            type: string
            enum:
              - targeted
              - excluded
              - not_targeted
              - all
        - name: advancedFilters
          in: query
          description: JSON-encoded advanced product filters.
          required: false
          schema:
            type: string
            maxLength: 5000
        - name: limit
          in: query
          description: Maximum number of products to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: cursor
          in: query
          description: Pagination cursor.
          required: false
          schema:
            type: string
            maxLength: 2000
        - name: countMode
          in: query
          description: How the total count should be calculated.
          required: false
          schema:
            type: string
            enum:
              - exact
              - page-bound
        - name: sortBy
          in: query
          description: Sort field.
          required: false
          schema:
            type: string
            enum:
              - createdAt
              - name
              - sku
              - updatedAt
            default: createdAt
        - name: sortOrder
          in: query
          description: Sort direction.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: sort
          in: query
          description: Multi-sort rule string.
          required: false
          schema:
            type: string
            maxLength: 500
      responses:
        "200":
          description: Successfully listed products
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: List products
      tags:
        - Products
    post:
      description: Create a product in the PIM catalog.
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sku:
                  type: string
                  minLength: 1
                  maxLength: 100
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  type: string
                  maxLength: 5000
                status:
                  type: string
                  enum:
                    - active
                    - draft
                    - archived
                externalId:
                  type: string
                  maxLength: 255
                externalSource:
                  type: string
                  enum:
                    - shopify
                    - woocommerce
                    - manual
                    - csv
                    - sap
                externalUrl:
                  type: string
                  maxLength: 2000
                  format: uri
                productType:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                productCategory:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                brand:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                tags:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    maxLength: 100
                categoryIds:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              required:
                - sku
                - name
              additionalProperties: false
      responses:
        "200":
          description: Successfully created product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Create product
      tags:
        - Products
  /api/products/{id}:
    get:
      description: Get a single product by ID, including readiness context when requested.
      operationId: getProduct
      parameters:
        - name: id
          in: path
          required: true
          description: Product identifier.
          schema:
            type: string
        - name: channelId
          in: query
          description: Channel ID for readiness context.
          required: false
          schema:
            type: string
        - name: channelPresetId
          in: query
          description: Channel preset ID for readiness context.
          required: false
          schema:
            type: string
        - name: market
          in: query
          description: Market code for readiness context.
          required: false
          schema:
            type: string
        - name: profileId
          in: query
          description: Readiness profile ID.
          required: false
          schema:
            type: string
        - name: sourceInstanceId
          in: query
          description: Source instance ID for readiness context.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successfully retrieved product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Get product
      tags:
        - Products
    patch:
      description: Update editable product fields in the PIM catalog.
      operationId: updateProduct
      parameters:
        - name: id
          in: path
          required: true
          description: Product identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sku:
                  type: string
                  minLength: 1
                  maxLength: 100
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  anyOf:
                    - type: string
                      maxLength: 5000
                    - type: "null"
                status:
                  type: string
                  enum:
                    - active
                    - draft
                    - archived
                brand:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                productCategory:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                productType:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                tags:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    maxLength: 100
                categoryIds:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                metafields:
                  type: array
                  items:
                    type: object
                    properties:
                      namespace:
                        type: string
                        maxLength: 255
                      key:
                        type: string
                        maxLength: 255
                      type:
                        type: string
                        maxLength: 100
                      value:
                        type: string
                        maxLength: 5000
                    required:
                      - namespace
                      - key
                      - type
                      - value
                    additionalProperties: false
                external_id:
                  anyOf:
                    - type: string
                      maxLength: 255
                    - type: "null"
                external_source:
                  anyOf:
                    - type: string
                      enum:
                        - shopify
                        - woocommerce
                        - manual
                        - csv
                        - sap
                    - type: "null"
                external_url:
                  anyOf:
                    - type: string
                      maxLength: 2000
                      format: uri
                    - type: "null"
              additionalProperties: false
      responses:
        "200":
          description: Successfully updated product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Update product
      tags:
        - Products
    delete:
      description: Delete a product from the PIM catalog.
      operationId: deleteProduct
      parameters:
        - name: id
          in: path
          required: true
          description: Product identifier.
          schema:
            type: string
      responses:
        "200":
          description: Successfully deleted product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductDeleteResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Delete product
      tags:
        - Products
  /api/products/search:
    get:
      description: Search products by name or SKU with optional fuzzy matching.
      operationId: searchProducts
      parameters:
        - name: q
          in: query
          description: Search query.
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: limit
          in: query
          description: Maximum number of search results to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: mode
          in: query
          description: Search matching mode.
          required: false
          schema:
            type: string
            enum:
              - fuzzy
              - contains
        - name: includeTotal
          in: query
          description: Whether to include a total result count.
          required: false
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "200":
          description: Successfully searched products
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Search products
      tags:
        - Products
  /api/products/with-assets:
    get:
      description: List products with their linked asset details and asset counts.
      operationId: listProductsWithAssets
      parameters:
        - name: search
          in: query
          description: Search by product name or SKU.
          required: false
          schema:
            type: string
            maxLength: 100
        - name: limit
          in: query
          description: Maximum number of products to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: sortBy
          in: query
          description: Sort field.
          required: false
          schema:
            type: string
            enum:
              - name
              - createdAt
              - assetCount
            default: name
        - name: sortOrder
          in: query
          description: Sort direction.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: tagIds
          in: query
          description: Comma-separated asset tag IDs.
          required: false
          schema:
            type: string
            maxLength: 2000
        - name: hideEmpty
          in: query
          description: Whether to hide products with no linked assets.
          required: false
          schema:
            type: string
            enum:
              - "true"
              - "false"
            default: "true"
      responses:
        "200":
          description: Successfully listed products with assets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductsWithAssetsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: List products with assets
      tags:
        - Products
  /api/products/{id}/assets:
    post:
      description: Link one or more assets to a product with optional merchandising role metadata.
      operationId: linkAssetsToProduct
      parameters:
        - name: id
          in: path
          required: true
          description: Product identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - type: object
                  properties:
                    assetId:
                      type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    role:
                      type: string
                      enum:
                        - main
                        - gallery
                        - lifestyle
                        - detail
                        - swatch
                    position:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    productVariantId:
                      anyOf:
                        - type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        - type: "null"
                    variantId:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                    variantExternalId:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                    variantSku:
                      anyOf:
                        - type: string
                          maxLength: 100
                        - type: "null"
                    slotKey:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                    replaceAtSlot:
                      type: boolean
                  required:
                    - assetId
                  additionalProperties: false
                - type: object
                  properties:
                    assetIds:
                      minItems: 1
                      maxItems: 100
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    role:
                      type: string
                      enum:
                        - main
                        - gallery
                        - lifestyle
                        - detail
                        - swatch
                    productVariantId:
                      anyOf:
                        - type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        - type: "null"
                    variantId:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                    variantExternalId:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                    variantSku:
                      anyOf:
                        - type: string
                          maxLength: 100
                        - type: "null"
                    slotKey:
                      anyOf:
                        - type: string
                          maxLength: 255
                        - type: "null"
                  required:
                    - assetIds
                  additionalProperties: false
      responses:
        "200":
          description: Successfully linked assets to product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkAssetsToProductResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Link assets to product
      tags:
        - Products
  /api/products/bulk:
    post:
      description: Perform a bulk action such as delete, status update, field update, or asset linking.
      operationId: bulkProductAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    action:
                      type: string
                      const: deleteAll
                  required:
                    - action
                  additionalProperties: false
                - type: object
                  properties:
                    action:
                      type: string
                      const: delete
                    productIds:
                      minItems: 1
                      maxItems: 500
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - action
                    - productIds
                  additionalProperties: false
                - type: object
                  properties:
                    action:
                      type: string
                      const: updateStatus
                    productIds:
                      minItems: 1
                      maxItems: 500
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    status:
                      type: string
                      enum:
                        - active
                        - draft
                        - archived
                  required:
                    - action
                    - productIds
                    - status
                  additionalProperties: false
                - type: object
                  properties:
                    action:
                      type: string
                      const: linkAssets
                    productIds:
                      minItems: 1
                      maxItems: 500
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    assetIds:
                      minItems: 1
                      maxItems: 100
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    role:
                      type: string
                      enum:
                        - main
                        - gallery
                        - lifestyle
                        - detail
                        - swatch
                  required:
                    - action
                    - productIds
                    - assetIds
                  additionalProperties: false
                - type: object
                  properties:
                    action:
                      type: string
                      const: updateFields
                    productIds:
                      minItems: 1
                      maxItems: 500
                      type: array
                      items:
                        type: string
                        format: uuid
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    fields:
                      type: object
                      properties:
                        brand:
                          anyOf:
                            - type: string
                              maxLength: 255
                            - type: "null"
                        productCategory:
                          anyOf:
                            - type: string
                              maxLength: 255
                            - type: "null"
                        productType:
                          anyOf:
                            - type: string
                              maxLength: 255
                            - type: "null"
                        description:
                          anyOf:
                            - type: string
                              maxLength: 5000
                            - type: "null"
                        tags:
                          maxItems: 50
                          type: array
                          items:
                            type: string
                            maxLength: 100
                        status:
                          type: string
                          enum:
                            - active
                            - draft
                            - archived
                      additionalProperties: false
                    tagMode:
                      default: merge
                      type: string
                      enum:
                        - merge
                        - replace
                  required:
                    - action
                    - productIds
                    - fields
                    - tagMode
                  additionalProperties: false
      responses:
        "200":
          description: Successfully applied bulk product action
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkProductActionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Bulk product action
      tags:
        - Products
  /api/fal/remove-background:
    post:
      description: Remove the background from an image, leaving only the foreground subject with
        transparency. Ideal for product photos and portraits.
      operationId: removeBackground
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                provider:
                  type: string
                  enum:
                    - birefnet
                    - bria
                model:
                  type: string
                version:
                  type: string
                  enum:
                    - v1
                    - v2
                v2_model:
                  type: string
                operating_resolution:
                  type: string
                  enum:
                    - 1024x1024
                    - 2048x2048
                    - 2304x2304
                image_width:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                image_height:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                source_asset_id:
                  type: string
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully removed background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Remove background from image
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/upscale:
    post:
      description: Upscale an image to a higher resolution using AI-powered super-resolution.
      operationId: upscaleImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                scale:
                  default: 2
                  type: number
                  minimum: 1
                  maximum: 10
                model:
                  default: esrgan
                  type: string
                  enum:
                    - esrgan
                    - clarity
                    - topaz
                    - seedvr
                upscale_mode:
                  type: string
                  enum:
                    - target
                    - factor
                target_resolution:
                  type: string
                  enum:
                    - 720p
                    - 1080p
                    - 1440p
                    - 2160p
                image_width:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                image_height:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                prompt:
                  type: string
                creativity:
                  type: number
                  minimum: 0
                  maximum: 1
                resemblance:
                  type: number
                  minimum: 0
                  maximum: 1
                topaz_model:
                  type: string
                  enum:
                    - standard
                    - highFidelity
                    - recovery
                    - lowRes
                    - cgi
                    - textRefine
                    - redefine
                face_enhancement:
                  type: boolean
                face_enhancement_strength:
                  type: number
                  minimum: 0
                  maximum: 1
                face_enhancement_creativity:
                  type: number
                  minimum: 0
                  maximum: 1
                noise_scale:
                  type: number
                  minimum: 0
                  maximum: 1
                seed:
                  type: number
                asset_id:
                  type: string
              required:
                - image_url
              additionalProperties: false
              dependentRequired:
                image_width:
                  - image_height
                image_height:
                  - image_width
      responses:
        "200":
          description: Successfully upscaled image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Upscale image resolution
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/generate:
    post:
      description: Generate images from a text description using Sirv AI Studio image models.
      operationId: generateImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 2000
                model:
                  default: nano-banana-2-lite
                  type: string
                  enum:
                    - nano-banana-2-lite
                    - nano-banana-2
                    - flux2
                    - zimage
                    - gemini
                    - gemini-or
                    - seedream
                    - seedream-or
                    - gpt-image-2
                aspect_ratio:
                  default: landscape_4_3
                  type: string
                num_images:
                  default: 1
                  type: integer
                  minimum: 1
                  maximum: 4
                resolution:
                  type: string
                  enum:
                    - 1K
                    - 2K
                    - 4K
                image_size:
                  type: string
                  enum:
                    - 1024x1024
                    - 1536x1024
                    - 1024x1536
                quality:
                  type: string
                  enum:
                    - low
                    - medium
                    - high
                background:
                  type: string
                  enum:
                    - auto
                    - transparent
                    - opaque
                seed:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
              required:
                - prompt
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate image from text
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/image-to-image:
    post:
      description: Transform an existing image based on a text prompt while preserving useful source-image
        context.
      operationId: imageToImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                prompt:
                  type: string
                strength:
                  default: 0.85
                  type: number
                  minimum: 0
                  maximum: 1
                model:
                  default: nano-banana-lite-edit
                  type: string
                  enum:
                    - nano-banana-lite-edit
                    - nano-banana-2-edit
                    - flux2-edit
                    - qwen-integrate-product
                    - qwen-multiple-angles
                    - qwen-remove-lighting
                    - seedream-edit
                    - reve-fast-edit
                    - gpt-image-2-edit
                    - zimage-i2i
                horizontal_angle:
                  type: number
                  minimum: 0
                  maximum: 360
                vertical_angle:
                  type: number
                  minimum: -30
                  maximum: 90
                zoom:
                  type: number
                  minimum: 0
                  maximum: 10
                lora_scale:
                  type: number
                  minimum: 0
                  maximum: 1
                ref_image_url:
                  type: string
                  format: uri
                image_size:
                  type: string
                  enum:
                    - auto
                    - 1024x1024
                    - 1536x1024
                    - 1024x1536
                quality:
                  type: string
                  enum:
                    - low
                    - medium
                    - high
                background:
                  type: string
                  enum:
                    - auto
                    - transparent
                    - opaque
                input_fidelity:
                  type: string
                  enum:
                    - low
                    - high
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully transformed image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Transform image with text prompt
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/image-translation:
    post:
      description: Translate visible text in an image while preserving the original layout, typography,
        and image style.
      operationId: translateImageText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                source_language:
                  type: string
                target_language:
                  type: string
                  minLength: 1
                model:
                  default: nano-banana-lite-edit
                  type: string
                  enum:
                    - nano-banana-lite-edit
                    - gemini
                    - gpt-image-2-edit
                    - seedream-edit
              required:
                - image_url
                - target_language
              additionalProperties: false
      responses:
        "200":
          description: Successfully translated image text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Translate text in image
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/background-replace:
    post:
      description: Replace the background of an image while keeping the foreground subject intact.
      operationId: replaceBackground
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                prompt:
                  type: string
                ref_image_url:
                  type: string
                  format: uri
                color:
                  type: string
                  pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
                color_mode:
                  default: smart
                  type: string
                  enum:
                    - smart
                    - simple
                model:
                  default: nano-banana-lite
                  type: string
                  enum:
                    - nano-banana-lite
                    - solid-color
                    - bria
                    - flux-kontext
                image_width:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                image_height:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully replaced background
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Replace image background
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/object-removal:
    post:
      description: Remove unwanted objects or fill a masked area with a prompt using AI inpainting.
      operationId: removeObjects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - mask_url
              additionalProperties: false
              properties:
                image_url:
                  type: string
                  format: uri
                  description: HTTPS URL of the source image.
                mask_url:
                  type: string
                  format: uri
                  description: HTTPS URL of the mask image.
                operation:
                  type: string
                  enum:
                    - object-removal
                    - generative-fill
                  default: object-removal
                  description: Use generative-fill, or set mode to fill, to fill the masked area with a prompt.
                mode:
                  type: string
                  enum:
                    - remove
                    - fill
                  default: remove
                model:
                  type: string
                  enum:
                    - qwen-inpaint
                    - bria-genfill
                    - gpt-image-2-edit
                  default: qwen-inpaint
                  description: Remove mode uses qwen-inpaint. Fill mode defaults to bria-genfill and also accepts
                    gpt-image-2-edit.
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  description: Required when operation is generative-fill or mode is fill. Describe what should appear
                    inside the masked area.
                image_width:
                  type: integer
                  minimum: 1
                image_height:
                  type: integer
                  minimum: 1
      responses:
        "200":
          description: Successfully edited masked area
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Remove or fill masked image areas
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/alt-text:
    post:
      description: Generate descriptive alt text for an image using AI vision models.
      operationId: generateAltText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                detail_level:
                  default: detailed-caption
                  type: string
                  enum:
                    - caption
                    - detailed-caption
                    - more-detailed-caption
                model:
                  default: florence
                  type: string
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated alt text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AltTextResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate alt text for image
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/product-description:
    post:
      description: Generate product copy from product details, an optional product image, writing
        controls, and workspace brand context.
      operationId: generateProductDescription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  pattern: \S
                brand:
                  type: string
                category:
                  type: string
                features:
                  type: string
                language:
                  default: en
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                    - pt
                    - nl
                    - pl
                    - uk
                    - ja
                    - zh
                    - ko
                length:
                  default: medium
                  type: string
                  enum:
                    - short
                    - medium
                    - long
                price:
                  type: string
                specs:
                  type: string
                style:
                  default: professional
                  type: string
                  enum:
                    - professional
                    - casual
                    - luxury
                    - technical
                targetAudience:
                  type: string
                imageUrl:
                  type: string
                  format: uri
              additionalProperties: false
              anyOf:
                - required:
                    - name
                - required:
                    - imageUrl
      responses:
        "200":
          description: Successfully generated product description
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductDescriptionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Generate product description
      tags:
        - AI text tools
      x-sirv-credits:
        required: true
  /api/fal/document-summary:
    post:
      description: Fetch a PDF, DOCX, or text document from a safe URL and generate a summary with
        optional length, format, language, and focus controls.
      operationId: summarizeDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - document_url
              additionalProperties: false
              properties:
                document_url:
                  type: string
                  format: uri
                focus:
                  type: string
                  maxLength: 200
                format:
                  default: paragraph
                  type: string
                  enum:
                    - paragraph
                    - bullets
                    - sections
                language:
                  default: en
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                    - pt
                    - nl
                    - pl
                    - uk
                    - ja
                    - zh
                    - ko
                length:
                  default: standard
                  type: string
                  enum:
                    - brief
                    - standard
                    - detailed
      responses:
        "200":
          description: Successfully summarized document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentSummaryResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Summarize document
      tags:
        - AI text tools
      x-sirv-credits:
        required: true
  /api/fal/pdf-translation:
    post:
      description: Fetch a PDF from a safe URL and return a translated PDF in translated-only or bilingual
        output mode.
      operationId: translatePdf
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - document_url
                - target_language
              additionalProperties: false
              properties:
                document_url:
                  type: string
                  format: uri
                mode:
                  default: translated
                  type: string
                  enum:
                    - translated
                    - bilingual
                source_language:
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                    - pt
                    - nl
                    - pl
                    - uk
                    - ja
                    - zh
                    - ko
                    - ar
                    - hi
                    - tr
                    - vi
                    - th
                    - id
                    - cs
                    - ru
                    - sv
                    - da
                    - no
                    - fi
                    - el
                    - he
                    - hu
                    - ro
                    - sk
                    - bg
                    - hr
                    - sr
                    - sl
                    - lt
                    - lv
                    - et
                    - ms
                    - tl
                    - bn
                    - ta
                    - te
                    - mr
                    - gu
                    - kn
                    - ml
                    - pa
                    - ur
                    - fa
                    - sw
                    - af
                target_language:
                  type: string
                  enum:
                    - en
                    - es
                    - fr
                    - de
                    - it
                    - pt
                    - nl
                    - pl
                    - uk
                    - ja
                    - zh
                    - ko
                    - ar
                    - hi
                    - tr
                    - vi
                    - th
                    - id
                    - cs
                    - ru
                    - sv
                    - da
                    - no
                    - fi
                    - el
                    - he
                    - hu
                    - ro
                    - sk
                    - bg
                    - hr
                    - sr
                    - sl
                    - lt
                    - lv
                    - et
                    - ms
                    - tl
                    - bn
                    - ta
                    - te
                    - mr
                    - gu
                    - kn
                    - ml
                    - pa
                    - ur
                    - fa
                    - sw
                    - af
      responses:
        "200":
          description: Successfully translated PDF
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PdfTranslationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Translate PDF
      tags:
        - AI text tools
      x-sirv-credits:
        required: true
  /api/fal/expand-prompt:
    post:
      description: Expand a short prompt into detailed instructions for supported Studio AI workflows,
        optionally using safe image context and workspace brand context.
      operationId: expandPrompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - taskType
              additionalProperties: false
              properties:
                imageUrl:
                  type: string
                  format: uri
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 1000
                taskType:
                  type: string
                  enum:
                    - brand-context
                    - video-generation
                    - image-generation
                    - image-editing
                    - background-replace
                    - product-lifestyle
      responses:
        "200":
          description: Successfully expanded prompt
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptExpansionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Expand prompt
      tags:
        - AI text tools
      x-sirv-credits:
        required: true
  /api/fal/ai-router:
    post:
      description: Classify an image into one of the caller-provided branch names for workflow routing
        decisions.
      operationId: classifyImageRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - prompt
                - branches
              additionalProperties: false
              properties:
                image_url:
                  type: string
                  format: uri
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 4000
                branches:
                  type: array
                  minItems: 2
                  maxItems: 20
                  items:
                    type: object
                    required:
                      - id
                      - name
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        minLength: 1
                        maxLength: 80
                      name:
                        type: string
                        minLength: 1
                        maxLength: 80
                      description:
                        type: string
                        maxLength: 240
                fallback_branch:
                  type: string
                  description: Optional fallback branch name. Must match one of the supplied branch names.
                  minLength: 1
                  maxLength: 80
                model:
                  type: string
                  enum:
                    - gemini-flash
                    - gemini-3-flash
                    - qwen-vl-8b
                  default: gemini-flash
      responses:
        "200":
          description: Successfully classified image route
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AiRouterResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Classify image route
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/image-review:
    post:
      description: Run product-image quality rules against one or more image URLs and return per-image
        pass/fail results with summary counts.
      operationId: reviewImageQuality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_urls
                - rules
              additionalProperties: false
              properties:
                image_urls:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: uri
                rules:
                  type: array
                  minItems: 1
                  items:
                    oneOf:
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - minWidth
                          - minHeight
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: min_dimension
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          minWidth:
                            type: number
                          minHeight:
                            type: number
                          match:
                            type: string
                            enum:
                              - both
                              - either
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - maxWidth
                          - maxHeight
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: max_dimension
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          maxWidth:
                            type: number
                          maxHeight:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - allowed
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: aspect_ratio
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          allowed:
                            type: array
                            items:
                              type: string
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - maxBytes
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: file_size
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          maxBytes:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - allowed
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: file_format
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          allowed:
                            type: array
                            items:
                              type: string
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - allowed
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: video_codec
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          allowed:
                            type: array
                            items:
                              type: string
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - tolerance
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: background_white
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          tolerance:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - minPercent
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: frame_fill
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          minPercent:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: no_watermark
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - tolerance
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: centered_subject
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          tolerance:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - minMargin
                          - maxMargin
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: whitespace_margin
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          minMargin:
                            type: number
                          maxMargin:
                            type: number
                          horizontalMinMargin:
                            type: number
                          horizontalMaxMargin:
                            type: number
                          verticalMinMargin:
                            type: number
                          verticalMaxMargin:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: no_overexposure
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: no_shadows
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - rejectBelow
                          - enhanceBelow
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: blur_quality
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          rejectBelow:
                            type: number
                          enhanceBelow:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - minScore
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: low_detail_quality
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          minScore:
                            type: number
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - backgroundWhiteThreshold
                          - minContrastThreshold
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: white_on_white
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          backgroundWhiteThreshold:
                            type: number
                          minContrastThreshold:
                            type: number
                          autofixBackgroundColor:
                            type: string
                            pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
                      - type: object
                        required:
                          - id
                          - type
                          - enabled
                          - allowed
                          - untagged
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                          type:
                            const: color_profile
                          enabled:
                            type: boolean
                          mediaTypes:
                            type: array
                            items:
                              type: string
                              enum:
                                - image
                                - video
                          allowed:
                            type: array
                            minItems: 1
                            items:
                              type: string
                              enum:
                                - srgb
                                - display-p3
                                - adobe-rgb
                            description: Accepted embedded colour profile families. CMYK never passes. Images without persisted
                              colour metadata are reported as skipped, not passed.
                          untagged:
                            type: string
                            enum:
                              - pass
                              - fail
                            description: Policy for images whose original upload had no embedded profile.
                    discriminator:
                      propertyName: type
                strict_mode:
                  type: boolean
                  default: true
                pass_threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                ai_model:
                  type: string
                  enum:
                    - gemini
                    - qwen-vl-8b
                    - qwen-vl-235b
                    - gemini-flash
                    - gemini-3-flash
                  default: qwen-vl-8b
      responses:
        "200":
          description: Successfully reviewed image quality
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageReviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Review image quality
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/depth-map:
    post:
      description: Generate a depth map from an image showing relative distances. Lighter areas are
        closer; darker areas are farther.
      operationId: generateDepthMap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                image_width:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                image_height:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                asset_id:
                  type: string
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated depth map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate depth map
      tags:
        - AI image tools
  /api/fal/product-lifestyle:
    post:
      description: Place a product in a realistic lifestyle scene for marketing and commerce content.
      operationId: createProductLifestyle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                scene_description:
                  type: string
                ref_image_url:
                  type: string
                  format: uri
                model:
                  default: nano-banana-lite
                  type: string
                  enum:
                    - nano-banana-lite
                    - gemini
                    - gpt-image-2
                    - bria
                    - seedream
                    - flux2
                placement_type:
                  default: manual_placement
                  type: string
                  enum:
                    - original
                    - automatic
                    - manual_placement
                    - manual_padding
                position:
                  default: bottom_center
                  type: string
                  enum:
                    - bottom_center
                    - bottom_left
                    - bottom_right
                    - upper_center
                    - upper_left
                    - upper_right
                    - center_vertical
                    - center_horizontal
                    - left_center
                    - right_center
                shot_size:
                  default:
                    - 1000
                    - 1000
                  type: array
                  prefixItems:
                    - type: number
                    - type: number
                num_results:
                  default: 1
                  type: number
                  minimum: 1
                  maximum: 4
              required:
                - image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully created lifestyle shots
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Create product lifestyle shot
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/virtual-try-on:
    post:
      description: Virtually try clothing on a person using AI.
      operationId: virtualTryOn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                person_image_url:
                  type: string
                  format: uri
                garment_image_url:
                  type: string
                  format: uri
                model:
                  default: fal
                  type: string
                  enum:
                    - fal
                    - gemini
                    - gpt
                    - flux
                    - fashn
                    - fibo
                    - fibo-holding
              required:
                - person_image_url
                - garment_image_url
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated try-on image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Virtual clothing try-on
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/image-to-3d:
    post:
      description: Convert a 2D image into a 3D model and return the generated model assets.
      operationId: imageTo3d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                image_urls:
                  minItems: 1
                  maxItems: 4
                  type: array
                  items:
                    type: string
                    format: uri
                model:
                  default: meshy
                  type: string
                  enum:
                    - meshy
                    - meshy-multi
                    - seed3d
                    - trellis
                    - trellis2
                    - hunyuan3d
                topology:
                  type: string
                  enum:
                    - triangle
                    - quad
                target_polycount:
                  type: number
                  minimum: 100
                  maximum: 300000
                enable_pbr:
                  type: boolean
                texture_size:
                  type: number
                generate_type:
                  type: string
                  enum:
                    - Normal
                    - LowPoly
                    - Geometry
                face_count:
                  type: number
                  minimum: 40000
                  maximum: 1500000
                resolution:
                  type: string
                  enum:
                    - "512"
                    - "1024"
                    - "1536"
                ss_sampling_steps:
                  type: number
                  minimum: 1
                  maximum: 50
                ss_guidance_strength:
                  type: number
                  minimum: 0
                  maximum: 10
                remesh:
                  type: boolean
                decimation_target:
                  type: number
                  minimum: 100000
                  maximum: 2000000
                seed:
                  type: number
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated 3D model
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Model3DResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Convert image to 3D model
      tags:
        - AI image tools
      x-sirv-credits:
        required: true
  /api/fal/glb-optimize:
    post:
      description: Optimize a binary .glb model up to 100 MB with mesh cleanup, Draco compression,
        optional simplification, and optional texture compression.
      operationId: optimizeGlb
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - glb_url
              additionalProperties: false
              properties:
                glb_url:
                  type: string
                  format: uri
                  description: HTTPS URL of a binary .glb file up to 100 MB.
                simplify_ratio:
                  default: 1
                  type: number
                  minimum: 0
                  maximum: 1
                simplify_error:
                  default: 0.001
                  type: number
                  minimum: 0
                  maximum: 1
                dedup:
                  default: true
                  type: boolean
                prune:
                  default: true
                  type: boolean
                draco:
                  default: true
                  type: boolean
                instance:
                  default: true
                  type: boolean
                flatten:
                  default: true
                  type: boolean
                join:
                  default: true
                  type: boolean
                weld:
                  default: true
                  type: boolean
                quantize:
                  default: true
                  type: boolean
                texture_format:
                  default: null
                  type:
                    - string
                    - "null"
                  enum:
                    - jpeg
                    - png
                    - webp
                    - avif
                    - null
                texture_size:
                  default: null
                  oneOf:
                    - const: 256
                    - const: 512
                    - const: 1024
                    - const: 2048
                    - const: 4096
                    - type: "null"
      responses:
        "200":
          description: Successfully optimized GLB model
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlbOptimizeResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Optimize GLB model
      tags:
        - AI 3D tools
      x-sirv-credits:
        required: true
        cost: 2
  /api/fal/video-generation:
    post:
      description: Generate a video from a text prompt or starting image using AI.
      operationId: generateVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  format: uri
                image_urls:
                  type: array
                  items:
                    type: string
                    format: uri
                prompt:
                  type: string
                  minLength: 1
                model:
                  default: veo31
                  type: string
                  enum:
                    - veo31
                    - veo31ref
                    - ltx
                    - kling
                    - kling-v3
                    - kling-v3-pro
                    - seedance-2-fast
                    - h3-max
                duration:
                  type: string
                resolution:
                  type: string
                aspect_ratio:
                  type: string
                generate_audio:
                  type: boolean
              required:
                - prompt
              additionalProperties: false
      responses:
        "200":
          description: Successfully generated video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Generate video from text or image
      tags:
        - AI video tools
      x-sirv-credits:
        required: true
  /api/fal/video-upscale:
    post:
      description: Upscale supplier videos to listing quality.
      operationId: upscaleVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
                - source_width
                - source_height
                - source_duration_seconds
              additionalProperties: false
              properties:
                video_url:
                  type: string
                  format: uri
                  description: HTTPS URL of the source video.
                model:
                  type: string
                  enum:
                    - seedvr-video
                    - topaz-video
                  default: topaz-video
                scale:
                  type: integer
                  enum:
                    - 2
                    - 4
                  default: 2
                target_resolution:
                  type: string
                  enum:
                    - auto
                    - 720p
                    - 1080p
                    - 1440p
                    - 2160p
                  default: auto
                source_width:
                  type: integer
                  minimum: 16
                  maximum: 7680
                source_height:
                  type: integer
                  minimum: 16
                  maximum: 7680
                source_duration_seconds:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 300
                source_frame_rate:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 120
                  default: 30
                asset_id:
                  type: string
                source_asset_id:
                  type: string
      responses:
        "200":
          description: Successfully upscaled video
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/InsufficientCredits"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
        "503":
          $ref: "#/components/responses/MeteringUnavailable"
      security:
        - bearerAuth: []
      summary: Upscale video resolution
      tags:
        - AI video tools
      x-sirv-credits:
        required: true
  /api/user/usage/stats:
    get:
      description: Get current credit usage statistics for the authenticated account.
      operationId: getUsageStats
      responses:
        "200":
          description: Successfully retrieved usage stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageStatsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"
      security:
        - bearerAuth: []
      summary: Get usage statistics
      tags:
        - Account
components:
  headers:
    XRateLimitLimit:
      description: Maximum requests allowed in the current rate-limit window.
      schema:
        type: integer
        minimum: 0
    XRateLimitRemaining:
      description: Requests remaining in the current rate-limit window.
      schema:
        type: integer
        minimum: 0
    XRateLimitReset:
      description: Unix timestamp, in seconds, when the rate-limit window resets.
      schema:
        type: integer
        minimum: 0
    RetryAfter:
      description: Seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    Forbidden:
      description: Request forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    InsufficientCredits:
      description: Insufficient credits
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    MeteringUnavailable:
      description: Programmatic request metering temporarily unavailable
      headers:
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    WorkspaceCapabilityRequired:
      description: Workspace capability required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
        X-RateLimit-Limit:
          $ref: "#/components/headers/XRateLimitLimit"
        X-RateLimit-Remaining:
          $ref: "#/components/headers/XRateLimitRemaining"
        X-RateLimit-Reset:
          $ref: "#/components/headers/XRateLimitReset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
  schemas:
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Stable machine-readable error code when available.
        details:
          description: Optional structured context for validation or provider failures.
        eventId:
          type: string
          description: Sentry event identifier for server-side failures when available.
        retryAfterMs:
          type: integer
          minimum: 0
          description: Suggested retry delay in milliseconds when available.
        retryable:
          type: boolean
          description: Whether the caller can retry the failed request.
    UrlResource:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Public URL for the generated or processed resource.
    SupplierSlotsResponse:
      type: object
      properties:
        template:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                slots:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                      position:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      label:
                        type: string
                      required:
                        type: boolean
                      mediaTypes:
                        type: array
                        items:
                          type: string
                      availability:
                        type: object
                        properties:
                          available:
                            type: boolean
                          reason:
                            anyOf:
                              - type: string
                                enum:
                                  - SLOT_OCCUPIED
                                  - SLOT_NOT_DEFINED
                              - type: "null"
                        required:
                          - available
                          - reason
                        additionalProperties: false
                    required:
                      - role
                      - position
                      - availability
                    additionalProperties: {}
                namingPattern:
                  anyOf:
                    - type: string
                    - type: "null"
              required:
                - id
                - name
                - slots
              additionalProperties: {}
            - type: "null"
        roleFill:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: object
            properties:
              total:
                type: number
              filled:
                type: number
            required:
              - total
              - filled
            additionalProperties: false
        uploadRequirements:
          type: object
          properties:
            maxFileSizeBytes:
              type: object
              properties:
                image:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                video:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
              required:
                - image
                - video
              additionalProperties: false
            accept:
              type: string
            contentValidation:
              type: string
              const: server
          required:
            - maxFileSizeBytes
            - accept
            - contentValidation
          additionalProperties: false
      required:
        - template
        - roleFill
        - uploadRequirements
      additionalProperties: false
    SupplierResolveResponse:
      type: object
      properties:
        matched:
          type: array
          items:
            type: object
            properties:
              clientFileId:
                type: string
              filename:
                type: string
              productId:
                type: string
              role:
                type: string
              position:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              availability:
                type: object
                properties:
                  available:
                    type: boolean
                  reason:
                    anyOf:
                      - type: string
                        enum:
                          - SLOT_OCCUPIED
                          - SLOT_NOT_DEFINED
                      - type: "null"
                required:
                  - available
                  - reason
                additionalProperties: false
              mediaTypes:
                type: array
                items:
                  type: string
            required:
              - clientFileId
              - filename
              - productId
              - role
              - position
              - availability
            additionalProperties: {}
        unmatched:
          type: array
          items:
            type: object
            properties:
              clientFileId:
                type: string
              filename:
                type: string
            required:
              - clientFileId
              - filename
            additionalProperties: {}
        blocked:
          type: array
          items:
            type: object
            properties:
              clientFileId:
                type: string
              filename:
                type: string
            required:
              - clientFileId
              - filename
            additionalProperties: {}
        ambiguous:
          type: array
          items:
            type: object
            properties:
              clientFileId:
                type: string
              filename:
                type: string
            required:
              - clientFileId
              - filename
            additionalProperties: {}
        products:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              sku:
                anyOf:
                  - type: string
                  - type: "null"
            required:
              - id
              - name
            additionalProperties: false
        uploadRequirements:
          type: object
          properties:
            maxFileSizeBytes:
              type: object
              properties:
                image:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                video:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
              required:
                - image
                - video
              additionalProperties: false
            accept:
              type: string
            contentValidation:
              type: string
              const: server
          required:
            - maxFileSizeBytes
            - accept
            - contentValidation
          additionalProperties: false
      required:
        - matched
        - unmatched
        - blocked
        - products
        - uploadRequirements
      additionalProperties: {}
    SupplierPresignResponse:
      type: object
      properties:
        assetId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        r2Key:
          type: string
        presignedUrl:
          type: string
        filename:
          type: string
        expiresAt:
          type: number
        previewR2Key:
          type: string
        previewPresignedUrl:
          type: string
      required:
        - assetId
        - r2Key
        - presignedUrl
        - filename
        - expiresAt
      additionalProperties: false
    SupplierConfirmResponse:
      type: object
      properties:
        assetId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        committed:
          type: boolean
          const: true
        operationId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        processing:
          type: string
          enum:
            - queued
            - complete
        outcome:
          type: string
        validationRejected:
          type: boolean
        rejectionReason:
          type: string
        url:
          type: string
        r2Key:
          anyOf:
            - type: string
            - type: "null"
      required:
        - assetId
        - committed
        - operationId
        - url
      additionalProperties: {}
    SupplierProductsResponse:
      type: object
      properties:
        products:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              product:
                anyOf:
                  - type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      sku:
                        anyOf:
                          - type: string
                          - type: "null"
                    required:
                      - id
                      - name
                      - sku
                    additionalProperties: {}
                  - type: "null"
            required:
              - id
              - product
            additionalProperties: {}
        total:
          type: number
        hasMore:
          type: boolean
      required:
        - products
        - total
      additionalProperties: {}
    SupplierSubmissionResponse:
      type: object
      properties:
        submission:
          type: object
          properties:
            id:
              type: string
            product:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                  required:
                    - id
                  additionalProperties: {}
                - type: "null"
            role:
              anyOf:
                - type: string
                - type: "null"
            position:
              anyOf:
                - type: number
                - type: "null"
          required:
            - id
          additionalProperties: {}
      required:
        - submission
      additionalProperties: false
    ImageResponse:
      type: object
      properties:
        image:
          $ref: "#/components/schemas/UrlResource"
    MultiImageResponse:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: "#/components/schemas/UrlResource"
    VideoResponse:
      type: object
      properties:
        video:
          $ref: "#/components/schemas/UrlResource"
    Model3DResponse:
      type: object
      properties:
        fbx:
          $ref: "#/components/schemas/UrlResource"
        glb:
          $ref: "#/components/schemas/UrlResource"
        obj:
          $ref: "#/components/schemas/UrlResource"
        thumbnail:
          $ref: "#/components/schemas/UrlResource"
        usdz:
          $ref: "#/components/schemas/UrlResource"
    AltTextResponse:
      type: object
      properties:
        caption:
          type: string
          description: Generated alt text or caption.
    AiRouterResponse:
      type: object
      required:
        - selectedBranch
        - model
        - modelId
      additionalProperties: false
      properties:
        selectedBranch:
          type: string
          description: Selected branch name from the supplied branch list.
        reasoning:
          type: string
          description: Optional model reasoning for the selected branch.
        model:
          type: string
          enum:
            - gemini-flash
            - gemini-3-flash
            - qwen-vl-8b
        modelId:
          type: string
          description: Provider model identifier used for classification.
    ProductDescriptionResponse:
      type: object
      required:
        - description
        - style
        - length
        - language
        - brandContext
      properties:
        brandContext:
          oneOf:
            - type: object
              additionalProperties: true
            - type: "null"
          description: Workspace brand context metadata applied to the prompt, or null.
        description:
          type: string
          description: Generated product description text.
        language:
          type: string
          description: Language used for the generated description.
        length:
          type: string
          enum:
            - short
            - medium
            - long
          description: Requested product description length.
        style:
          type: string
          enum:
            - professional
            - casual
            - luxury
            - technical
          description: Requested writing style.
    DocumentSummaryResponse:
      type: object
      required:
        - summary
        - metadata
      additionalProperties: false
      properties:
        summary:
          type: string
          description: Generated document summary.
        keyPoints:
          type: array
          description: Optional extracted key points for bullet or section summaries.
          items:
            type: string
        metadata:
          type: object
          required:
            - documentType
            - originalLength
            - summaryLength
          additionalProperties: false
          properties:
            documentType:
              type: string
              description: Detected document type label.
            originalLength:
              type: number
              description: Source text character count before summary generation.
            summaryLength:
              type: number
              description: Generated summary character count.
            truncated:
              type: boolean
              description: Whether source text was truncated before summary generation.
    PdfTranslationResponse:
      type: object
      required:
        - document
        - pageCount
        - mode
      additionalProperties: false
      properties:
        document:
          type: object
          required:
            - url
          additionalProperties: false
          properties:
            url:
              type: string
              format: uri
              description: Temporary URL for the translated PDF.
        pageCount:
          type: number
          description: Number of pages processed in the source PDF.
        mode:
          type: string
          enum:
            - translated
            - bilingual
          description: Translation layout mode used for the output PDF.
    GlbOptimizeResponse:
      type: object
      required:
        - optimizedUrl
        - originalSize
        - optimizedSize
        - reductionPercent
        - vertexCount
        - triangleCount
      additionalProperties: false
      properties:
        optimizedUrl:
          type: string
          format: uri
          description: Temporary URL for the optimized GLB model.
        originalSize:
          type: number
          minimum: 0
          description: Source GLB size in bytes.
        optimizedSize:
          type: number
          minimum: 0
          description: Optimized GLB size in bytes.
        reductionPercent:
          type: number
          description: Rounded percentage file-size reduction.
        vertexCount:
          type: object
          required:
            - before
            - after
          additionalProperties: false
          properties:
            before:
              type: number
              minimum: 0
            after:
              type: number
              minimum: 0
        triangleCount:
          type: object
          required:
            - before
            - after
          additionalProperties: false
          properties:
            before:
              type: number
              minimum: 0
            after:
              type: number
              minimum: 0
    PromptExpansionResponse:
      type: object
      required:
        - brandContext
        - expandedPrompt
        - model
        - modelId
      additionalProperties: false
      properties:
        brandContext:
          anyOf:
            - type: object
              additionalProperties: true
            - type: "null"
          description: Workspace brand context metadata applied to the prompt, or null.
        expandedPrompt:
          type: string
          description: Expanded prompt text.
        model:
          type: string
          enum:
            - prompt-expansion
          description: Studio model key charged for this request.
        modelId:
          type: string
          description: Provider model identifier used for prompt expansion.
    ImageReviewRuleResult:
      type: object
      required:
        - ruleId
        - ruleType
        - passed
        - message
      additionalProperties: false
      properties:
        ruleId:
          type: string
          description: Identifier of the rule that produced this result.
        ruleType:
          type: string
          description: Image review rule type, such as min_dimension or no_watermark.
        passed:
          type: boolean
          description: Whether this individual rule passed for the image.
        message:
          type: string
          description: Human-readable rule outcome.
        details:
          type: object
          additionalProperties: true
          description: Optional structured details from deterministic or AI-backed checks.
        skipped:
          type: boolean
          description: True when the rule could not be evaluated for this image (for example a colour profile
            check without colour metadata). Never counts as a pass.
    ImageReviewResult:
      type: object
      required:
        - imageUrl
        - passed
        - ruleResults
        - score
      additionalProperties: false
      properties:
        imageUrl:
          type: string
          format: uri
          description: Reviewed source image URL.
        passed:
          type: boolean
          description: Whether the image passed the requested rule set.
        ruleResults:
          type: array
          description: Per-rule review outcomes for this image.
          items:
            $ref: "#/components/schemas/ImageReviewRuleResult"
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Normalized pass score for the image.
        analysisMode:
          type: string
          enum:
            - full
            - metadata_only
            - metadata_unavailable
          description: How much deterministic analysis was available for the image.
        analysisWarning:
          type:
            - string
            - "null"
          description: Warning explaining degraded analysis, when present.
        rulesetFingerprint:
          type:
            - string
            - "null"
          description: Stable fingerprint of the evaluated rule set, when available.
        skippedRules:
          type: array
          description: Rules that could not be evaluated for this image. Reported separately and excluded from
            ruleResults and score.
          items:
            $ref: "#/components/schemas/ImageReviewRuleResult"
    ImageReviewResponse:
      type: object
      required:
        - results
        - passed
        - failed
        - skipped
        - summary
      additionalProperties: false
      properties:
        results:
          type: array
          description: Per-image review results.
          items:
            $ref: "#/components/schemas/ImageReviewResult"
        passed:
          type: array
          description: Image URLs that passed the requested rule set.
          items:
            type: string
            format: uri
        failed:
          type: array
          description: Image URLs that failed the requested rule set.
          items:
            type: string
            format: uri
        skipped:
          type: array
          description: Image URLs where no rule could be evaluated. Never counted as passed.
          items:
            type: string
            format: uri
        summary:
          type: object
          required:
            - total
            - passedCount
            - failedCount
            - skippedCount
            - passRate
          additionalProperties: false
          properties:
            total:
              type: integer
              minimum: 0
              description: Number of image URLs reviewed.
            passedCount:
              type: integer
              minimum: 0
              description: Number of images that passed.
            failedCount:
              type: integer
              minimum: 0
              description: Number of images that failed.
            skippedCount:
              type: integer
              minimum: 0
              description: Number of images where no rule could be evaluated.
            passRate:
              type: number
              minimum: 0
              maximum: 1
              description: Passed image count divided by total image count.
    UsageStatsResponse:
      type: object
      properties:
        stats:
          type: object
          properties:
            remaining:
              type: integer
              description: Credits remaining in the current period.
            tier:
              type: string
              description: Subscription tier name.
            total:
              type: integer
              description: Total credits for the current period.
            used:
              type: integer
              description: Credits used in the current period.
    ZapierAuthenticatedUserResponse:
      type: object
      required:
        - id
        - email
        - credits
        - tier
      properties:
        id:
          type: string
          description: Authenticated user identifier.
        email:
          type:
            - string
            - "null"
          format: email
          description: Authenticated user email address when available.
        credits:
          type: number
          description: Credits currently available to the authenticated user.
        tier:
          type: string
          description: Stored subscription tier for the authenticated user.
    ZapierSirvSearchHit:
      type: object
      additionalProperties: false
      properties:
        basename:
          type: string
          description: File basename returned by Sirv.
        contentType:
          type: string
          description: File content type returned by Sirv.
        ctime:
          type: string
          description: File creation timestamp returned by Sirv.
        dirname:
          type: string
          description: Directory path returned by Sirv.
        extension:
          type: string
          description: File extension returned by Sirv.
        filename:
          type: string
          description: Full file path returned by Sirv.
        height:
          type: integer
          minimum: 0
          description: Image height in pixels when Sirv returns it.
        isDirectory:
          type: boolean
          description: Whether the result is a directory.
        mtime:
          type: string
          description: File modification timestamp returned by Sirv.
        size:
          type: integer
          minimum: 0
          description: File size in bytes when Sirv returns it.
        width:
          type: integer
          minimum: 0
          description: Image width in pixels when Sirv returns it.
    ZapierSirvSearchResponse:
      type: object
      required:
        - id
        - query
        - hits
        - total
        - took
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        query:
          type: string
          description: Search query that was executed.
        hits:
          type: array
          description: Stable public Sirv search hit fields returned by the Sirv API.
          items:
            $ref: "#/components/schemas/ZapierSirvSearchHit"
        total:
          type: integer
          minimum: 0
          description: Total matching files reported by Sirv.
        took:
          type: integer
          minimum: 0
          description: Search execution time reported by Sirv, in milliseconds.
    ZapierSirvFileInfo:
      type: object
      required:
        - filename
        - ctime
        - mtime
        - size
        - contentType
        - isDirectory
      additionalProperties: false
      properties:
        filename:
          type: string
          description: Full file path returned by Sirv.
        ctime:
          type: string
          description: File creation timestamp returned by Sirv.
        mtime:
          type: string
          description: File modification timestamp returned by Sirv.
        size:
          type: integer
          minimum: 0
          description: File size in bytes.
        contentType:
          type: string
          description: File content type.
        isDirectory:
          type: boolean
          description: Whether the file info describes a directory.
    ZapierSirvProductMetadata:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          maxLength: 256
          description: Sirv product metadata ID.
        name:
          type: string
          maxLength: 256
          description: Sirv product metadata name.
        brand:
          type: string
          maxLength: 256
          description: Sirv product metadata brand.
        category1:
          type: string
          maxLength: 256
          description: Primary Sirv product metadata category.
        category2:
          type: string
          maxLength: 256
          description: Secondary Sirv product metadata category.
    ZapierSirvMetadata:
      type: object
      additionalProperties: false
      properties:
        title:
          type: string
          maxLength: 256
          description: Sirv meta title.
        description:
          type: string
          maxLength: 1024
          description: Sirv meta description, commonly used as image alt text.
        tags:
          type: array
          maxItems: 50
          description: Sirv meta tags.
          items:
            type: string
            maxLength: 32
        product:
          $ref: "#/components/schemas/ZapierSirvProductMetadata"
    ZapierSirvGetMetadataResponse:
      type: object
      required:
        - id
        - file_path
        - metadata
        - file_info
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        file_path:
          type: string
          description: Validated Sirv file path used for the metadata lookup.
        metadata:
          $ref: "#/components/schemas/ZapierSirvMetadata"
        file_info:
          oneOf:
            - $ref: "#/components/schemas/ZapierSirvFileInfo"
            - type: "null"
          description: Stable Sirv file info fields, or null when the stat lookup is unavailable.
    ZapierSirvMetadataUpdateResponse:
      type: object
      required:
        - id
        - file_path
        - metadata
        - queued
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        file_path:
          type: string
          description: Validated Sirv file path queued for metadata update.
        metadata:
          $ref: "#/components/schemas/ZapierSirvMetadata"
        queued:
          type: boolean
          description: Whether the metadata update has been queued for processing.
    ZapierSirvTagsResponse:
      type: object
      required:
        - id
        - file_path
        - action
        - tags
        - queued
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        file_path:
          type: string
          description: Validated Sirv file path queued for tag update.
        action:
          type: string
          enum:
            - add
            - remove
          description: Queued tag operation.
        tags:
          type: array
          maxItems: 50
          description: Tag values queued for the operation.
          items:
            type: string
            maxLength: 32
        queued:
          type: boolean
          description: Whether the tag update has been queued for processing.
    ZapierSirvFileOperationResponse:
      type: object
      required:
        - id
        - action
        - file_path
        - queued
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        action:
          type: string
          enum:
            - rename
            - copy
            - delete
          description: Queued Sirv file operation.
        file_path:
          type: string
          description: Validated Sirv file path queued for the operation.
        target_path:
          type: string
          description: Validated destination path for rename and copy operations.
        queued:
          type: boolean
          description: Whether the file operation has been queued for processing.
    ZapierSirvFolderItem:
      type: object
      additionalProperties: false
      properties:
        filename:
          type: string
          description: Folder item filename returned by Sirv.
        dirname:
          type: string
          description: Directory path for the folder item.
        basename:
          type: string
          description: Folder item basename.
        contentType:
          type: string
          description: Folder item content type returned by Sirv.
        mtime:
          type: string
          description: File modification timestamp returned by Sirv.
        ctime:
          type: string
          description: File creation timestamp returned by Sirv.
        size:
          type: integer
          minimum: 0
          description: File size in bytes when Sirv returns it.
        isDirectory:
          type: boolean
          description: Whether the folder item is a directory.
    ZapierSirvFolderOperationResponse:
      type: object
      required:
        - id
        - action
        - folder_path
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        action:
          type: string
          enum:
            - create
            - list
          description: Sirv folder operation.
        folder_path:
          type: string
          description: Validated Sirv folder path used for the operation.
        queued:
          type: boolean
          description: Whether the folder creation has been queued for processing.
        contents:
          type: array
          description: Stable public Sirv folder item fields.
          items:
            $ref: "#/components/schemas/ZapierSirvFolderItem"
        continuation:
          oneOf:
            - type: string
            - type: "null"
          description: Sirv continuation cursor for the next page, when available.
        total:
          type: integer
          minimum: 0
          description: Number of folder items returned in this response.
    ZapierSirvUploadResponse:
      type: object
      required:
        - id
        - url
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        url:
          type: string
          format: uri
          description: Public Sirv CDN URL for the uploaded file.
        folder:
          type: string
          description: Validated destination folder when the upload used folder plus filename.
        filename:
          type: string
          description: Validated filename when the upload used folder plus filename.
        target_path:
          type: string
          description: Validated full Sirv target path when supplied.
    ZapierImageTranslationResponse:
      type: object
      required:
        - id
        - image_url
        - target_language
        - credits_used
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        image_url:
          type: string
          format: uri
          description: URL of the translated image.
        target_language:
          type: string
          description: Target language used for the translated image text.
        credits_used:
          type: number
          minimum: 0
          description: Credits charged for the translation.
    ZapierImageReviewResult:
      type: object
      required:
        - check
        - passed
        - message
      additionalProperties: false
      properties:
        check:
          type: string
          description: Stable check identifier, such as min_width or no_watermark.
        passed:
          type: boolean
          description: Whether this individual review check passed.
        message:
          type: string
          description: Human-readable review outcome for this check.
        confidence:
          type: number
          minimum: 0
          maximum: 100
          description: AI confidence score for model-backed checks, when available.
    ZapierImageReviewResponse:
      type: object
      required:
        - id
        - passed
        - results
        - summary
        - credits_used
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        passed:
          type: boolean
          description: Whether every requested review check passed.
        results:
          type: array
          description: Per-check image review results.
          items:
            $ref: "#/components/schemas/ZapierImageReviewResult"
        summary:
          type: object
          required:
            - total_checks
            - passed_checks
            - failed_checks
          additionalProperties: false
          properties:
            total_checks:
              type: integer
              minimum: 0
              description: Number of review checks executed.
            passed_checks:
              type: integer
              minimum: 0
              description: Number of review checks that passed.
            failed_checks:
              type: integer
              minimum: 0
              description: Number of review checks that failed.
        credits_used:
          type: number
          minimum: 0
          description: Credits charged for this one image-review request.
    ZapierProductDescriptionResponse:
      type: object
      required:
        - id
        - description
        - style
        - length
        - language
        - credits_used
      properties:
        id:
          type: string
          description: Zapier-compatible result identifier.
        description:
          type: string
          description: Generated product description text.
        style:
          type: string
          enum:
            - professional
            - casual
            - luxury
            - technical
          description: Requested writing style.
        length:
          type: string
          enum:
            - short
            - medium
            - long
          description: Requested product description length.
        language:
          type: string
          description: Language used for the generated description.
        credits_used:
          type: number
          minimum: 0
          description: Credits charged for the generated product description.
    Asset:
      type: object
      required:
        - id
        - url
      additionalProperties: true
      properties:
        id:
          type: string
          description: Asset identifier.
        url:
          type: string
          format: uri
          description: Public asset URL.
        filename:
          type: string
          description: Display filename.
        mimeType:
          type: string
          description: Asset MIME type.
        isFavorite:
          type: boolean
          description: Whether the asset is marked as a favorite.
    AssetListResponse:
      type: object
      required:
        - assets
        - total
      properties:
        assets:
          type: array
          items:
            $ref: "#/components/schemas/Asset"
        total:
          type: integer
          minimum: 0
          description: Total matching assets.
    AssetSearchResponse:
      type: object
      required:
        - hits
        - query
        - total
      properties:
        hits:
          type: array
          items:
            type: object
            additionalProperties: true
        query:
          type: string
          description: Search query that was executed.
        total:
          type: integer
          minimum: 0
          description: Total matching search hits.
    AssetMetadataResponse:
      type: object
      required:
        - metadata
      additionalProperties: true
      properties:
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata values keyed by field name.
        templateId:
          type:
            - string
            - "null"
          description: Applied metadata template identifier, when present.
    AssetAltTextResponse:
      type: object
      required:
        - altText
      properties:
        altText:
          type: string
          description: Generated or stored alt text.
    AssetDeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
          description: Whether the asset was deleted.
        success:
          type: boolean
          description: Whether the delete operation succeeded.
    BulkAssetOperationResponse:
      type: object
      required:
        - count
      additionalProperties: true
      properties:
        count:
          type: integer
          minimum: 0
          description: Number of assets affected.
        success:
          type: boolean
          description: Whether the bulk operation succeeded.
    Product:
      type: object
      required:
        - id
        - name
        - sku
        - status
      additionalProperties: true
      properties:
        id:
          type: string
          description: Product identifier.
        sku:
          type: string
          description: Product SKU.
        name:
          type: string
          description: Product name.
        description:
          type:
            - string
            - "null"
          description: Product description.
        status:
          type: string
          enum:
            - active
            - draft
            - archived
          description: Product lifecycle status.
        brand:
          type:
            - string
            - "null"
          description: Product brand.
        productCategory:
          type:
            - string
            - "null"
          description: Product category.
        productType:
          type:
            - string
            - "null"
          description: Product type.
        tags:
          type: array
          items:
            type: string
          description: Product tags.
    ProductWithAssets:
      type: object
      required:
        - id
        - name
        - sku
        - status
        - assets
      additionalProperties: true
      properties:
        id:
          type: string
          description: Product identifier.
        sku:
          type: string
          description: Product SKU.
        name:
          type: string
          description: Product name.
        status:
          type: string
          enum:
            - active
            - draft
            - archived
          description: Product lifecycle status.
        assetCount:
          type: integer
          minimum: 0
          description: Number of linked assets.
        assets:
          type: array
          items:
            $ref: "#/components/schemas/Asset"
    ProductListResponse:
      type: object
      required:
        - products
        - total
      additionalProperties: true
      properties:
        products:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        total:
          type: integer
          minimum: 0
          description: Total matching products.
        hasMore:
          type: boolean
          description: Whether more products are available after this page.
        totalExact:
          type: boolean
          description: Whether the total count is exact.
        nextCursor:
          type: string
          description: Cursor for the next page when cursor pagination is used.
    ProductSearchResponse:
      type: object
      required:
        - products
      additionalProperties: true
      properties:
        products:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        total:
          type: integer
          minimum: 0
          description: Total matching products when requested.
    ProductsWithAssetsResponse:
      type: object
      required:
        - products
        - total
        - hasMore
      additionalProperties: true
      properties:
        products:
          type: array
          items:
            $ref: "#/components/schemas/ProductWithAssets"
        total:
          type: integer
          minimum: 0
          description: Total matching products.
        hasMore:
          type: boolean
          description: Whether more products are available after this page.
    ProductDeleteResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the product was deleted.
        deleted:
          type: boolean
          description: Whether the delete operation removed a product.
    LinkAssetsToProductResponse:
      type: object
      additionalProperties: true
      properties:
        success:
          type: boolean
          description: Whether the link operation succeeded.
        linked:
          type: integer
          minimum: 0
          description: Number of assets linked to the product.
    BulkProductActionResponse:
      type: object
      additionalProperties: true
      properties:
        count:
          type: integer
          minimum: 0
          description: Number of products affected.
        success:
          type: boolean
          description: Whether the bulk operation succeeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth access token.
    zapierApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_*
      description: "Zapier API key using the `Authorization: Bearer sk_live_...` header."
security:
  - bearerAuth: []