> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Replacement

> Replace a person in a video with a character from a reference image.

Swap a character in an input video for one shown in a reference image, preserving motion and composition. Returns a `request_id` for status polling.

<Note>
  **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check specific **limits**.
</Note>


## OpenAPI

````yaml openapi-v2.json POST /api/v2/videos/replacements
openapi: 3.0.0
info:
  title: deAPI REST API
  description: >-
    Decentralized AI inference API for image generation, video processing, audio
    transcription, and more.
  contact:
    name: deAPI Support
    url: https://deapi.ai
    email: support@deapi.ai
  version: 0.0.1
servers:
  - url: https://api.deapi.ai
    description: Production API Server base URL
security:
  - bearerAuth: []
tags:
  - name: Client API v2
    description: Current client endpoints (OpenAI-aligned noun-based paths)
paths:
  /api/v2/videos/replacements:
    post:
      tags:
        - Client API v2
      description: >-
        Replace a person in the input video with the character from a reference
        image.
      operationId: replaceVideoCharacter
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
      requestBody:
        description: Video replace parameters
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VideoReplaceRequestBody'
      responses:
        '200':
          description: ID of the inference request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRequestResponseResource'
        '401':
          description: Unauthorized user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error_default'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error_default'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      security:
        - bearerAuth: []
components:
  parameters:
    AcceptHeader:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        default: application/json
        enum:
          - application/json
  schemas:
    VideoReplaceRequestBody:
      required:
        - video
        - ref_image
        - model
      properties:
        video:
          description: >-
            Input video file. Supported formats: MP4, MPEG, QuickTime, AVI, WMV,
            OGG.
          type: string
          format: binary
        ref_image:
          description: >-
            Reference character image. Supported formats: JPG, JPEG, PNG, GIF,
            BMP, WebP. Maximum file size: 10 MB.
          type: string
          format: binary
        prompt:
          description: Optional text prompt to guide the replacement
          type: string
          nullable: true
        width:
          description: >-
            Output video width in pixels. If omitted, uses input video width.
            Must be provided together with height.
          type: integer
          nullable: true
        height:
          description: >-
            Output video height in pixels. If omitted, uses input video height.
            Must be provided together with width.
          type: integer
          nullable: true
        steps:
          description: 'Number of inference steps (default: 4)'
          type: integer
          example: 4
        seed:
          description: 'Random seed for generation (default: -1 for random)'
          type: integer
          example: -1
        model:
          description: >-
            The model to use for video replacement. Available models can be
            retrieved via the GET /api/v1/client/models endpoint.
          type: string
        webhook_url:
          description: >-
            Optional HTTPS URL to receive webhook notifications for job status
            changes. Must be HTTPS. Max 2048 characters.
          type: string
          format: uri
          maxLength: 2048
          nullable: true
      type: object
    JobRequestResponseResource:
      properties:
        data:
          description: Information from success endpoint
          properties:
            request_id:
              description: Request Id
              required:
                - request_id
              type: string
              example: c08a339c-73e5-4d67-a4d5-231302fbff9a
          type: object
      type: object
    response_error_default:
      properties:
        data:
          description: Information from success endpoint
          type: object
        message:
          description: Error general message
          type: string
        errors:
          description: Information about errors
          type: array
          items: {}
        statusCode:
          description: Status code
          type: integer
      type: object
    response_error_rate_limit:
      description: Rate limit exceeded response
      properties:
        message:
          description: Error message
          type: string
          example: Too Many Attempts.
      type: object
  responses:
    ValidationError:
      description: >-
        Validation failed. Common errors include: model does not exist, model
        does not support the inference type for this endpoint, or invalid
        request parameters.
      content:
        application/json:
          schema:
            properties:
              message:
                description: General error message
                type: string
                example: The selected model does not support Text To Image.
              errors:
                description: Detailed validation errors by field
                type: object
                example:
                  model:
                    - The selected model does not support Text To Image.
            type: object
    RateLimitExceeded:
      description: >-
        Rate limit exceeded. Check X-RateLimit-Type header to determine if
        minute (RPM) or daily (RPD) limit was hit.
      headers:
        X-RateLimit-Limit:
          description: Maximum requests allowed per minute (RPM)
          schema:
            type: integer
            example: 3
        X-RateLimit-Remaining:
          description: Remaining requests in current minute window
          schema:
            type: integer
            example: 0
        X-RateLimit-Daily-Limit:
          description: Maximum requests allowed per day (RPD)
          schema:
            type: integer
            example: 100
        X-RateLimit-Daily-Remaining:
          description: Remaining requests in current day window
          schema:
            type: integer
            example: 95
        X-RateLimit-Type:
          description: 'Type of rate limit exceeded: "minute" for RPM, "daily" for RPD'
          schema:
            type: string
            enum:
              - minute
              - daily
            example: minute
        Retry-After:
          description: >-
            Seconds until rate limit resets (60 for minute, up to 86400 for
            daily)
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response_error_rate_limit'
  securitySchemes:
    bearerAuth:
      type: http
      bearerFormat: JWT
      scheme: bearer

````