Referencia de API de video de referencia de Vidu - Alibaba Cloud Model Studio

El modelo de referencia a video de Vidu utiliza una imagen de referencia y un prompt de texto. El modelo incorpora el sujeto de la imagen en la escena descrita por el prompt para generar un video fluido.

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

Dado que las tareas de referencia a video son de larga duración (típicamente de 1 a 5 minutos), la API utiliza llamadas asíncronas. El proceso consta de dos pasos principales: "Crear una tarea -> 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 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.

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 modelo a utilizar. Valores válidos:

vidu/viduq3-ad_reference2video
vidu/viduq3-drama_reference2video
vidu/viduq3-mix_reference2video

Guía de selección de modelos

Videos publicitarios: Utilice viduq3-ad. Diseñado para la industria publicitaria, cuenta con transiciones de toma inteligentes de grado comercial, movimientos de cámara y salida de audio directa. Suba imágenes de productos para generar videos publicitarios.
Dramas premium / Cómics de IA: Utilice viduq3-drama. Fuerte consistencia de personajes, efectos refinados y expresión emocional realista, ideal para la producción de contenido narrativo.
Uso general: Utilice viduq3-mix. Calidad visual y efectos dinámicos equilibrados, adecuado para la mayoría de los escenarios de referencia a video.

input object (obligatorio)

La entrada básica, que incluye imágenes de referencia y un prompt.

Propiedades

prompt string (obligatorio)

El prompt de texto. Describe los elementos y las características visuales que usted want en el video generado.

Se admiten tanto chino como inglés. La longitud máxima es de 5,000 caracteres. El texto que exceda este límite se truncará automáticamente.

Ejemplo: Un hombre sentado en una silla junto a una ventana, sosteniendo una guitarra y tocando una relajante canción folk country estadounidense en una cafetería.

media array (requerido)

Una lista de recursos multimedia que especifica los materiales de referencia para la generación de video.

Cada elemento de la matriz es un objeto multimedia que contiene los campos type y url.

Propiedades del elemento

type string (obligatorio)

El tipo de recurso multimedia. Los valores válidos dependen del modelo seleccionado.

Proporcionar solo imágenes de referencia

Modelos admitidos: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2video

El valor está fijado en:

image: Imagen de referencia.

Límite de recursos: De 1 a 7 imágenes.

url string (requerido)

La URL del recurso multimedia.

Proporcionar una imagen (type=image)

La URL de la imagen de referencia. La URL debe ser accesible públicamente.

Se admiten los protocolos HTTP y HTTPS.
Ejemplo: https://xxx/xxx.png

Límites de imagen:

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

parameters object (obligatorio)

Parámetros para la generación de video, como la resolución y la duración del video.

Propiedades

resolution string (opcional)

ImportanteLa resolución afecta directamente a la facturación. Antes de llamar a la API, confirme los precios del modelo.

La resolución del video generado. Los valores válidos dependen del modelo seleccionado:

vidu/viduq3-ad_reference2video: 720P o 1080P. Predeterminado: 720P.
vidu/viduq3-drama_reference2video: 720P o 1080P. Predeterminado: 1080P.
vidu/viduq3-mix_reference2video: 720P o 1080P. Predeterminado: 720P.

size string (opcional)

La resolución del video generado, en píxeles, con formato width*height.

El valor predeterminado depende de resolution:

Cuando resolución=720P, el tamaño predeterminado es 1280*720.
Cuando la resolución es 1080P, el tamaño predeterminado es 1920*1080.

Las relaciones de aspecto admitidas varían según el modelo:

vidu/viduq3-drama_reference2video: Solo se admiten 16:9 y 9:16.
Otros modelos: Se admiten 16:9, 4:3, 1:1, 3:4 y 9:16.

Valores de tamaño válidos por nivel de resolución:

720P
- 16:9: 1280*720
- 4:3: 1280*960
- 1:1: 1280*1280
- 3:4: 960*1280
- 9:16: 720*1280
1080P
- 16:9: 1920*1080
- 4:3: 1920*1440
- 1:1: 1920*1920
- 3:4: 1440*1920
- 9:16: 1080*1920

duration integer (obligatorio)

ImportanteLa duración afecta directamente a la facturación, la cual se calcula por segundo. Antes de llamar a la API, confirme los precios del modelo.

La duración del video generado, en segundos.

vidu/viduq3-ad_reference2video: Un entero en el rango de [3, 15]. El valor predeterminado es 5.
vidu/viduq3-drama_reference2video: Un entero en el rango de [2, 15]. El valor predeterminado es 5.
- Cuando el número de tomas es excesivo o significativamente menor que la duración, el modelo puede ajustar automáticamente la longitud del video para garantizar la integridad de la historia. La duración real del video puede ser mayor o menor que el valor de duración especificado.
- La facturación se calcula en función de la duración real de la salida.
vidu/viduq3-mix_reference2video: El valor es un entero en el rango de [1, 16]. El valor predeterminado es 5.

audio boolean (opcional)

Modelos compatibles: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.

Especifica si se debe generar un video con audio. Si está habilitado, el modelo genera automáticamente música de fondo o efectos de sonido que coinciden con el contenido del video.

false: El valor predeterminado. La salida es un video sin audio.
true: Genera un video con audio.

Notavidu/viduq3-drama_reference2video no admite este parámetro. Este modelo genera videos con audio de forma predeterminada.

watermark boolean (opcional)

Especifica si se debe agregar una marca de agua en la esquina inferior derecha del video. El texto de la marca de agua está fijado como "Contenido generado por IA".

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

seedinteger(opcional)

La semilla. El rango de valores es [0, 2147483647].

Si no especifica una semilla, el sistema genera una aleatoriamente. Para mejorar la reproducibilidad de los resultados, recomendamos establecer un valor de semilla fijo.

Tenga en cuenta que, debido a la naturaleza probabilística del modelo, usar la misma semilla no garantiza resultados idénticos en distintas ejecuciones.

Ejemplo: 12345

Publicidad (solo imagen)

Modelo admitido: vidu/viduq3-ad_reference2video.

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/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Drama (solo imagen)

Modelo admitido: vidu/viduq3-drama_reference2video.

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/viduq3-drama_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/eelcsu/daram-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/adglrn/drama-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/fmofkp/drama-3.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mktdht/drama-4.png"
            }
        ],
        "prompt": "Hotel banquet hall. Wang Guilan (Image 3) sits on the right side of the frame. Su Wenbo (Image 1) and Xu Xiangnuan (Image 2) are in the distance on the left, making toasts. The wedding venue is packed with guests. Su Wenbo mother Wang Guilan sits at her seat, brow furrowed tightly, visibly displeased. The camera is fixed, capturing her frowning expression. The camera pushes in on Wang Guilan face - her gaze is dark, corners of her mouth turned down, showing disdain and dissatisfaction."
    },
    "parameters": {
        "duration": 9,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Solo imagen

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/viduq3-mix_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe."
    },
    "parameters": {
        "duration": 5,
        "size": "1280*720",
        "resolution": "720P",
        "watermark": true
    }
}'

Parámetros de respuesta	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" }`
output `object` Los datos 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.

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

Paso 2: Consultar el resultado de la tarea

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. Recomendamos utilizar un mecanismo de sondeo con un intervalo de consulta razonable (por ejemplo, 15 segundos) para recuperar el resultado.
Transiciones de estado de la tarea: PENDING (en cola) → RUNNING (en progreso) → SUCCEEDED (exitoso) / FAILED (fallido).
Periodo de validez de task_id: 24 horas. Una vez expirado el periodo de validez, ya no podrá consultar el resultado y la API devolverá el estado de la tarea como UNKNOWN.
Límite de RPS: La API de consulta tiene un límite de RPS predeterminado de 20. Para consultas de mayor frecuencia o para recibir notificaciones de eventos, recomendamos configurar callbacks de tareas asíncronas.
Más operaciones: Para operaciones como consultar tareas en lotes o cancelar tareas, consulte Gestionar tareas asíncronas.

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

Los datos 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.

video_urlstring

La URL del video. Este parámetro se devuelve solo cuando task_status es SUCCEEDED.

El video está en formato MP4 (codificación H.264). La URL del video es válida durante 24 horas. Descargue el video 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 (contadas solo para tareas exitosas).

Propiedades

duration integer

La duración total del video generado, utilizada para la facturación.

size string

Especifica la resolución del video generado.

fps integer

Especifica la tasa de fotogramas del video generado. El valor está fijado en 24.

SR string

Especifica el nivel de resolución del video generado.

audio boolean

Indica si el video generado incluye audio.

video_count integer

Especifica el número de videos generados. El valor está fijado en 1.

reference_type string

Especifica el tipo de materiales de referencia utilizados.

request_id string

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

Tarea exitosa

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": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

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 la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.

FAQ

P: ¿Tengo que proporcionar tanto `size` como `resolution`?

R: No. Ambos parámetros son opcionales, pero recomendamos proporcionar ambos. Esto le permite controlar con precisión la relación de aspecto del video generado. Para más detalles, consulte Valores de tamaño válidos.

Si no proporciona ambos, el sistema maneja la solicitud de la siguiente manera:

Solo se pasa size: El parámetro size se ignora y el sistema utiliza el valor predeterminado resolution=720P y su correspondiente valor predeterminado de size (1280*720).

Ejemplo: La API devuelve size="1280*720" y SR=720.
Si solo proporciona resolution: La salida utiliza el nivel de resolución especificado.

Por ejemplo, si establece resolution=540P, la API devuelve size="960*528" y SR=540. Si establece resolution=1080P, la API devuelve size="1920*1080" y SR=1080.

Notas de uso

Llamadas HTTP

Paso 1: Crear una tarea

Parámetros de solicitud

Encabezados de solicitud

Cuerpo de la solicitud

Publicidad (solo imagen)

Drama (solo imagen)

Solo imagen

Parámetros de respuesta

Respuesta exitosa

Respuesta de error

Paso 2: Consultar el resultado de la tarea

Parámetros de solicitud

Encabezados de solicitud

Parámetros de ruta

Consultar resultado de la tarea

Parámetros de respuesta

Tarea exitosa

Tarea fallida

Consulta de tarea caducada

Códigos de error

FAQ

P: ¿Tengo que proporcionar tanto size como resolution?

P: ¿Tengo que proporcionar tanto `size` como `resolution`?