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

# Video Replication

> Generate a character variant from a source video, reference images, and optional voice.

Use a Darwin API key with `tools:execute`. Send a source video, one to three character images, written instructions, and an optional authorized voice sample. Source and output videos are limited to 45 seconds. Keep the same `Idempotency-Key` when retrying the exact request.

See the [Video Replication guide](/docs/agents/video-replication) for preparing a character variant and reviewing the result.


## OpenAPI

````yaml openapi-agents.json POST /v3/agents/video-replication
openapi: 3.1.0
info:
  title: Agents
  version: 3.0.0
  description: Run specialized marketing agents with an authenticated Darwin API key.
servers:
  - url: https://api.darwin.so/api
security: []
paths:
  /v3/agents/video-replication:
    post:
      tags:
        - Marketing
      summary: Video Replication
      description: >-
        Generate a new version of a source video with a new character. Provide
        one to three character images, instructions, and optionally an
        authorized voice sample. Source and output videos are limited to 45
        seconds.
      operationId: video_replication
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: Reuse the same key only for an identical request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                videoUrl:
                  type: string
                  maxLength: 2048
                  format: uri
                  description: Source MP4 or MOV video, up to 45 seconds.
                instructions:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: >-
                    Describe the requested changes and what should stay
                    consistent.
                characterImages:
                  minItems: 1
                  maxItems: 3
                  type: array
                  items:
                    type: string
                    maxLength: 2048
                    format: uri
                  description: One to three reference images of the same new character.
                voiceUrl:
                  description: >-
                    Optional MP3 or WAV sample of the new character’s authorized
                    voice.
                  type: string
                  maxLength: 2048
                  format: uri
              required:
                - videoUrl
                - instructions
                - characterImages
              additionalProperties: false
            example:
              videoUrl: https://media.example.com/source.mp4
              characterImages:
                - https://media.example.com/character.png
              instructions: Use the new character, retaining the pacing and scene structure.
      responses:
        '200':
          description: Generated video.
          content:
            application/json:
              schema:
                type: object
                required:
                  - video
                properties:
                  video:
                    type: object
                    required:
                      - url
                      - durationSeconds
                      - mimeType
                    properties:
                      url:
                        type: string
                        format: uri
                      durationSeconds:
                        type: number
                        maximum: 45
                      mimeType:
                        type: string
                        const: video/mp4
        '400':
          description: Invalid media references or instructions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
        '401':
          description: API key missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
        '403':
          description: >-
            API_UNAVAILABLE: contact support@darwin.so for access, or
            insufficient scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
        '422':
          description: Unsupported media or source video longer than 45 seconds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
        '503':
          description: 'API_UNAVAILABLE: contact support@darwin.so for access.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  supportEmail:
                    type: string
      security:
        - apiKey: []
        - apiKeyBearer: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: Darwin API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.