Skip to main content

Referencia de API de video de referencia de Vidu

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.
El 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
  • 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 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_reference2videoEl 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.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)
La 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)
La 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.
vidu/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)
  • Drama (solo imagen)
  • 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
    }
}'

Parámetros de respuesta

  • 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"
}
output objectLos datos 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.
message stringMensaje 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}
  • 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

outputobjectLos datos 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. El formato es YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringLa hora en que se ejecutó la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.end_time stringLa hora en que se completó la tarea. El formato es YYYY-MM-DD HH:mm:ss.SSS.video_urlstringLa 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 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 (contadas solo para tareas exitosas).

Propiedades

duration integerLa duración total del video generado, utilizada para la facturación.size stringEspecifica la resolución del video generado.fps integerEspecifica la tasa de fotogramas del video generado. El valor está fijado en 24.SR stringEspecifica el nivel de resolución del video generado.audio booleanIndica si el video generado incluye audio.video_count integerEspecifica el número de videos generados. El valor está fijado en 1.reference_type stringEspecifica el tipo de materiales de referencia utilizados.
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": "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"
    }
}

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.