> ## 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

> - Generación de movimiento labial en video impulsada por audio; reemplaza el movimiento labial de la persona en el video para que coincida con el audio objetivo
- Modo de procesamiento asíncrono, use el ID de tarea devuelto para [consultar](/es/api-manual/task-management/get-task-detail)
- Los enlaces de video generados son válidos por 24 horas, guárdelos cuanto antes

**Escenarios de aplicación típicos:**
- Doblaje multilingüe: reemplaza el movimiento labial del video original con doblaje en otro idioma
- Presentador virtual: impulsa el video del personaje con audio generado por TTS
- Producción publicitaria: genera rápidamente versiones publicitarias en distintos idiomas con el mismo material de video
- Formación educativa: reemplaza el video del instructor con explicaciones en distintos idiomas

**Notas importantes:**
- Las URL de entrada deben ser accesibles públicamente en internet
- El video debe contener al menos un rostro; de lo contrario, la tarea fallará
- En escenarios con múltiples rostros, asegúrese de pasar `ref_image_url`



## OpenAPI

````yaml es/api-manual/video-series/videoretalk/videoretalk-video-generate.json POST /v1/videos/generations
openapi: 3.1.0
info:
  title: Interfaz de sincronización labial VideoRetalk
  description: >-
    Generación de movimiento labial en video impulsada por audio. Introduce un
    video de una persona hablando y el audio objetivo; reemplaza el movimiento
    labial de la persona en el video para que coincida con el audio objetivo.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: Entorno de producción
security:
  - bearerAuth: []
tags:
  - name: Sincronización labial
    description: >-
      Interfaces relacionadas con la generación de video con sincronización
      labial VideoRetalk
paths:
  /v1/videos/generations:
    post:
      tags:
        - Sincronización labial
      summary: Generación de video con sincronización labial VideoRetalk
      description: >-
        - Generación de movimiento labial en video impulsada por audio;
        reemplaza el movimiento labial de la persona en el video para que
        coincida con el audio objetivo

        - Modo de procesamiento asíncrono, use el ID de tarea devuelto para
        [consultar](/es/api-manual/task-management/get-task-detail)

        - Los enlaces de video generados son válidos por 24 horas, guárdelos
        cuanto antes


        **Escenarios de aplicación típicos:**

        - Doblaje multilingüe: reemplaza el movimiento labial del video original
        con doblaje en otro idioma

        - Presentador virtual: impulsa el video del personaje con audio generado
        por TTS

        - Producción publicitaria: genera rápidamente versiones publicitarias en
        distintos idiomas con el mismo material de video

        - Formación educativa: reemplaza el video del instructor con
        explicaciones en distintos idiomas


        **Notas importantes:**

        - Las URL de entrada deben ser accesibles públicamente en internet

        - El video debe contener al menos un rostro; de lo contrario, la tarea
        fallará

        - En escenarios con múltiples rostros, asegúrese de pasar
        `ref_image_url`
      operationId: createVideoRetalkGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoRetalkRequest'
            examples:
              minimal:
                summary: Llamada mínima
                value:
                  model: videoretalk
                  video_url: https://example.com/speaker.mp4
                  audio_url: https://example.com/target-speech.wav
              multi_face:
                summary: Escenario con múltiples rostros + extensión de video
                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: Ajustar sensibilidad de coincidencia facial
                value:
                  model: videoretalk
                  video_url: https://example.com/speaker.mp4
                  audio_url: https://example.com/speech.wav
                  query_face_threshold: 140
      responses:
        '200':
          description: >-
            Tarea de generación de video con sincronización labial creada con
            éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoRetalkResponse'
        '400':
          description: Error en los parámetros de solicitud
          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: No autenticado, token inválido o expirado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: Créditos insuficientes, recarga necesaria
          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: Sin permiso de acceso
          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: Frecuencia de solicitudes excedida
          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: Error interno del servidor
          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: Nombre del modelo
          enum:
            - videoretalk
          default: videoretalk
          example: videoretalk
        video_url:
          type: string
          format: uri
          description: >-
            URL del video de entrada que contiene la persona cuyo movimiento
            labial se reemplazará


            **Requisitos:**

            - URL de video accesible públicamente en internet

            - Formatos: MP4, MOV y otros formatos comunes

            - El video debe contener un rostro claramente visible

            - Duración recomendada: `2` ~ `300` segundos
          example: https://example.com/speaker.mp4
        audio_url:
          type: string
          format: uri
          description: >-
            URL del audio objetivo; la persona en el video hablará sincronizando
            con este audio


            **Requisitos:**

            - URL de audio accesible públicamente en internet

            - Formatos: WAV, MP3, M4A y otros formatos comunes

            - Se recomienda que sea contenido de voz hablada
          example: https://example.com/target-speech.wav
        ref_image_url:
          type: string
          format: uri
          description: >-
            URL de imagen de referencia facial


            Cuando el video contiene **múltiples rostros**, use esta imagen para
            especificar el rostro objetivo cuyo movimiento labial se reemplazará


            **Requisitos:**

            - La imagen debe contener el rostro frontal de la persona objetivo

            - Solo es necesario cuando el video contiene múltiples rostros
          example: https://example.com/target-person-face.jpg
        video_extension:
          type: boolean
          description: >-
            Cuando la duración del audio > duración del video, indica si se
            extiende automáticamente el video a la duración del audio


            - `true`: duración de salida = duración del audio (el video se
            extiende automáticamente)

            - `false`: duración de salida = min(duración del video, duración del
            audio)
          default: false
          example: false
        query_face_threshold:
          type: integer
          description: >-
            Umbral de confianza para la coincidencia facial


            - Rango: `120` ~ `200`

            - Cuanto menor es el valor, más fácil es la coincidencia (puede
            haber coincidencias incorrectas)

            - Cuanto mayor es el valor, más estricta es la coincidencia (puede
            fallar la coincidencia)

            - Si aparece el error "no se encontró rostro coincidente", reduzca
            el valor apropiadamente (por ejemplo, `140`)

            - Si coincide con el rostro incorrecto, aumente el valor
            apropiadamente (por ejemplo, `190`)
          default: 170
          minimum: 120
          maximum: 200
          example: 170
        callback_url:
          type: string
          description: >-
            Dirección de callback HTTPS tras completar la tarea


            **Momento del callback:**

            - Se activa cuando la tarea se completa (completed), falla (failed)
            o se cancela (cancelled)

            - Se envía tras confirmar la facturación


            **Restricciones de seguridad:**

            - Solo se admite el protocolo HTTPS

            - Prohibido hacer callback a direcciones IP internas (127.0.0.1,
            10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.)

            - La URL no debe superar los `2048` caracteres


            **Mecanismo de callback:**

            - Tiempo de espera: `10` segundos

            - Máximo `3` reintentos tras fallo (respectivamente `1`/`2`/`4`
            segundos después del fallo)

            - El formato del cuerpo de respuesta del callback es igual al
            formato de retorno de la interfaz de consulta de tareas

            - Si la dirección de callback devuelve código de estado 2xx se
            considera exitoso; otros códigos activan reintentos
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    VideoRetalkResponse:
      type: object
      properties:
        created:
          type: integer
          description: Marca de tiempo de creación de la tarea
          example: 1775200000
        id:
          type: string
          description: ID de tarea
          example: task-unified-1775200000-xyz12345
        model:
          type: string
          description: Nombre del modelo realmente utilizado
          example: videoretalk
        object:
          type: string
          enum:
            - video.generation.task
          description: Tipo específico de la tarea
        progress:
          type: integer
          description: Porcentaje de progreso de la tarea (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: |-
            Estado de la tarea

            | Estado | progress | Descripción |
            |------|----------|------|
            | `pending` | 0~10 | En espera de procesamiento |
            | `processing` | 10~80 | En procesamiento |
            | `completed` | 100 | Completado |
            | `failed` | 0 | Fallido |
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          $ref: '#/components/schemas/VideoTaskInfo'
          description: Información detallada de la tarea de video
        type:
          type: string
          enum:
            - video
          description: Tipo de salida de la tarea
          example: video
        usage:
          $ref: '#/components/schemas/VideoUsage'
          description: Información de uso y facturación
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Identificador del código de error
            message:
              type: string
              description: Mensaje de descripción del error
            type:
              type: string
              description: Tipo de error
    VideoTaskInfo:
      type: object
      properties:
        can_cancel:
          type: boolean
          description: Si la tarea se puede cancelar
          example: false
        estimated_time:
          type: integer
          description: Tiempo estimado de finalización (segundos)
          minimum: 0
          example: 90
        video_duration:
          type: integer
          description: Duración estimada del video (segundos)
          example: 0
    VideoUsage:
      type: object
      description: Información de uso
      properties:
        billing_rule:
          type: string
          description: Regla de facturación
          enum:
            - per_second
          example: per_second
        credits_reserved:
          type: number
          description: >-
            Créditos estimados a consumir (basado en la duración del video y el
            audio)
          minimum: 0
          example: 480
        user_group:
          type: string
          description: Tipo de grupo de usuario
          example: default
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ##Todas las interfaces requieren autenticación con Bearer Token##


        **Obtener API Key:**


        Visita la [página de administración de API
        Key](https://evolink.ai/dashboard/keys) para obtener tu API Key


        **Agrégalo en el encabezado de solicitud:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````