Vidu - Referencia de API de imagen a video desde un cuadro inicial - Alibaba Cloud Model Studio

El modelo de imagen a video de Vidu genera un video fluido a partir de una imagen de entrada y una indicación de texto.

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.

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

Llamadas HTTP

La generación de imagen a video es una tarea de larga duración que normalmente toma de 1 a 5 minutos, por lo que la API utiliza un modelo asíncrono. El flujo de trabajo consta de dos pasos principales: crear una tarea y luego sondear el resultado.

Paso 1: Crear una tarea

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

Nota

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

Content-Type string (Requerido)

El tipo de contenido de la solicitud. Debe ser application/json.

Content-Type string (Requerido)

El tipo de contenido de la solicitud. Debe ser application/json.

X-DashScope-Async string (Requerido)

Habilita el procesamiento asíncrono. Las solicitudes HTTP solo admiten llamadas asíncronas. Debe ser enable.

ImportanteSi 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. Los valores válidos son:

vidu/viduq2-pro-fast_img2video

input object (Obligatorio)

La entrada básica, que incluye la indicación de texto y los recursos multimedia.

Propiedades

prompt string (Opcional)

La indicación de texto, que describe los elementos deseados y las características visuales del video generado.

La longitud máxima es de 5,000 caracteres (tanto los caracteres chinos como las letras inglesas cuentan como uno). El texto que exceda este límite se truncará.

media array (Obligatorio)

Una lista de recursos multimedia que especifican la imagen para la generación.

Cada elemento en la matriz es un objeto multimedia que contiene un campo type y un campo url.

Propiedades

type string (Obligatorio)

El tipo de recurso multimedia. Debe establecerse en el siguiente valor fijo:

image: Una URL de imagen.

Limitación de recursos: Debe proporcionar exactamente un recurso de imagen.

url string (Obligatorio)

La URL del archivo de imagen, que debe ser accesible públicamente.

Protocolos admitidos: HTTP o HTTPS.
Ejemplo: https://example.com/image.jpg.

Restricciones de imagen:

Formatos: JPG, JPEG, PNG, WEBP.
Relación de aspecto: de 1:4 a 4:1.
Tamaño de archivo: Hasta 50 MB.

parameters object (Opcional)

Parámetros para el procesamiento de video, como resolución y duración.

Propiedades

resolution string (Opcional)

ImportanteLa configuración de resolution afecta directamente el costo. Antes de realizar una llamada, confirme los precios del modelo.

Especifica el nivel de resolución para el video generado.

El modelo escala el video a un recuento de píxeles que se aproxima al nivel seleccionado mientras conserva la relación de aspecto de la imagen de entrada.

Los valores válidos son 720P y 1080P. El valor predeterminado es 720P.

duration integer (Opcional)

ImportanteLa configuración de duration afecta directamente el costo, que se factura por segundo. Una mayor duración resulta en un costo más alto. Antes de realizar una llamada, confirme los precios del modelo.

La duración del video generado en segundos.

Un entero en el rango [1, 10]. El valor predeterminado es 5.

audio boolean (Opcional)

watermark boolean (Opcional)

Especifica si se debe añadir una marca de agua. La marca de agua se coloca en la esquina inferior derecha del video y contiene el texto fijo "Generated by AI".

false: (Predeterminado) No se añade ninguna marca de agua.
true: Se añade una 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.

Imagen a video

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": "vidu/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "watermark": true
    }
}'

Parámetros de respuesta

output object

Información de salida de la tarea.

Propiedades

task_id string

El ID de la tarea. Válido para consultas durante 24 horas.

task_status string

El 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 string

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

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Respuesta exitosa

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"
}

Respuesta de error

Error en la creación de la tarea. Consulte Códigos de error.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Paso 2: Consultar el resultado

Región de Singapur: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Nota

Recomendación de sondeo: La generación de video puede tardar varios minutos. Sondee el resultado a un intervalo razonable, como cada 15 segundos.
Flujo de estado de la tarea: PENDING (en cola) → RUNNING (procesando) → SUCCEEDED (exitoso) / FAILED (fallido).
Validez del ID de tarea: El task_id es válido durante 24 horas. Después de este período, las consultas fallarán y devolverán un estado de UNKNOWN.
Límite de RPS: El punto de conexión de consulta tiene un límite predeterminado de 20 RPS. Para consultas de alta frecuencia o notificaciones de eventos, configure devoluciones de llamada de tareas asíncronas.
Más operaciones: Para realizar consultas por lotes, cancelar tareas u otras operaciones, consulte Gestionar tareas asíncronas.

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 de task_id devuelto por la llamada API anterior. El task_id es válido para consultas durante 24 horas

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

outputobject

Información de salida de la tarea.

Propiedades

task_id string

El ID de la tarea. Válido para consultas durante 24 horas.

task_status string

El 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 string

La hora en que se envió la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

La hora en que se ejecutó la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.

end_time string

La hora en que se completó la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.

end_time string

La hora en que se completó la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.

orig_prompt string

URL del video. Se devuelve solo cuando task_status es SUCCEEDED.

El formato del video es MP4 (codificación H.264). El enlace del video es válido durante 24 horas. Descárguelo a la brevedad.

orig_prompt string

El prompt de entrada original, correspondiente al parámetro de solicitud prompt.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

usage object

Estadísticas de uso de salida, contadas solo para tareas exitosas.

Propiedades

duration integer

La duración total facturable del video en segundos.

output_video_durationinteger

La duración del video de salida en segundos.

size string

La resolución del video de salida.

fps integer

La tasa de cuadros del video de salida. Este valor es fijo en 24.

SR string

El nivel de resolución del video de salida.

audio boolean

Indica si la salida es un video con audio.

video_count integer

El número de videos de salida. Este valor es fijo en 1.

request_id string

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

Tarea exitosa

{
    "request_id": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Tarea fallida

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 size is not match xxxxxx"
    }
}

Consulta de tarea caducada

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 falla una llamada al modelo, consulte Mensajes de error para solucionar el error.