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

# Kling-V3 Control de movimiento

> - El modelo Kling-V3 Motion Control (kling-v3-motion-control) permite generar movimiento mediante **imagen de referencia + video de referencia**
- El sistema extrae la trayectoria de movimiento del video de referencia y la aplica al personaje/objeto de la imagen de referencia, generando un nuevo video con movimientos consistentes con el video de referencia
- La duración del video depende de `character_orientation`: `image` máximo 10 segundos, `video` máximo 30 segundos, mínimo 3 segundos
- Modo de procesamiento asíncrono, utilice el ID de tarea devuelto para [consultar el estado](/es/api-manual/task-management/get-task-detail)
- El enlace del video generado es válido por 24 horas, por favor guárdelo lo antes posible



## OpenAPI

````yaml es/api-manual/video-series/kling/kling-v3-motion-control.json POST /v1/videos/generations
openapi: 3.1.0
info:
  title: API kling-v3-motion-control
  description: Crea tareas de control de movimiento de video usando modelos de IA
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Generación de video
    description: Interfaces relacionadas con la generación de video por IA
paths:
  /v1/videos/generations:
    post:
      tags:
        - Generación de video
      summary: kling-v3-motion-control API
      description: >-
        - El modelo Kling-V3 Motion Control (kling-v3-motion-control) permite
        generar movimiento mediante **imagen de referencia + video de
        referencia**

        - El sistema extrae la trayectoria de movimiento del video de referencia
        y la aplica al personaje/objeto de la imagen de referencia, generando un
        nuevo video con movimientos consistentes con el video de referencia

        - La duración del video depende de `character_orientation`: `image`
        máximo 10 segundos, `video` máximo 30 segundos, mínimo 3 segundos

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

        - El enlace del video generado es válido por 24 horas, por favor
        guárdelo lo antes posible
      operationId: createVideoGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
            examples:
              basic:
                summary: Control de movimiento básico
                value:
                  model: kling-v3-motion-control
                  prompt: A girl dancing gracefully
                  image_urls:
                    - https://example.com/character.jpg
                  video_urls:
                    - https://example.com/dance-reference.mp4
                  quality: 720p
                  model_params:
                    character_orientation: image
              hd_no_sound:
                summary: Alta definición + sin sonido original
                value:
                  model: kling-v3-motion-control
                  prompt: A robot performing martial arts
                  image_urls:
                    - https://example.com/robot.png
                  video_urls:
                    - https://example.com/martial-arts.mp4
                  quality: 1080p
                  model_params:
                    character_orientation: video
                    keep_sound: false
              with_element:
                summary: Con control de elemento principal
                value:
                  model: kling-v3-motion-control
                  image_urls:
                    - https://example.com/person.jpg
                  video_urls:
                    - https://example.com/walking.mp4
                  model_params:
                    character_orientation: video
                    element_list:
                      - element_id: '123456789'
      responses:
        '200':
          description: Tarea de generación de video creada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationResponse'
        '400':
          description: Error en los parámetros de la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: Invalid request parameters
                  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: Cuota insuficiente, necesita recargar
          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: kling-v3-motion-control'
                  type: invalid_request_error
        '429':
          description: Límite de frecuencia de solicitudes excedido
          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:
    VideoGenerationRequest:
      type: object
      required:
        - model
        - image_urls
        - video_urls
        - model_params
      properties:
        model:
          type: string
          description: Nombre del modelo de generación de video
          enum:
            - kling-v3-motion-control
          default: kling-v3-motion-control
          example: kling-v3-motion-control
        image_urls:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Array de URLs de imágenes de referencia, utilizado para proporcionar
            la fuente de apariencia del personaje/objeto


            **Nota:**

            - Envíe una imagen de referencia

            - Tamaño de imagen: no mayor a `10MB`

            - Formatos de archivo compatibles: `.jpg`, `.jpeg`, `.png`

            - Dimensiones de imagen: ancho y alto ≥ `300px`, relación de aspecto
            entre `1:2.5` ~ `2.5:1`

            - La URL de la imagen debe ser accesible directamente por el
            servidor
          example:
            - https://example.com/character.jpg
        video_urls:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Array de URLs de video de referencia para proporcionar la
            trayectoria de movimiento


            **Nota:**

            - Proporcione un video de referencia

            - Duración del video: `3` a `30` segundos

            - Tamaño del video: hasta `100MB`

            - Dimensiones del video: ancho y alto entre `340px` y `3850px`

            - Evite cortes, movimientos rápidos y cambios de escena

            - La URL del video debe ser accesible directamente por el servidor
          example:
            - https://example.com/dance-reference.mp4
        prompt:
          type: string
          description: >-
            Texto de indicación (opcional), utilizado para guiar el contenido
            generado


            **Nota:**

            - Máximo `2500` caracteres

            - Puede dejarse vacío, el modelo generará automáticamente basándose
            en la imagen y el video de referencia
          example: A girl dancing gracefully
          maxLength: 2500
        quality:
          type: string
          description: |-
            Nivel de resolución

            **Descripción:**
            - `720p`: Calidad estándar (std)
            - `1080p`: Calidad alta (pro)
          enum:
            - 720p
            - 1080p
          default: 720p
          example: 720p
        model_params:
          type: object
          required:
            - character_orientation
          description: >-
            Parámetros específicos del modelo (obligatorio), utilizado para la
            configuración del control de movimiento
          properties:
            character_orientation:
              type: string
              description: >-
                Controla la dirección hacia la que mira el personaje generado.


                **Valores:**

                - `image`: El personaje mira en la misma dirección que la imagen
                de referencia (máx. 10 segundos)

                - `video`: El personaje mira en la misma dirección que el video
                de referencia (máx. 30 segundos)


                **Nota:**

                - Cuando se usa `element_list`, solo se admite `video`
              enum:
                - image
                - video
              example: image
            element_list:
              type: array
              description: >-
                Lista de elementos principales, utilizada para especificar los
                personajes/objetos a controlar


                **Nota:**

                - Máximo `1` elemento principal (limitación de Motion Control)

                - `element_id`: ID del elemento principal

                - Solo admite elementos creados mediante el tipo de referencia
                `video_refer` (`image_refer` no es compatible)
              items:
                type: object
                properties:
                  element_id:
                    type: string
                    description: ID del elemento principal
                required:
                  - element_id
              maxItems: 1
            keep_sound:
              type: boolean
              description: |-
                Si se conserva el sonido original del video de referencia

                **Descripción:**
                - `true`: Conservar sonido original (por defecto)
                - `false`: Silenciar
              default: true
              example: true
            watermark_info:
              type: object
              description: Configuración de marca de agua
              properties:
                enabled:
                  type: boolean
                  description: Si se habilita la marca de agua
        callback_url:
          type: string
          description: >-
            Dirección de callback HTTPS cuando la tarea se complete


            **Momento del callback:**

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

            - Se envía después de confirmar la facturación


            **Restricciones de seguridad:**

            - Solo se admite el protocolo HTTPS

            - Se prohíbe el callback a direcciones IP de red interna

            - La longitud de la URL no debe exceder `2048` caracteres


            **Mecanismo de callback:**

            - Tiempo de espera: `10` segundos

            - Máximo `3` reintentos después de un fallo

            - El formato del cuerpo de respuesta del callback es consistente con
            el formato devuelto por la interfaz de consulta de tareas

            - Si la dirección de callback devuelve un código de estado 2xx se
            considera exitoso, otros códigos de estado activarán reintentos
          format: uri
          example: https://your-domain.com/webhooks/video-task-completed
    VideoGenerationResponse:
      type: object
      properties:
        created:
          type: integer
          description: Marca de tiempo de creación de la tarea
          example: 1757169743
        id:
          type: string
          description: ID de la tarea
          example: task-unified-1757169743-7cvnl5zw
        model:
          type: string
          description: Nombre del modelo realmente utilizado
          example: kling-v3-motion-control
        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
          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:
            - text
            - image
            - audio
            - 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: 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: true
        estimated_time:
          type: integer
          description: Tiempo estimado de finalización (segundos)
          minimum: 0
          example: 300
        video_duration:
          type: integer
          description: >-
            Duración del video (segundos), depende de `character_orientation`:
            `image` máximo 10 segundos, `video` máximo 30 segundos
          example: 8
    VideoUsage:
      type: object
      description: Información de uso y facturación
      properties:
        billing_rule:
          type: string
          description: Regla de facturación
          enum:
            - per_call
            - per_token
            - per_second
          example: per_second
        credits_reserved:
          type: number
          description: Créditos estimados consumidos
          minimum: 0
          example: 408240
        user_group:
          type: string
          description: Categoría del grupo de usuarios
          example: default
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ##Todas las interfaces requieren autenticación mediante Bearer Token##


        **Obtener API Key:**


        Visite la [página de gestión de API
        Key](https://evolink.ai/dashboard/keys) para obtener su API Key


        **Agregue en el encabezado de la solicitud:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````