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

# VideoRetalk Video Generate

> - Audio-driven lip-sync video generation — replaces the lip movements of the person in the video with ones matching the target audio
- Asynchronous processing mode; use the returned task ID to [query the result](/en/api-manual/task-management/get-task-detail)
- Generated video links are valid for 24 hours — save them promptly

**Typical use cases:**
- Multilingual dubbing: replace the lip movements in the original video with a dubbed audio track in another language
- Virtual presenter: drive a character video with TTS-generated audio
- Advertising: quickly produce multilingual versions of the same video asset
- Education and training: replace instructor videos with explanations in different languages

**Notes:**
- Input URLs must be publicly accessible
- The video must contain a human face; otherwise the task will fail
- Pass `ref_image_url` when multiple faces are present in the video



## OpenAPI

````yaml /en/api-manual/video-series/videoretalk/videoretalk-video-generate.json POST /v1/videos/generations
openapi: 3.1.0
info:
  title: VideoRetalk Lip-Sync Video Generation API
  description: >-
    Audio-driven lip-sync video generation. Provide a talking-head video and a
    target audio clip to replace the lip movements of the person in the video
    with ones that match the target audio.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: Production environment
security:
  - bearerAuth: []
tags:
  - name: Lip-Sync Video
    description: VideoRetalk lip-sync video generation API endpoints
paths:
  /v1/videos/generations:
    post:
      tags:
        - Lip-Sync Video
      summary: VideoRetalk Lip-Sync Video Generation
      description: >-
        - Audio-driven lip-sync video generation — replaces the lip movements of
        the person in the video with ones matching the target audio

        - Asynchronous processing mode; use the returned task ID to [query the
        result](/en/api-manual/task-management/get-task-detail)

        - Generated video links are valid for 24 hours — save them promptly


        **Typical use cases:**

        - Multilingual dubbing: replace the lip movements in the original video
        with a dubbed audio track in another language

        - Virtual presenter: drive a character video with TTS-generated audio

        - Advertising: quickly produce multilingual versions of the same video
        asset

        - Education and training: replace instructor videos with explanations in
        different languages


        **Notes:**

        - Input URLs must be publicly accessible

        - The video must contain a human face; otherwise the task will fail

        - Pass `ref_image_url` when multiple faces are present in the video
      operationId: createVideoRetalkGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoRetalkRequest'
            examples:
              minimal:
                summary: Minimal call
                value:
                  model: videoretalk
                  video_url: https://example.com/speaker.mp4
                  audio_url: https://example.com/target-speech.wav
              multi_face:
                summary: Multi-face scene + video extension
                value:
                  model: videoretalk
                  video_url: https://example.com/two-people-talking.mp4
                  audio_url: https://example.com/long-speech.wav
                  ref_image_url: https://example.com/target-person-face.jpg
                  video_extension: true
                  query_face_threshold: 150
              adjust_threshold:
                summary: Adjust face matching sensitivity
                value:
                  model: videoretalk
                  video_url: https://example.com/speaker.mp4
                  audio_url: https://example.com/speech.wav
                  query_face_threshold: 140
      responses:
        '200':
          description: Lip-sync video generation task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoRetalkResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: missing_required_params
                  message: 'Missing required parameter: video_url or audio_url'
                  type: invalid_request_error
        '401':
          description: Unauthenticated, invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: Insufficient quota, top-up required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: insufficient_quota
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: model_access_denied
                  message: 'Token does not have access to model: videoretalk'
                  type: invalid_request_error
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests, please try again later
                  type: rate_limit_error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
components:
  schemas:
    VideoRetalkRequest:
      type: object
      required:
        - model
        - video_url
        - audio_url
      properties:
        model:
          type: string
          description: Model name
          enum:
            - videoretalk
          default: videoretalk
          example: videoretalk
        video_url:
          type: string
          format: uri
          description: >-
            Input video URL containing the person whose lip movements will be
            replaced


            **Requirements:**

            - Publicly accessible video URL

            - Formats: MP4, MOV, and other common formats

            - The video must contain a clearly visible human face

            - Recommended duration: `2` ~ `300` seconds
          example: https://example.com/speaker.mp4
        audio_url:
          type: string
          format: uri
          description: >-
            Target audio URL — the person in the video will lip-sync to this
            audio


            **Requirements:**

            - Publicly accessible audio URL

            - Formats: WAV, MP3, M4A, and other common formats

            - Recommended to use human speech content
          example: https://example.com/target-speech.wav
        ref_image_url:
          type: string
          format: uri
          description: >-
            Reference face image URL


            When the video contains **multiple faces**, use this image to
            specify the target face whose lip movements should be replaced


            **Requirements:**

            - The image should show a clear frontal view of the target person's
            face

            - Only required when the video contains multiple faces
          example: https://example.com/target-person-face.jpg
        video_extension:
          type: boolean
          description: >-
            Whether to automatically extend the video to match the audio length
            when the audio is longer than the video


            - `true`: output duration = audio duration (video extended
            automatically)

            - `false`: output duration = min(video duration, audio duration)
          default: false
          example: false
        query_face_threshold:
          type: integer
          description: >-
            Face matching confidence threshold


            - Range: `120` ~ `200`

            - Lower values match more easily (may cause false matches)

            - Higher values are stricter (may fail to match)

            - If "no matching face found" is reported, try lowering the value
            (e.g. `140`)

            - If the wrong face is matched, try raising the value (e.g. `190`)
          default: 170
          minimum: 120
          maximum: 200
          example: 170
        callback_url:
          type: string
          description: >-
            HTTPS callback URL invoked when the task completes


            **Trigger conditions:**

            - Triggered when the task is completed, failed, or cancelled

            - Sent after billing confirmation


            **Security restrictions:**

            - HTTPS only

            - Internal IP addresses are blocked (127.0.0.1, 10.x.x.x,
            172.16-31.x.x, 192.168.x.x, etc.)

            - URL length must not exceed `2048` characters


            **Callback behavior:**

            - Timeout: `10` seconds

            - Up to `3` retries after failure (at 1s / 2s / 4s intervals)

            - Response body format matches the task query API response

            - A 2xx status code is considered success; other codes trigger a
            retry
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    VideoRetalkResponse:
      type: object
      properties:
        created:
          type: integer
          description: Task creation timestamp
          example: 1775200000
        id:
          type: string
          description: Task ID
          example: task-unified-1775200000-xyz12345
        model:
          type: string
          description: Actual model name used
          example: videoretalk
        object:
          type: string
          enum:
            - video.generation.task
          description: Specific task type
        progress:
          type: integer
          description: Task progress percentage (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: |-
            Task status

            | Status | progress | Description |
            |------|----------|------|
            | `pending` | 0~10 | Waiting to be processed |
            | `processing` | 10~80 | Processing |
            | `completed` | 100 | Completed |
            | `failed` | 0 | Failed |
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          $ref: '#/components/schemas/VideoTaskInfo'
          description: Video task details
        type:
          type: string
          enum:
            - video
          description: Task output type
          example: video
        usage:
          $ref: '#/components/schemas/VideoUsage'
          description: Usage and billing information
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code identifier
            message:
              type: string
              description: Error description
            type:
              type: string
              description: Error type
    VideoTaskInfo:
      type: object
      properties:
        can_cancel:
          type: boolean
          description: Whether the task can be cancelled
          example: false
        estimated_time:
          type: integer
          description: Estimated completion time (seconds)
          minimum: 0
          example: 90
        video_duration:
          type: integer
          description: Estimated video duration (seconds)
          example: 0
    VideoUsage:
      type: object
      description: Usage information
      properties:
        billing_rule:
          type: string
          description: Billing rule
          enum:
            - per_second
          example: per_second
        credits_reserved:
          type: number
          description: Estimated credits to be consumed (based on video and audio duration)
          minimum: 0
          example: 480
        user_group:
          type: string
          description: User group category
          example: default
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ##All endpoints require Bearer Token authentication##


        **Get your API Key:**


        Visit the [API Key management page](https://evolink.ai/dashboard/keys)
        to obtain your API Key


        **Add the following header to every request:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````