Skip to main content

Referencia de la API de texto a video HappyHorse

Genere video físicamente realista y con movimiento fluido a partir de prompts de texto con el modelo HappyHorse.

Disponibilidad

El modelo, la URL del endpoint y la clave de API deben pertenecer a la misma región. Las llamadas entre regiones fallarán.
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.

Solicitud HTTP

Las tareas de texto a video suelen tardar de 1 a 5 minutos. La API utiliza llamadas asíncronas con dos pasos: "Crear una tarea → Sondear resultados".

Paso 1: Crear una tarea y obtener el ID de 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

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-t2v.input object (Obligatorio)Entrada del modelo.

Propiedades

prompt string (Obligatorio)Descripción textual del video a generar.Admite cualquier idioma. Máximo 5,000 caracteres no chinos o 2,500 caracteres chinos. El exceso se trunca.
parameters object (Opcional)Configuración de salida de video (resolución, relación de aspecto, duración).

Propiedades

resolution string (Opcional)Resolución del video de salida.Valores válidos:
  • 480P
  • 720P
  • 1080P (predeterminado)
ratio string (Opcional)Relación de aspecto del video de salida.Valores válidos:
  • 16:9 (predeterminado)
  • 9:16
  • 1:1
  • 4:3
  • 3:4
  • 4:5
  • 5:4
  • 9:21
  • 21:9
duration integer (Opcional)Duración del video de salida en segundos.
  • happyhorse-1.0-t2v: 3–15. Predeterminado: 5.
watermark boolean (Opcional)Indica si se debe agregar una marca de agua. Muestra "HappyHorse" en la esquina inferior derecha.
  • true (predeterminado)
  • false
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.
  • Texto a video
# 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-t2v",
    "input": {
        "prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead."
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

Parámetros de respuesta

output objectInformació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: Consultar el resultado por ID de 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 tarda varios minutos. Utilice un mecanismo de sondeo con un intervalo razonable, como 15 segundos.
  • Transición de estado de la tarea: PENDING → RUNNING → SUCCEEDED o FAILED.
  • Enlace de resultado: Después de que una tarea tenga éxito, se devuelve una URL de video válida durante 24 horas. Descargue y guarde el video en un almacenamiento permanente, como OSS.
  • task_idvalidez: 24 horas. Después de este período, las consultas devuelven el estado de la tarea como UNKNOWN.

Parámetros de solicitud

Encabezados
Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.
Parámetros de ruta
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

outputobjectInformació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 salida. Solo se cuentan las tareas exitosas.

Propiedades

input_video_duration integerDuración del video de entrada en segundos.output_video_duration integerDuración del video de salida en segundos.duration integerDuración total del video para facturación.SR integerResolución del video de salida.ratio stringRelación de aspecto del video de salida.video_count integerNúmero de videos de salida. Siempre 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": "99243b47-ec5f-9413-9993-xxxxxx",
    "output": {
        "task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 17:55:17.075",
        "scheduled_time": "2026-04-20 17:55:17.129",
        "end_time": "2026-04-20 17:56:36.658",
        "orig_prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead.",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

Códigos de error

Las llamadas a la API fallidas devuelven códigos de error documentados en Mensajes de error.