Skip to main content

Referência da API de vídeo com referência Vidu

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.
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_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 da solicitação
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 modelo a usar. Valores válidos:
  • vidu/viduq3-ad_reference2video
  • vidu/viduq3-drama_reference2video
  • vidu/viduq3-mix_reference2video

Guia de seleção de modelos

  • Vídeos publicitários: Use viduq3-ad. Projetado para publicidade, oferece transições inteligentes entre planos e movimentos de câmera voltados ao marketing, além de saída direta de áudio. Envie imagens de produtos para gerar vídeos publicitários.
  • Dramas de alta qualidade / quadrinhos de IA: Use viduq3-drama. Com alta consistência de personagens, efeitos refinados e expressão emocional realista, é ideal para produzir conteúdo narrativo.
  • Uso geral: Use viduq3-mix. O equilíbrio entre qualidade visual e efeitos dinâmicos atende à maioria dos cenários de vídeo com referência.
input 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:
  • image: Imagem de referência.
Limite de recursos: de 1 a 7 imagens.
url 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.Limites de imagem:
  • Formatos: JPEG, JPG, PNG e WEBP.
  • Proporção: de 1:4 a 4:1.
  • Tamanho do arquivo: até 50 MB.
parameters object (obrigatório)Parâmetros de geração de vídeo, como resolução e duração.

Propriedades

resolution string (opcional)
A resolução afeta diretamente a cobrança. Antes de chamar a API, confira os preços dos modelos.
A resolução do vídeo gerado. Os valores válidos dependem do modelo selecionado:
  • vidu/viduq3-ad_reference2video: 720P ou 1080P. Padrão: 720P.
  • vidu/viduq3-drama_reference2video: 720P ou 1080P. Padrão: 1080P.
  • vidu/viduq3-mix_reference2video: 720P ou 1080P. Padrão: 720P.
size string (opcional)A resolução do vídeo gerado, em pixels, no formato width*height.O valor padrão depende de resolution:
  • Quando resolution=720P, o padrão de size é 1280*720.
  • Quando resolution é 1080P, o padrão de size é 1920*1080.
As proporções compatíveis variam conforme o modelo:
  • vidu/viduq3-drama_reference2video: Somente 16:9 e 9:16 são compatíveis.
  • Outros modelos: 16:9, 4:3, 1:1, 3:4 e 9:16 são compatíveis.
Valores de size válidos por faixa de resolução:
  • 720P
    • 16:9: 1280*720
    • 4:3: 1280*960
    • 1:1: 1280*1280
    • 3:4: 960*1280
    • 9:16: 720*1280
  • 1080P
    • 16:9: 1920*1080
    • 4:3: 1920*1440
    • 1:1: 1920*1920
    • 3:4: 1440*1920
    • 9:16: 1080*1920
duration integer (obrigatório)
A duração afeta diretamente a cobrança, calculada por segundo. Antes de chamar a API, confira os preços dos modelos.
A duração do vídeo gerado, em segundos.
  • vidu/viduq3-ad_reference2video: Um inteiro no intervalo [3, 15]. O padrão é 5.
  • vidu/viduq3-drama_reference2video: Um inteiro no intervalo [2, 15]. O padrão é 5.
    • Se o número de planos for excessivo ou muito baixo em relação à duração, o modelo poderá ajustar automaticamente o comprimento do vídeo para manter a integridade da história. A duração real poderá ser maior ou menor que a especificada.
    • A cobrança é calculada com base na duração real da saída.
  • vidu/viduq3-mix_reference2video: O valor é um inteiro no intervalo [1, 16]. O padrão é 5.
audio 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.
  • false: Valor padrão. A saída é um vídeo sem áudio.
  • true: Produz um vídeo com áudio.
vidu/viduq3-drama_reference2video não aceita esse parâmetro. Esse modelo produz vídeos com áudio por padrão.
watermark boolean (opcional)Especifica se será adicionada uma marca-d’água no canto inferior direito do vídeo. O texto é fixo: "Content generated by AI".
  • false: Valor padrão. Nenhuma marca-d’água é adicionada.
  • true: Adiciona uma marca-d’água.
seedinteger(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
  • Publicidade (somente imagem)
  • Drama (somente imagem)
  • Somente imagem
Modelo compatível: vidu/viduq3-ad_reference2video.
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": "vidu/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Parâmetros de resposta

  • 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"
}
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

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: a tarefa não existe ou seu status é desconhecido.
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ção

Cabeçalhos da solicitação
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
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

outputobjectOs 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

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: a tarefa não existe ou seu status é desconhecido.
Transições de status durante as consultas periódicas:
  • PENDING → RUNNING → SUCCEEDED ou FAILED.
  • O status da consulta inicial geralmente é PENDING ou RUNNING.
  • 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 executar a tarefa novamente.
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_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.
usage 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.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.
  • Tarefa bem-sucedida
  • Falha na tarefa
  • Consulta da tarefa expirada
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.
{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

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ão resolution=720P e o valor padrão correspondente de size (1280*720).
    Exemplo: a API retorna size="1280*720" e SR=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" e SR=540. Se definir resolution=1080P, retornará size="1920*1080" e SR=1080.