O modelo de vídeo com referência Vidu usa uma imagem de referência e um prompt de texto. Ele incorpora o sujeito da imagem à cena descrita pelo prompt para gerar um vídeo fluido.
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 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.
O código de exemplo deste tópico se aplica à região de Singapura.
Chamadas HTTP
Como as tarefas de vídeo com referência costumam levar de 1 a 5 minutos, a API usa chamadas assíncronas. O processo tem duas etapas principais: "Criar uma tarefa -> Consultar periodicamente o resultado".
Etapa 1: criar uma tarefa
Região de Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
- 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çalhos da solicitaçãoContent-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 modelo a usar. Valores válidos:
Guia de seleção de modelos
object (obrigatório)A entrada básica, incluindo imagens de referência e um prompt.
Propriedades prompt string (obrigatório)O prompt de texto que descreve os elementos e as características visuais desejados no vídeo gerado.Há suporte para chinês e inglês. O comprimento máximo é de 5.000 caracteres. O texto que exceder o limite será truncado automaticamente.Exemplo: um homem está sentado em uma cadeira junto à janela de um café, segurando um violão e tocando uma canção folk country americana relaxante.media array (obrigatório)Uma lista de recursos de mídia que especifica os materiais de referência para gerar o 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. Os valores válidos dependem do modelo selecionado.
Fornecer apenas imagens de referência Modelos compatíveis: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2videoO valor é fixo como:
string (obrigatório)A URL do recurso de mídia.
Fornecer uma imagem (type=image) A URL da imagem de referência. Deve ser acessível publicamente.
object (obrigatório)Parâmetros de geração de vídeo, como resolução e duração.
Propriedades resolution string (opcional)A resolução do vídeo gerado. Os valores válidos dependem do modelo selecionado:
string (opcional)A resolução do vídeo gerado, em pixels, no formato width*height.O valor padrão depende de resolution:
integer (obrigatório)A duração do vídeo gerado, em segundos.
boolean (opcional)Modelos compatíveis: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.Especifica se será gerado um vídeo com áudio. Quando ativado, o modelo gera automaticamente música de fundo ou efeitos sonoros adequados ao conteúdo.
vidu/viduq3-drama_reference2video não aceita esse parâmetro. Esse modelo produz vídeos com áudio por padrão. boolean (opcional)Especifica se será adicionada uma marca-d’água no canto inferior direito do vídeo. O texto é fixo: "Content generated by AI".
integer(opcional)A semente. O intervalo de valores é [0, 2147483647].Se você não especificar uma semente, o sistema gerará uma aleatoriamente. Para melhorar a reprodutibilidade dos resultados, recomendamos definir uma semente fixa.Devido à natureza probabilística do modelo, a mesma semente não garante resultados idênticos entre execuções.Exemplo: 12345 |
Modelo compatível: vidu/viduq3-ad_reference2video. |
Parâmetros de resposta |
Salve o task_id para consultar o status e o resultado da tarefa. |
output objectOs dados 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
| |
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. | |
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro. |
Etapa 2: consultar o resultado 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. Recomendamos a consulta periódica em intervalos razoáveis (por exemplo, 15 segundos) para obter o resultado.
- Transições de status da tarefa: PENDING (na fila) → RUNNING (em andamento) → SUCCEEDED (sucesso) / FAILED (falha).
- Período de validade do task_id: 24 horas. Após o prazo de validade, não é mais possível consultar o resultado, e a API retorna o status
UNKNOWN. - Limite de RPS: A API de consulta tem limite padrão de 20 RPS. Para consultas mais frequentes ou notificações de eventos, recomendamos configurar callbacks de tarefas assíncronas.
- Outras operações: Para operações como consultas de tarefas em lote ou cancelamento, consulte Gerenciar tarefas assíncronas.
Parâmetros de solicitaçãoCabeçalhos da solicitaçãoAuthorizationstring (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 |
Parâmetros de respostaoutputobjectOs dados 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_urlstringA URL do vídeo. Este parâmetro é retornado somente quando task_status é SUCCEEDED.O vídeo está no formato MP4 (codificação H.264). A URL é válida por 24 horas. 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 (somente tarefas bem-sucedidas).
Propriedades duration integerA duração total do vídeo gerado, usada para cobrança.size stringEspecifica a resolução do vídeo gerado.fps integerEspecifica a taxa de quadros do vídeo gerado. O valor é fixo em 24.SR stringEspecifica a faixa de resolução do vídeo gerado.audio booleanIndica se o vídeo gerado inclui áudio.video_count integerEspecifica o número de vídeos gerados. O valor é fixo em 1.reference_type stringEspecifica o tipo de material de referência usado.stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. |
As URLs de vídeo são válidas por apenas 24 horas e depois são excluídas automaticamente. Salve os vídeos gerados o quanto antes. |
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: Preciso fornecer size e resolution juntos?
R: Não. Ambos são opcionais, mas recomendamos fornecer os dois para controlar com precisão a proporção do vídeo gerado. Consulte Valores válidos de size.
Se você não fornecer os dois, o sistema tratará a solicitação da seguinte forma:
-
Somente size é fornecido: O parâmetro
sizeé ignorado, e o sistema usa o padrãoresolution=720Pe o valor padrão correspondente desize(1280*720).Exemplo: a API retorna
size="1280*720"eSR=720. -
Se você fornecer apenas
resolution: A saída usa a faixa de resolução especificada.Por exemplo, se você definir
resolution=540P, a API retornarásize="960*528"eSR=540. Se definirresolution=1080P, retornarásize="1920*1080"eSR=1080.