Skip to main content

Referência da API PixVerse - texto para vídeo

O modelo de texto para vídeo PixVerse gera um vídeo fluido com base em um prompt de texto.

Este documento se aplica somente à região de Singapura. Use uma chave de API dessa região.

Ativar o serviço

  1. Acesse o console do Model Studio, pesquise por PixVerse, encontre o cartão do modelo PixVerse e clique em Activate Now.
  2. Na janela pop-up, confirme a ativação e a autorização.

Notas de uso

Para que as chamadas de API sejam bem-sucedidas, use um modelo, uma URL de endpoint e uma chave de API da mesma região. Chamadas entre regiões falharão.
O código de exemplo deste tópico se aplica à região de Singapura.

Chamadas HTTP

A geração de vídeo a partir de texto costuma levar de 1 a 5 minutos, por isso a API usa chamadas assíncronas. O fluxo tem duas etapas principais: "Criar uma tarefa -> Consultar periodicamente o resultado". As etapas são as seguintes:

Etapa 1: criar uma tarefa para obter o ID da tarefa

Região de Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Após criar a tarefa, use o task_id retornado para consultar o resultado. O task_id é válido por 24 horas. Não crie tarefas duplicadas. Consulte periodicamente o resultado.
  • Para orientações iniciais, consulte Chamar APIs com Postman ou cURL.

Parâmetros de solicitação

Cabeçalhos
Content-Type string (Obrigatório)O tipo de conteúdo da solicitação. Deve ser application/json.Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.X-DashScope-Async string (Obrigatório)Ativa o processamento assíncrono. As solicitações HTTP permitem apenas chamadas assíncronas. Deve ser enable.
Se esse cabeçalho de solicitação estiver ausente, será retornado o erro "current user api does not support synchronous calls".
Corpo da solicitação
model string (Obrigatório)O nome do modelo.Valores válidos:
  • pixverse/pixverse-v6-t2v
input object (Obrigatório)As informações básicas de entrada, como o prompt.

Propriedades

prompt string (Obrigatório)O prompt de texto. Ele descreve os elementos e as características visuais desejados no vídeo gerado.Há suporte para chinês e inglês. Cada caractere chinês ou letra conta como um caractere. A codificação de caracteres é UTF-8. Os caracteres excedentes são truncados automaticamente.
  • pixverse/pixverse-v6-t2v: até 5.000 caracteres.
parameters object (Obrigatório)Os parâmetros de geração de vídeo, como a resolução, a duração e se o vídeo terá áudio.

Propriedades

size string (Obrigatório)A resolução do vídeo gerado, no formato width*height, em pixels.
O parâmetro size afeta diretamente o custo. Antes de fazer a chamada, confira os preços dos modelos.
A tabela a seguir lista os valores válidos para diferentes faixas de resolução e proporções.

Modelo pixverse/pixverse-v6-t2v

Faixa de resolução

Proporção

Valor de size (largura*altura)

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 (Obrigatório)
O parâmetro duration afeta diretamente o custo, cobrado por segundo. Antes de fazer a chamada, confira os preços dos modelos.
A duração do vídeo gerado, em segundos.
  • pixverse/pixverse-v6-t2v: um número inteiro no intervalo [1, 15].
audio boolean (Opcional)
O parâmetro audio afeta diretamente o custo. Antes de fazer a chamada, confira os preços dos modelos.
Especifica se será gerado um vídeo com áudio. Se ativado, o modelo gera automaticamente música de fundo ou efeitos sonoros correspondentes ao conteúdo do vídeo.
  • false: Valor padrão. Gera um vídeo sem som.
  • true: Gera um vídeo com áudio.
watermark boolean (Opcional)Especifica se uma marca-d’água será adicionada. Ela fica no canto inferior direito do vídeo e exibe o texto fixo "AI Generated".
  • false: Valor padrão. Nenhuma marca-d’água é adicionada.
  • true: Uma marca-d’água é adicionada.
shot_type string (Opcional)Modelo compatível: pixverse/pixverse-v6-t2v.Especifica o tipo de tomada do vídeo gerado. Controla se o vídeo é composto por uma única tomada contínua ou por várias tomadas.
  • single: Valor padrão. Gera um vídeo de tomada única.
  • multi: Várias tomadas. O sistema segmenta as tomadas de forma inteligente.
Sugestão de uso: o parâmetro prompt tem prioridade maior que shot_type. Para obter os melhores resultados, recomendamos que a configuração deste parâmetro seja coerente com a descrição do prompt.
  • Para gerar sempre um vídeo de tomada única: defina shot_type="single" e descreva uma cena de tomada única no prompt.
  • Para gerar sempre um vídeo com várias tomadas: defina shot_type="multi" e descreva uma cena com várias tomadas no prompt.
seed integer (Opcional)A semente aleatória deve ser um número inteiro no intervalo [0, 2147483647].Se não for especificada, uma semente aleatória será gerada. Uma semente fixa melhora a reprodutibilidade.Como a geração do modelo é probabilística, a mesma semente não garante resultados idênticos.
  • Texto para vídeo
  • Texto para vídeo (várias tomadas)
Modelo compatível: 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 resposta

output objectInformações de saída da tarefa.

Propriedades

task_id stringO ID da tarefa. Válido para consultas por 24 horas.task_status stringO status da tarefa.

Valores de enumeração

  • PENDING: a tarefa está na fila.
  • RUNNING: a tarefa está em processamento.
  • SUCCEEDED: a tarefa foi concluída com sucesso.
  • FAILED: a tarefa falhou.
  • CANCELED: a tarefa foi cancelada.
  • UNKNOWN: a tarefa não existe ou seu status é desconhecido.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
  • Resposta de sucesso
  • Resposta de erro
Salve o task_id para consultar o status e o resultado da tarefa.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Etapa 2: consultar o resultado pelo ID da tarefa

Região de Singapura: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recomendação de consulta periódica: A geração do vídeo pode levar vários minutos. Use um mecanismo de consulta periódica e consulte o resultado em intervalos razoáveis, por exemplo, a cada 15 segundos.
  • Fluxo de status da tarefa: PENDING (na fila) → RUNNING (em processamento) → SUCCEEDED (sucesso) / FAILED (falha).
  • Validade do ID da tarefa: O task_id é válido por 24 horas. Após esse período, as consultas falham e a API retorna o status de tarefa UNKNOWN.
  • Limite de RPS: O endpoint de consulta tem limite padrão de 20 RPS. Para consultas frequentes ou notificações de eventos, configure callbacks de tarefas assíncronas.
  • Outras operações: Para consultas em lote, cancelamento de tarefas e outras operações, consulte Gerenciar tarefas assíncronas.

Parâmetros de solicitação

Cabeçalhos
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho
task_id string (Obrigatório)O ID da tarefa.
  • Consultar resultado da tarefa
Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id é válido para consultas por 24 horas. Substitua {WorkspaceId} pelo seu ID do workspace 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 resposta

output objectInformações de saída da tarefa.

Propriedades

task_id stringO ID da tarefa. Válido para consultas por 24 horas.task_status stringO status da tarefa.

Valores de enumeração

  • PENDING: a tarefa está na fila.
  • RUNNING: a tarefa está em processamento.
  • SUCCEEDED: a tarefa foi concluída com sucesso.
  • FAILED: a tarefa falhou.
  • CANCELED: a tarefa foi cancelada.
  • UNKNOWN: a tarefa não existe ou seu status é desconhecido.
Transições de status durante as consultas periódicas:
  • PENDING (na fila) → RUNNING (em processamento) → SUCCEEDED (sucesso) / FAILED (falha).
  • O status da consulta inicial geralmente é PENDING (na fila) ou RUNNING (em processamento).
  • Quando o status muda para SUCCEEDED, a resposta contém a URL do vídeo gerado.
  • Se o status for FAILED, verifique a mensagem de erro e tente novamente.
  • Se o status for CANCELED, a tarefa foi cancelada. Para continuar, envie a tarefa novamente.
  • Se o status for UNKNOWN, a tarefa não existe ou seu status é desconhecido. Isso pode ocorrer se o task_id não existir ou tiver ultrapassado o período de validade de 24 horas.
submit_time stringO horário de envio da tarefa. Formato: YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringO horário de execução da tarefa. Formato: YYYY-MM-DD HH:mm:ss.SSS.end_time stringO horário de conclusão da tarefa. Formato: YYYY-MM-DD HH:mm:ss.SSS.video_url stringA URL do vídeo. Retornada somente quando task_status é SUCCEEDED.O vídeo está no formato MP4 (codificação H.264). No momento, o link do vídeo não expira, mas não se destina ao armazenamento de longo prazo. Baixe o vídeo o quanto antes.orig_prompt stringO prompt de entrada original, correspondente ao parâmetro de solicitação prompt.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
usage objectEstatísticas de uso de saída, contabilizadas apenas para tarefas bem-sucedidas.

Propriedades

duration integerA duração total do vídeo gerado, em segundos, usada para faturamento.size stringA resolução do vídeo gerado.fps integerA taxa de quadros do vídeo gerado.SR stringA faixa de resolução do vídeo gerado.audio booleanIndica se o vídeo gerado tem áudio.video_count integerO número de vídeos gerados. O valor é fixo em 1.shot_type stringO tipo de tomada do vídeo gerado.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.
  • Tarefa bem-sucedida
  • Falha na tarefa
  • Consulta da tarefa expirada
{
    "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"
    }
}

Chamadas com o DashScope SDK

Os nomes dos parâmetros no SDK são, em grande parte, os mesmos da API HTTP. A estrutura dos parâmetros é adaptada aos recursos de cada linguagem de programação. Como as tarefas de texto para vídeo levam bastante tempo (normalmente de 1 a 5 minutos), o SDK encapsula o processo de chamada assíncrona HTTP e permite chamadas síncronas e assíncronas.
O tempo real necessário depende do número de tarefas na fila e do status de execução do serviço. Aguarde o resultado com paciência.

Chamadas com o SDK para Python

Antes de executar o código a seguir, verifique se a versão do DashScope SDK para Python não é anterior à 2.0.1.Uma versão anterior pode gerar erros como "url error, please check url!". Para atualizar o SDK, consulte Instalar o SDK.
Região de Singapura: region="ap-southeast-1" Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Chamada síncrona
  • Chamada assíncrona
Exemplo de solicitação
import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha a seguir pela sua API Key do Model Studio: api_key="sk-xxx"
    # As API Keys variam conforme a região. Para obter uma API Key, 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():
    # Chama a API síncrona, que retorna o resultado diretamente.
    print('please wait...')
    # generate é uma chamada de uma etapa (envia a tarefa e aguarda a conclusão) e retorna um Job concluído
    # audio não faz parte da assinatura nomeada e é passada via 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"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_t2v()
Exemplo de resposta
No momento, video_url não expira, mas não se destina ao armazenamento de longo prazo. Baixe o vídeo o quanto antes.
{
    "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"
    }
}

Chamadas com o SDK para Java

Antes de executar o código a seguir, verifique se a versão do DashScope SDK para Java não é anterior à 2.22.6.Uma versão anterior pode gerar erros como "url error, please check url!". Para atualizar o SDK, consulte Instalar o SDK.
Região de Singapura: Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"; Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Chamada síncrona
  • Chamada assíncrona
Exemplo de solicitação
// 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);
    }
}
Exemplo de resposta
No momento, video_url não expira, mas não se destina ao armazenamento de longo prazo. Baixe o vídeo o quanto antes.
{
    "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 erro

Se a chamada ao modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolver o problema.