openapi: 3.0.3
servers:
  - url: https://prod.api.market/api/v1/magicapi/faceswap-video-v3
info:
  title: "Faceswap Video V3 API: Swap faces in any Video"
  version: 1.0.0
  description: Use the Faceswap Video V3 API to swap faces in any video with
    advanced AI for seamless, realistic results. Supports 480p, 720p, and 4K+.
  termsOfService: https://api.market/terms
  contact:
    name: API.market Support
    url: https://api.market/support
  license:
    name: Proprietary
externalDocs:
  description: API listing on API.market
  url: https://api.market/store/magicapi/faceswap-video-v3
tags:
  - name: Face Swap (Video)
    description: Submit and track face swap jobs for videos
  - name: image-to-video
    description: Operations related to image-to-video
  - name: artificial-intelligence
    description: Operations related to artificial-intelligence
  - name: image
    description: Operations related to image
  - name: media
    description: Operations related to media
  - name: visual-recognition
    description: Operations related to visual-recognition
paths:
  /run:
    post:
      tags:
        - Face Swap (Video)
      operationId: submitFaceSwapVideoJob
      summary: Submit a face swap job for a video
      description: >
        Creates a new asynchronous video face swap job.

        Use the returned `id` to poll `/video/status/{id}` until `status`
        becomes `COMPLETED` (or `FAILED`).
      security:
        - ApiMarketKey: []
          MagicApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FaceSwapVideoRunRequest"
            examples:
              exampleRun:
                summary: Sample request
                value:
                  input:
                    swap_image: https://blog.api.market/wp-content/uploads/2025/04/a9aefac679bdbde0f70210b5dec60cf6-1.jpg
                    target_video: https://blog.api.market/wp-content/uploads/2025/04/5639717-uhd_2732_1440_25fps.mp4
      responses:
        "200":
          description: Job accepted / queued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaceSwapVideoRunResponse"
              examples:
                queuedResponse:
                  summary: Job queued
                  value:
                    id: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
                    status: IN_QUEUE
        "400":
          description: Bad request (invalid input URL or payload)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (missing/invalid API keys)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    parameters:
      - &a1
        description: API.market API Key
        in: header
        name: x-api-market-key
        value: Please Login/Signup to get an API Key
        required: true
        schema:
          type: string
  /status/{id}:
    get:
      tags:
        - Face Swap (Video)
      operationId: getFaceSwapVideoStatus
      summary: Get status for a face swap video job
      description: >
        Poll the job status using the `id` you received from `/video/run`.

        When `status` is `COMPLETED`, the result `output.video_url` will contain
        the final video URL.
      security:
        - ApiMarketKey: []
          MagicApiKey: []
      parameters:
        - $ref: "#/components/parameters/JobId"
      responses:
        "200":
          description: Current job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaceSwapVideoStatusResponse"
              examples:
                completedResponse:
                  summary: Completed job result
                  value:
                    delayTime: 17255
                    executionTime: 93418
                    id: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
                    output:
                      video_url: https://blog.api.market/wp-content/uploads/2025/04/20250421_055533_d07e51c6.mp4
                    status: COMPLETED
                    workerId: 375sfo7c8o86qf
                queuedResponse:
                  summary: Still in queue
                  value:
                    id: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
                    status: IN_QUEUE
        "401":
          description: Unauthorized (missing/invalid API keys)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    parameters:
      - *a1
components:
  securitySchemes: {}
  parameters:
    JobId:
      name: id
      in: path
      required: true
      description: The job identifier returned by `/video/run`.
      schema:
        type: string
        example: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
  schemas:
    FaceSwapVideoRunRequest:
      type: object
      required:
        - input
      properties:
        input:
          type: object
          required:
            - swap_image
            - target_video
          properties:
            swap_image:
              type: string
              format: uri
              description: Publicly accessible image URL whose face will be **copied** into
                the target video frames.
              example: https://blog.api.market/wp-content/uploads/2025/04/a9aefac679bdbde0f70210b5dec60cf6-1.jpg
            target_video:
              type: string
              format: uri
              description: Publicly accessible video URL whose subject's face will be
                **replaced** by the swap image face.
              example: https://blog.api.market/wp-content/uploads/2025/04/5639717-uhd_2732_1440_25fps.mp4
    FaceSwapVideoRunResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          description: Unique job identifier to poll with `/video/status/{id}`.
          example: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
        status:
          $ref: "#/components/schemas/JobStatus"
    FaceSwapVideoStatusResponse:
      type: object
      required:
        - id
        - status
      properties:
        delayTime:
          type: integer
          format: int64
          description: Queue waiting time in milliseconds (if available).
          example: 17255
        executionTime:
          type: integer
          format: int64
          description: Processing time in milliseconds (if available).
          example: 93418
        id:
          type: string
          description: Job identifier.
          example: 3fde20c7-6c3b-4814-91e2-ede9fcb83c82-u2
        output:
          type: object
          description: Result payload available when status is `COMPLETED`.
          properties:
            video_url:
              type: string
              format: uri
              description: URL of the generated face-swapped video.
              example: https://blog.api.market/wp-content/uploads/2025/04/20250421_055533_d07e51c6.mp4
        status:
          $ref: "#/components/schemas/JobStatus"
        workerId:
          type: string
          description: Internal worker identifier (if available).
          example: 375sfo7c8o86qf
    JobStatus:
      type: string
      description: Current state of the job.
      enum:
        - IN_QUEUE
        - IN_PROGRESS
        - COMPLETED
        - FAILED
      example: IN_QUEUE
    Error:
      type: object
      properties:
        error:
          type: string
          example: invalid_request
        message:
          type: string
          example: target_video must be a valid URL
        status:
          type: integer
          example: 400
security: {}