HappyHorse - Referencia de la API de referencia a video

Notas de uso

Para garantizar llamadas a la API exitosas, debe utilizar un modelo, una URL de endpoint y una clave de API que pertenezcan todos a la misma región. Las llamadas entre regiones fallarán.

Seleccionar un modelo: Confirm la región donde se encuentra su modelo.
Seleccionar una URL: Elija la URL de endpoint correspondiente. Se admiten tanto URLs HTTP como del SDK de DashScope.
Configurar una clave de API: Seleccione una región, obtenga una clave de API y luego configure la clave de API como variable de entorno.

El código de ejemplo en este tema aplica a la región de Singapur.

Alibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.

Llamadas HTTP

Debido a que las tareas de referencia a video consumen mucho tiempo (generalmente 1–5 minutos), la API utiliza una llamada asíncrona. El flujo de trabajo consta de dos pasos principales: "Crear una tarea -> Sondear para obtener el resultado".

Paso 1: Crear una tarea

Singapore
EE. UU. (Virginia)
China (Beijing)
Germany (Frankfurt)
Japan (Tokyo)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Después de crear la tarea, utilice el task_id devuelto para consultar el resultado. El task_id es válido durante 24 horas. No cree tareas duplicadas. En su lugar, utilice el sondeo para recuperar el resultado.
Para obtener orientación para principiantes, consulte Llamar a APIs con Postman o cURL.

Parámetros de solicitud

Encabezados de solicitud

Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.X-DashScope-Async string (Requerido)Habilita el procesamiento asíncrono. Las solicitudes HTTP solo admiten llamadas asíncronas. Debe ser enable.

Si falta este encabezado de solicitud, se devuelve el error "current user api does not support synchronous calls".

Cuerpo de la solicitud

model string (Obligatorio)El nombre del modelo. Para ver los modelos disponibles, consulte la consola de Model Studio.Ejemplo: happyhorse-1.1-r2v.input object (Obligatorio)La entrada del modelo, que incluye las imágenes de referencia y el indicador de texto.

Propiedades

prompt string (Obligatorio)Una descripción de los elementos deseados y el estilo visual para el video generado.Se admite la entrada en cualquier idioma. La longitud está limitada a 5,000 caracteres no chinos o 2,500 caracteres chinos. El contenido que exceda este límite se trunca automáticamente.Referencia de imágenes: En el prompt, utilice "[Imagen 1]" y "[Imagen 2]" para hacer referencia a la imagen de referencia correspondiente en el arreglo media. El orden debe ser consistente con el orden en el arreglo media. Al usar una referencia, especifique el objeto en la imagen, como "la mujer con qipao rojo en [Imagen 1]".media array (Obligatorio)Una lista de imágenes de referencia.Cada elemento en la matriz es un objeto multimedia que contiene los campos type y url.

El orden de los elementos en esta matriz define el orden de las referencias de sujeto en el prompt.
La primera reference_image en la matriz corresponde a [Imagen 1], la segunda a [Imagen 2], y así sucesivamente.

Propiedades del elemento

type string (Obligatorio)El tipo de recurso multimedia. Establézcalo en:

reference_image: Una imagen de referencia.

Límites de recursos:

Número de imágenes de referencia: 1 a 9.

url string (Obligatorio)La URL o datos codificados en Base64 de una imagen de referencia.Requisitos de imagen:

Formatos: JPEG, JPG, PNG, WEBP.
Resolución: El lado más corto debe tener al menos 400 píxeles. Se recomienda una imagen nítida con una resolución de 720P o superior. Evite usar imágenes demasiado pequeñas, borrosas o excesivamente comprimidas, ya que esto puede degradar la calidad del resultado.
Tamaño máximo de archivo: 20 MB.

Formatos de entrada admitidos:

URL pública:
- Admite protocolos HTTP o HTTPS.
- Ejemplo: https://xxx/xxx.jpg.
Cadena de imagen codificada en Base64:
- Formato de datos: data:{MIME_type};base64,{base64_data}.
- Ejemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncado con fines de visualización).
  Formato de datos codificado en Base64
  Formato: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: La cadena codificada en Base64 del archivo de imagen.
  - {MIME_type}: El tipo de medio de la imagen, que debe coincidir con el formato del archivo.
  Formato de imagen
  Tipo MIME
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object (Opcional)Parámetros para la generación de video, como resolución de video, relación de aspecto y duración.

Propiedades

resolution string (Opcional)El nivel de resolución del video generado.Valores válidos:

480P
720P
1080P: Valor predeterminado.

ratio string (Opcional)La relación de aspecto del video generado.Valores válidos:

16:9: Valor predeterminado.
9:16
3:4
4:3
4:5
5:4
1:1
9:21
21:9

duration integer (Opcional)La duración del video generado, en segundos.Rango de valores: Un entero de 3 a 15.Valor predeterminado: 5.watermark boolean (Opcional)Especifica si se debe añadir una marca de agua al video generado. La marca de agua se coloca en la esquina inferior derecha con el texto fijo "Happy Horse".

true: Valor predeterminado. Se añade una marca de agua.
false: No se añade ninguna marca de agua.

seed integer (Opcional)La semilla de número aleatorio debe ser un entero en el rango [0, 2147483647].Si no se especifica, se genera una semilla aleatoria. Una semilla fija mejora la reproducibilidad.Dado que la generación del modelo es probabilística, la misma semilla no garantiza resultados idénticos.

Referencia a video (imágenes múltiples)

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "happyhorse-1.1-r2v",
    "input": {
        "prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the tailored cut and S-curve of the dress. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

Parámetros de respuesta

output objectLa información de salida de la tarea.

Propiedades

task_id stringEl ID de la tarea. Válido para consultas durante 24 horas.task_status stringEl estado de la tarea.

Valores de enumeración

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: La tarea no existe o se desconoce su estado.

request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Respuesta exitosa
Respuesta de error

Guarde el task_id para consultar el estado y el resultado de la tarea.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Paso 2: Obtener el resultado de la tarea

Singapore
EE. UU. (Virginia)
China (Beijing)
Germany (Frankfurt)
Japan (Tokyo)

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Recomendación de sondeo: La generación de video puede tardar varios minutos. Le recomendamos implementar un mecanismo de sondeo con un intervalo de consulta razonable (por ejemplo, 15 segundos) para recuperar el resultado.
Flujo de estado de la tarea: PENDING (En cola) → RUNNING (Procesando) → SUCCEEDED (Exitoso) o FAILED (Fallido).
Validez del ID de tarea: El ID de tarea es válido durante 24 horas. Después de este período, ya no puede consultar el resultado y la API devuelve un estado de tarea de UNKNOWN.

Parámetros de solicitud

Encabezados de solicitud

Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.

Parámetros de ruta de URL

task_id string (Obligatorio)El ID de la tarea.

Consultar resultado de la tarea

Reemplace {task_id} con el valor task_id devuelto por la llamada a la API anterior. El task_id es válido para consultas durante 24 horas. Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parámetros de respuesta

outputobjectLa información de salida de la tarea.

Propiedades

task_id stringEl ID de la tarea. Válido para consultas durante 24 horas.task_status stringEl estado de la tarea.

Valores de enumeración

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: La tarea no existe o se desconoce su estado.

Transiciones de estado durante el sondeo:

PENDING → RUNNING → SUCCEEDED o FAILED.
El estado inicial de la consulta suele ser PENDING o RUNNING.
Cuando el estado cambia a SUCCEEDED, la respuesta contiene la URL del video generado.
Si el estado es FAILED, revise el mensaje de error y reintente la tarea.

submit_time stringLa hora en que se envió la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringLa hora en que se ejecutó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.end_time stringLa hora en que se completó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL del video generado. Se devuelve solo cuando task_status es SUCCEEDED.Válido durante 24 horas. El video está en formato MP4 con codificación H.264.orig_prompt stringEl prompt de entrada original, correspondiente al parámetro de solicitud prompt.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

usage objectEstadísticas de uso de la tarea. Solo se le cobra por las tareas exitosas.

Propiedades

duration integerLa duración facturable del video generado, en segundos.input_video_duration integerLa duración total del video de entrada, en segundos. Siempre es 0 para tareas de referencia a video.output_video_duration integerLa duración total del video de salida, en segundos.ratio stringLa relación de aspecto del video generado.SR integerEl nivel de resolución del video generado.video_count integerEl número de videos generados. Siempre es 1.

request_id stringIdentificador único de solicitud para rastreo y solución de problemas.

Tarea exitosa
Tarea fallida
Consulta de tarea caducada

Las URL de video son válidas solo durante 24 horas y luego se eliminan automáticamente. Guarde los videos generados de inmediato.

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-25 15:03:25.848",
        "scheduled_time": "2026-04-25 15:03:25.884",
        "end_time": "2026-04-25 15:04:05.882",
        "orig_prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the dress'\''s tailored cut and S-curve. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

Cuando una tarea falla, task_status es FAILED con un código de error y un mensaje. Consulte Códigos de error.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The resolution is not valid xxxxxx"
    }
}

El task_id es válido durante 24 horas. Después de este período, las consultas devuelven el siguiente error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Códigos de error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.

​Notas de uso

​Llamadas HTTP

​Paso 1: Crear una tarea

Parámetros de solicitud

Encabezados de solicitud

Cuerpo de la solicitud

Parámetros de respuesta

​Paso 2: Obtener el resultado de la tarea

Parámetros de solicitud

Encabezados de solicitud

Parámetros de ruta de URL

Parámetros de respuesta

​Códigos de error

Notas de uso

Llamadas HTTP

Paso 1: Crear una tarea

Paso 2: Obtener el resultado de la tarea

Códigos de error