Referencia de la API HappyHorse imagen a video (primer fotograma)

Notas de uso

El modelo, la URL del endpoint y la clave de API deben pertenecer a la misma región. Las llamadas entre regiones fallarán.

Seleccionar un modelo: Verifique a qué región pertenece el modelo.
Seleccione una URL: Seleccione la URL del endpoint correspondiente a la misma región.
Configurar una clave de API: Obtenga una clave de API para la misma región 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

Las tareas de imagen a video tardan 1–5 minutos. La API utiliza llamadas asíncronas: "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

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-i2v.input object (obligatorio)Entrada del modelo, incluido el prompt de texto.

Propiedades

prompt string (opcional)Describe el contenido del video a generar.Admite cualquier idioma. Máximo: 5,000 caracteres no chinos o 2,500 caracteres chinos. Las entradas más largas se truncan.media array (requerido)El arreglo de imágenes de entrada.

Propiedades del elemento media[]

type string (obligatorio)El tipo de medio. Valor permitido:

first_frame: El primer fotograma.

Se requiere exactamente una imagen de primer fotograma.url string (requerido)La URL del medio.

Imagen de entrada (type=first_frame)

La URL o datos codificados en Base64 de la imagen del primer fotograma.Restricciones de imagen:

Formatos: JPEG, JPG, PNG, WEBP.
Resolución: El ancho y el alto deben ser de al menos 300 píxeles.
Relación de aspecto: Entre 1:2.5 y 2.5:1.
Tamaño de archivo: Hasta 20 MB.

Formatos de entrada admitidos:

URL pública:
- Se admiten HTTP y HTTPS.
- Ejemplo: https://xxx/xxx.png.
Cadena de imagen codificada en Base64:
- Formato: data:{MIME_type};base64,{base64_data}.
- Ejemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncado para visualización).
  Formato de codificación 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)Configuración de salida de video, como resolución y duración.

Propiedades

resolution string (opcional)La resolución del video generado.El recuento de píxeles de salida se aproxima al nivel seleccionado mientras se conserva la relación de aspecto de la imagen de entrada.Valores permitidos:

480P
720P
1080P (Predeterminado)

duration integer (opcional)La duración del video generado, en segundos.El valor debe ser un entero en el rango [3, 15]. Predeterminado: 5.watermark boolean (opcional)Añade una marca de agua de texto "Happy Horse" 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.

Imagen a video

# The following URLs are for the Singapore region. Replace {WorkspaceId} with your Bailian 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-i2v",
    "input": {
        "prompt": "A cat running on the grass",
        "media": [
            {
                "type": "first_frame",
                "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5
    }
}'

Parámetros de respuesta

output objectLa 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: Sondear para obtener el resultado

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 de solicitud

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

outputobjectLa 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_urlstringDevuelto solo cuando task_status es SUCCEEDED.La URL es válida durante 24 horas. Descargue el video MP4 (24 fps, codificación H.264) desde esta URL.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. Calculadas solo para tareas exitosas.

Propiedades

input_video_duration integerLa duración del video de entrada, en segundos.output_video_duration integerLa duración del video de salida, en segundos.duration integerLa duración total del video utilizada para la facturación.SR integerLa resolución del video de salida.video_count integerEl número de videos de salida. Este valor 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": "8ae698ba-df2d-966c-abcf-xxxxxx",
    "output": {
        "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 19:33:50.425",
        "scheduled_time": "2026-04-20 19:33:50.463",
        "end_time": "2026-04-20 19:35:34.216",
        "orig_prompt": "A cat running on the grass",
        "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
    }
}

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 parameter is invalid."
    }
}

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 una llamada falla, consulte la referencia de mensajes de error.

FAQ

Relación de aspecto del video

La relación de aspecto de salida coincide con el primer fotograma. A diferencia del modelo HappyHorse texto a video, imagen a video no admite el parámetro ratio.

​Notas de uso

​Llamadas HTTP

​Paso 1: Crear una tarea

Parámetros de solicitud

Cuerpo de la solicitud

Parámetros de respuesta

​Paso 2: Sondear para obtener el resultado

Parámetros de solicitud

Encabezados de solicitud

Parámetros de ruta

Parámetros de respuesta

​Códigos de error

​FAQ

​Relación de aspecto del video

Notas de uso

Llamadas HTTP

Paso 1: Crear una tarea

Paso 2: Sondear para obtener el resultado

Códigos de error

FAQ

Relación de aspecto del video