PixVerse - Referencia de API de imagen a video desde los cuadros inicial y final - Alibaba Cloud Model Studio

El modelo de cuadros inicial y final a video de PixVerse genera un video con una transición fluida a partir de una imagen de cuadro inicial, una imagen de cuadro final y una indicación de texto.

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

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

Llamadas HTTP

La generación de video a partir de los cuadros inicial y final 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.

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.

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.

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.

Valores válidos:

pixverse/pixverse-v6-kf2v

input object (Obligatorio)

La información de entrada básica, que incluye la imagen del cuadro inicial, la imagen del cuadro final y la indicación de texto.

Propiedades

prompt string (Obligatorio)

La indicación de texto. Describe el proceso de transición desde el cuadro inicial hasta el cuadro final.

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-kf2v: Hasta 5,000 caracteres.

media array (Obligatorio)

Una lista de recursos multimedia que contiene las imágenes del cuadro inicial y del cuadro final.

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

Propiedades

type string (Obligatorio)

El tipo de recurso multimedia.

first_frame: La imagen del cuadro inicial.
last_frame: La imagen del cuadro final.

Limitación de recursos:

Imagen del cuadro inicial: Exactamente una.
Imagen del cuadro final: Exactamente una.

url string (Obligatorio)

La URL de la imagen, accesible públicamente.

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

Restricciones de imagen:

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

parameters object (Obligatorio)

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

Propiedades

resolution string (Obligatorio)

ImportanteEl parámetro resolution afecta directamente el costo. Antes de realizar una llamada, confirme los precios del modelo.

La resolución del video generado.

Valores válidos: 360P, 540P, 720P y 1080P.

duration integer (Obligatorio)

ImportanteEl parámetro duration afecta directamente el costo. Antes de realizar una llamada, confirme los precios del modelo.

La duración del video generado, en segundos.

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

audio boolean (Opcional)

ImportanteEl parámetro audio afecta directamente el costo. Antes de realizar una llamada, confirme los precios del modelo.

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.

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.

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.

Cuadros inicial y final a video

Modelo compatible: pixverse/pixverse-v6-kf2v.

# 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-kf2v",
    "input": {
        "media": [
            {
                "type": "first_frame",
                "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
            },
            {
                "type": "last_frame",
                "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
            }
        ],
        "prompt": "A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5,
        "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: 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 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": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-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}

Nota

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 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: 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 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_url string

La 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 está pensado para el almacenamiento a largo plazo. 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 de salida, contadas solo para tareas exitosas.

Propiedades

duration integer

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

size string

La resolución del video generado.

fps integer

La tasa de cuadros del video generado.

SR string

El nivel de resolución del video generado.

audio boolean

Indica si el video generado tiene audio.

video_count integer

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

request_id string

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

Tarea exitosa

{
    "request_id": "40799260-689c-4c44-9d7c-xxxxxx",
    "output": {
        "task_id": "408b6c3b-27c9-43dd-b928-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 13:47:42.916",
        "scheduled_time": "2026-03-20 13:47:42.949",
        "end_time": "2026-03-20 13:48:41.896",
        "orig_prompt": "A kitten jumps down from the windowsill, lands lightly on the sofa, and then looks around curiously.",
        "video_url": "https://media.pixverseai.cn/xxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*960",
        "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 la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para solucionarlo.

FAQ

P: ¿Existe un orden obligatorio para los cuadros inicial y final en la matriz media?

R: La matriz media debe contener dos objetos, con type establecido en first_frame (cuadro inicial) y last_frame (cuadro final), respectivamente. El orden no afecta el resultado. El sistema identifica automáticamente cada imagen en función del campo type.

P: ¿Las imágenes del cuadro inicial y del cuadro final deben tener la misma resolución?

R: No. Las imágenes del cuadro inicial y del cuadro final pueden tener resoluciones diferentes. El sistema las procesa automáticamente.

La relación de aspecto del video de salida sigue aproximadamente la de la imagen del cuadro inicial. La resolución se adapta automáticamente a un recuento total de píxeles similar según el nivel de resolution seleccionado (como 720P).