O modelo de vídeo com referência PixVerse aceita várias imagens de referência. Ele usa um prompt de texto para descrever a cena e combina os personagens dos recursos em um vídeo fluido.
Ativar o serviço
- Acesse o console do Model Studio, pesquise por PixVerse, encontre o cartão do modelo PixVerse e clique em Activate Now.
- 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.
- Selecionar um modelo: Confirme a região em que o modelo está localizado.
- Selecionar uma URL: Escolha a URL do endpoint da região correspondente. Há suporte para URLs HTTP e do DashScope SDK.
- Configurar uma chave de API: Selecione uma região, obtenha uma chave de API e configure-a como variável de ambiente.
Chamadas HTTP
A geração de vídeo com referência 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_idretornado para consultar o resultado. Otask_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çãoCabeçalhosContent-Typestring (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.Corpo da solicitaçãomodelstring (Obrigatório)O nome do modelo. Para as especificações de saída dos modelos, consulte a Lista de modelos.Valores válidos:
object (Obrigatório)As informações básicas de entrada, incluindo as imagens de referência e 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.
@ref_name.
array (Obrigatório)Uma lista de recursos de mídia que especifica as imagens de referência necessárias para a geração do vídeo.Cada elemento do array é um objeto de mídia que contém os campos type e url.
Propriedades do elemento type string (Obrigatório)O tipo do recurso de mídia. Valor fixo:
string (Obrigatório)A URL da imagem de referência. A URL deve ser acessível publicamente.
string (Opcional)O identificador de nome do sujeito na imagem de referência. É usado para referenciar a imagem no prompt com @ref_name. Até 30 caracteres.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.A tabela a seguir lista os valores válidos para diferentes faixas de resolução.
Modelo pixverse/pixverse-v6-r2v
integer (Obrigatório)A duração do vídeo gerado, em segundos.
boolean (Opcional)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.
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".
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. |
Passe as imagens de referência em media e defina size e duration para controlar a resolução e a duração do vídeo. |
Parâmetros de respostaoutputobjectInformaçõ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
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. |
Salve o task_id para consultar o status e o resultado da tarefa. |
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 tarefaUNKNOWN. - 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çãoCabeçalhosAuthorizationstring (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.Parâmetros de caminhotask_idstring (Obrigatório)O ID 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. |
Parâmetros de respostaoutputobjectInformaçõ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
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 dependa dele para 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.objectEstatísticas de uso de saída, contabilizadas apenas para tarefas bem-sucedidas.
Propriedades duration integerA duração total do vídeo gerado, 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.stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. |
|
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.
Perguntas frequentes
P: Como otimizar o resultado se o prompt não funcionar bem?
R: Tente usar @ref_name como alternativa.
- Método padrão: use o prompt diretamente. O modelo analisa automaticamente o conteúdo das imagens de referência de forma global, o que funciona para a maioria dos cenários comuns.
- Método alternativo: se o resultado gerado não corresponder ao esperado, use
@ref_namepara especificar a imagem de referência no prompt e melhorar o resultado.
P: Como usar ref_name?
R: ref_name cria um vínculo entre uma imagem de referência e o prompt. Depois de definir ref_name para uma imagem no array media, você pode referenciar o sujeito correspondente da imagem de referência no prompt usando a sintaxe @ref_name.
- Por exemplo, se você definir
"ref_name": "kitten"em media, use@kittenno prompt para referenciar esse sujeito. Observação: deixe um espaço após @kitten. - Exemplo: @kitten e @puppy estão brincando na grama.