PixVerse - Referencia de API de video de referencia

Este documento solo se aplica a la región de Singapur. Debe utilizar una clave de API de esta región.

Activar el servicio

Vaya a la consola de Model Studio, busque PixVerse, encuentre la tarjeta del modelo PixVerse y haga clic en Activate Now.
En la ventana emergente, confirme la activación y la autorización.

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: Confirme la región donde se encuentra su modelo.
Seleccionar una URL: Elija la URL de endpoint de la región 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.

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

Llamadas HTTP

La generación de video de referencia es una tarea de larga duración que normalmente toma de 1 a 5 minutos, por lo que la API utiliza llamadas asíncronas. El flujo de trabajo consta de dos pasos principales: "Crear una tarea -> Sondear el resultado". Los pasos son los siguientes:

Paso 1: Crear una tarea para obtener un ID de tarea

Región de Singapur: 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

Encabezados

Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave de 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 conocer las especificaciones de salida del modelo, consulte Lista de modelos.Valores válidos:

pixverse/pixverse-v6-r2v

input object (Obligatorio)La información de entrada básica, que incluye las imágenes de referencia y la indicación de texto.

Propiedades

prompt string (Obligatorio)La indicación de texto. Describe los elementos deseados y las características visuales del video generado.Se admiten tanto chino como inglés. Cada carácter chino o letra cuenta como un carácter. La codificación de caracteres es UTF-8. Los caracteres que excedan el límite se truncan automáticamente.

pixverse/pixverse-v6-r2v: Hasta 2,048 caracteres.

Instrucciones de referencia de imágenes: Cuando pasa una imagen de referencia en el parámetro media, puede hacer referencia a ella directamente en el prompt mediante @ref_name.

El ref_name establecido en media debe ser único de forma global dentro de la misma solicitud y debe corresponderse uno a uno con las referencias del prompt.
Regla de formato: Debe dejar un espacio después de @ref_name como separador.

Ejemplos:

Prompt simple: Un hombre se sienta en una silla junto a la ventana, sosteniendo una guitarra, y toca una relajante canción folk country estadounidense junto a una cafetería.
Prompt con referencias: @man se sienta en una silla junto a la ventana, sosteniendo @guitar , y toca una relajante canción folk country estadounidense junto a @coffeeshop .

media array (Obligatorio)Una lista de recursos multimedia que especifica las imágenes de referencia necesarias para la generación del video.Cada elemento de la matriz es un objeto multimedia que contiene los campos type y url.

Propiedades de los elementos

type string (Obligatorio)El tipo de recurso multimedia. Valor fijo:

image_url: Una URL de imagen.

Límite de cantidad de recursos: Hasta 7 imágenes.url string (Obligatorio)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.jpg.

Restricciones de imagen:

Formato: JPG, PNG o WEBP.
Resolución: El ancho y el alto de la imagen no pueden superar los 10,000 píxeles.
Tamaño de archivo: Hasta 20 MB.

ref_name string (Opcional)El identificador de nombre del sujeto de la imagen de referencia. Se utiliza para hacer referencia a la imagen en el prompt con @ref_name. Hasta 30 caracteres.

parameters object (Obligatorio)Los parámetros de generación de video, como la resolución, la duración y si se genera audio.

Propiedades

size string (Obligatorio)La resolución del video generado, en formato width*height en píxeles.La siguiente tabla enumera los valores válidos para los distintos niveles de resolución.

Modelo pixverse/pixverse-v6-r2v

Nivel de resolución	Relación de aspecto	Valor de size (width*height)
360P	16:9	640*360
	4:3	640*480
	1:1	640*640
	3:4	480*640
	9:16	360*640
	3:2	640*432
	2:3	432*640
	21:9	640*288
540P	16:9	1024*576
	4:3	1024*768
	1:1	1024*1024
	3:4	768*1024
	9:16	576*1024
	3:2	1024*688
	2:3	688*1024
	21:9	1024*448
720P	16:9	1280*720
	4:3	1108*832
	1:1	960*960
	3:4	832*1108
	9:16	720*1280
	3:2	1200*800
	2:3	800*1200
	21:9	1280*560
1080P	16:9	1920*1080
	4:3	1664*1248
	1:1	1440*1440
	3:4	1248*1664
	9:16	1080*1920
	3:2	1776*1184
	2:3	1184*1776
	21:9	1920*832

Ejemplo: 1280*720.duration integer (Obligatorio)

El parámetro duration afecta directamente el costo. Antes de realizar una llamada, confirme los precios de PixVerse - Video de referencia.

La duración del video generado, en segundos.

pixverse/pixverse-v6-r2v: Un entero en el rango [1, 15].

Ejemplo: 5.audio boolean (Opcional)

El parámetro audio afecta directamente el costo. Antes de realizar una llamada, confirme los precios de PixVerse - Video de referencia.

Especifica si se genera un video con audio. Si se habilita, el modelo genera automáticamente música de fondo o efectos de sonido acordes al contenido del video.

false: Valor predeterminado. Genera un video sin sonido.
true: Genera un video con audio.

Ejemplo: false.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 muestra el texto fijo "AI Generated".

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

Ejemplo: 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.

Video de referencia
SDK de Python
Video de referencia (con ref_name)

Pase las imágenes de referencia mediante media y establezca size y duration para controlar la resolución y la duración del video.

# Replace {WorkspaceId} with your actual workspace ID.
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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

import dashscope
import os
from dashscope.v2 import DashScopeError

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si la variable de entorno no está configurada, establezca directamente su clave de API de Model Studio: api_key="sk-xxx"
    # Las claves de API son específicas de cada región. Para obtener una clave de API, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

media = [{'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png'}]

def sample_async_call():
    # Envía la tarea de generación de video de forma asíncrona
    # audio no forma parte de la firma con nombre y se pasa a través de parameters
    try:
        job = client.videos.jobs.create(model='pixverse/pixverse-v6-r2v',
                                        media=media,
                                        prompt='A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop',
                                        size='1280*720',
                                        duration=5,
                                        watermark=True,
                                        parameters={'audio': False})
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"Código de estado HTTP: {e.status_code}")
        print(f"Código de error: {e.code}")
        print(f"Mensaje de error: {e.message}")
        print("Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Consulta el estado de la tarea
    try:
        snapshot = client.videos.jobs.fetch(job.task_id)
        print(snapshot.status)
    except DashScopeError as e:
        print(f"Código de estado HTTP: {e.status_code}")
        print(f"Código de error: {e.code}")
        print(f"Mensaje de error: {e.message}")
        print("Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

    # Espera a que la tarea finalice
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"Código de estado HTTP: {e.status_code}")
        print(f"Código de error: {e.code}")
        print(f"Mensaje de error: {e.message}")
        print("Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call()

Pase las imágenes de referencia en media y pase ref_name para establecer el nombre del sujeto de cada imagen de referencia.

# Replace {WorkspaceId} with your actual workspace ID.
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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg",
                "ref_name": "man"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "ref_name": "guitar"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "coffeeshop"
            }
        ],
        "prompt": "@man sits on a chair by the window, holding @guitar , playing a soothing American country folk song next to @coffeeshop "
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

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: La tarea está en cola.
RUNNING: La tarea se está procesando.
SUCCEEDED: La tarea se completó correctamente.
FAILED: La tarea falló.
CANCELED: La tarea fue cancelada.
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

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. Utilice un mecanismo de sondeo y consulte 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 la API devolverá un estado de tarea UNKNOWN.
Límite de RPS: El endpoint 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 de 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 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

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: La tarea está en cola.
RUNNING: La tarea se está procesando.
SUCCEEDED: La tarea se completó correctamente.
FAILED: La tarea falló.
CANCELED: La tarea fue cancelada.
UNKNOWN: La tarea no existe o se desconoce su estado.

Transiciones de estado durante el sondeo:

PENDING (en cola) → RUNNING (procesando) → SUCCEEDED (exitoso) / FAILED (fallido).
El estado inicial de la consulta suele ser PENDING (en cola) o RUNNING (procesando).
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 vuelva a intentarlo.
Si el estado es CANCELED, la tarea fue cancelada. Para continuar, envíe la tarea de nuevo.
Si el estado es UNKNOWN, la tarea no existe o se desconoce su estado. Esto puede ocurrir si el task_id no existe o ha superado su período de validez de 24 horas.

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_url stringLa URL del video. Se devuelve solo cuando task_status es SUCCEEDED.El video está en formato MP4 (codificación H.264). Actualmente, el enlace del video no caduca, pero no dependa de él para el almacenamiento a largo plazo. 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 de salida, contadas solo para tareas exitosas.

Propiedades

duration integerLa duración total del video generado, utilizada para la facturación.size stringLa resolución del video generado.fps integerLa tasa de cuadros del video generado.SR stringEl nivel de resolución del video generado.audio booleanIndica si el video generado tiene audio.video_count integerEl número de videos generados. Este valor es fijo en 1.

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

Tarea exitosa
Tarea fallida
Consulta de tarea caducada

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "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 size is not match xxxxxx"
    }
}

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

FAQ

P: ¿Cómo optimizo el resultado si el prompt no funciona bien?

R: Pruebe a utilizar @ref_name como alternativa.

Método predeterminado: Utilice el prompt directamente. El modelo analiza automáticamente el contenido de las imágenes de referencia de forma global, lo que funciona en la mayoría de los escenarios habituales.
Método alternativo: Si el resultado generado se desvía de lo esperado, utilice @ref_name para especificar la imagen de referencia en el prompt y mejorar el resultado.

P: ¿Cómo utilizo ref_name?

R: ref_name crea un vínculo entre una imagen de referencia y el prompt. Después de establecer ref_name para una imagen en la matriz media, puede hacer referencia al sujeto correspondiente de la imagen de referencia en el prompt mediante la sintaxis @ref_name.

Por ejemplo, si establece "ref_name": "kitten" en media, utilice @kitten en el prompt para hacer referencia a ese sujeto. Nota: Debe dejar un espacio después de @kitten.
Ejemplo: @kitten y @puppy juegan en el césped.

​Activar el servicio

​Notas de uso

​Llamadas HTTP

​Paso 1: Crear una tarea para obtener un ID de tarea

Parámetros de solicitud

Encabezados

Cuerpo de la solicitud

Parámetros de respuesta

​Paso 2: Consultar el resultado por ID de tarea

Parámetros de solicitud

Encabezados

Parámetros de ruta

Parámetros de respuesta

​Códigos de error

​FAQ

​P: ¿Cómo optimizo el resultado si el prompt no funciona bien?

​P: ¿Cómo utilizo ref_name?

Activar el servicio

Notas de uso

Llamadas HTTP

Paso 1: Crear una tarea para obtener un ID de tarea

Paso 2: Consultar el resultado por ID de tarea

Códigos de error

FAQ

P: ¿Cómo optimizo el resultado si el prompt no funciona bien?

P: ¿Cómo utilizo ref_name?