Skip to main content

PixVerse - Referencia de API de texto a video

El modelo de texto a video de PixVerse genera un video fluido a partir de una indicación de texto.

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

Activar el servicio

  1. Vaya a la consola de Model Studio, busque PixVerse, encuentre la tarjeta del modelo PixVerse y haga clic en Activate Now.
  2. 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.
El código de ejemplo en este tema aplica a la región de Singapur.

Llamadas HTTP

La generación de texto a video 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.Valores válidos:
  • pixverse/pixverse-v6-t2v
input object (Obligatorio)La información de entrada básica, como 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-t2v: Hasta 5,000 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.
El parámetro size afecta directamente el costo. Antes de realizar una llamada, confirme los precios del modelo.
La siguiente tabla enumera los valores válidos para los distintos niveles de resolución y relaciones de aspecto.

Modelo pixverse/pixverse-v6-t2v

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

duration integer (Obligatorio)
El parámetro duration afecta directamente el costo, que se factura por segundo. Antes de realizar una llamada, confirme los precios del modelo.
La duración del video generado, en segundos.
  • pixverse/pixverse-v6-t2v: Un entero en el rango [1, 15].
audio boolean (Opcional)
El 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.
shot_type string (Opcional)Modelo compatible: pixverse/pixverse-v6-t2v.Especifica el tipo de toma del video generado. Controla si el video consta de una sola toma continua o de varias tomas.
  • single: Valor predeterminado. Genera un video de una sola toma.
  • multi: Varias tomas. El sistema segmenta las tomas de forma inteligente.
Sugerencia de uso: El parámetro prompt tiene mayor prioridad que shot_type. Para obtener los mejores resultados, recomendamos que la configuración de este parámetro sea coherente con la descripción del prompt.
  • Para generar de forma coherente un video de una sola toma: Establezca shot_type="single" y describa una escena de una sola toma en el prompt.
  • Para generar de forma coherente un video de varias tomas: Establezca shot_type="multi" y describa una escena de varias tomas en el prompt.
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.
  • Texto a video
  • Texto a video (varias tomas)
Modelo compatible: pixverse/pixverse-v6-t2v.
# 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-t2v",
    "input": {
        "prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame."
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "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 está pensado 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 en segundos, 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.shot_type stringEl tipo de toma del video generado.
request_id stringIdentificador único de solicitud para rastreo y solución de problemas.
  • Tarea exitosa
  • Tarea fallida
  • Consulta de tarea caducada
{
    "request_id": "19171ea5-9efb-4d35-93a1-xxxxxx",
    "output": {
        "task_id": "7ed706b7-a9a9-4319-820c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 10:34:41.630",
        "scheduled_time": "2026-03-20 10:34:41.655",
        "end_time": "2026-03-20 10:35:12.725",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Llamadas del SDK de DashScope

Los nombres de los parámetros del SDK son en su mayoría coherentes con los de la API HTTP. La estructura de los parámetros se adapta a las características de cada lenguaje de programación. Dado que las tareas de texto a video tardan bastante tiempo (normalmente de 1 a 5 minutos), el SDK encapsula el proceso de llamada asíncrona HTTP y admite métodos de llamada tanto síncronos como asíncronos.
El tiempo real necesario depende del número de tareas en cola y del estado de ejecución del servicio. Espere pacientemente el resultado.

Llamadas del SDK de Python

Asegúrese de que la versión del SDK de DashScope para Python no sea anterior a 2.0.1 antes de ejecutar el siguiente código.Una versión anterior puede provocar errores como "url error, please check url!". Para actualizar el SDK, consulte Instalar el SDK.
Región de Singapur: region="ap-southeast-1" Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Llamada síncrona
  • Llamada asíncrona
Ejemplo de solicitud
import os
import dashscope
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",
)

def sample_sync_call_t2v():
    # Llama a la API síncrona, que devuelve el resultado directamente.
    print('Espere, por favor...')
    # generate es una llamada de un solo paso (envía la tarea y espera a que finalice) y devuelve un Job completado
    # audio no forma parte de la firma con nombre y se pasa a través de parameters
    try:
        job = client.videos.generate(model='pixverse/pixverse-v6-t2v',
                                     prompt='In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.',
                                     size='1280*720',
                                     duration=5,
                                     watermark=False,
                                     parameters={'audio': False})
        print(job)
        print(job.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_sync_call_t2v()
Ejemplo de respuesta
Actualmente, video_url no caduca, pero no está pensado para el almacenamiento a largo plazo. Descargue el video a la brevedad.
{
    "request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
    "task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "video_url": "https://media.pixverseai.cn/xxx.mp4"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "size": "1280x720",
        "fps": 24,
        "audio": false,
        "SR": "720"
    }
}

Llamadas del SDK de Java

Asegúrese de que la versión del SDK de DashScope para Java no sea anterior a 2.22.6 antes de ejecutar el siguiente código.Una versión anterior puede provocar errores como "url error, please check url!". Para actualizar el SDK, consulte Instalar el SDK.
Región de Singapur: Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"; Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
  • Llamada síncrona
  • Llamada asíncrona
Ejemplo de solicitud
// Replace {WorkspaceId} with your actual workspace ID.
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {

    static {
        // The following is the URL for the Singapore region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Create a video compositing task and wait for the task to complete.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("pixverse/pixverse-v6-t2v")
                        .prompt("In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.")
                        .size("1280*720")
                        .duration(5)
                        .audio(true)
                        .watermark(true)
                        .seed(12345)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
Ejemplo de respuesta
Actualmente, video_url no caduca, pero no está pensado para el almacenamiento a largo plazo. Descargue el video a la brevedad.
{
    "request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
    "output": {
        "task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://media.pixverseai.cn/xxx.mp4",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "submit_time": "2026-03-20 11:21:13.227",
        "scheduled_time": "2026-03-20 11:21:13.252",
        "end_time": "2026-03-20 11:21:43.924"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "size": "1280*720",
        "input_video_duration": 0.0,
        "output_video_duration": 0.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Códigos de error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para solucionarlo.