Skip to main content

Referência da API Vidu - imagem para vídeo a partir do quadro inicial

O modelo de imagem para vídeo Vidu gera um vídeo fluido a partir de uma imagem de entrada e um prompt de texto.

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 imagem costuma levar de 1 a 5 minutos, por isso a API usa um modelo assíncrono. O fluxo tem duas etapas principais: criar uma tarefa e 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
Content-Type string (Obrigatório)O tipo de conteúdo da solicitação. Deve ser application/json.Content-Type string (Obrigatório)O tipo de conteúdo da solicitação. Deve ser application/json.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:
  • vidu/viduq2-pro-fast_img2video
input object (Obrigatório)A entrada básica, incluindo o prompt de texto e os recursos de mídia.

Propriedades

prompt string (Opcional)O prompt de texto que descreve os elementos e as características visuais desejados para o vídeo gerado.O comprimento máximo é de 5.000 caracteres (cada caractere chinês ou letra inglesa conta como um). O texto que exceder o limite será truncado.media array (Obrigatório)Uma lista de recursos de mídia que especifica a imagem usada na geração.Cada elemento do array é um objeto de mídia que contém os campos type e url.

Propriedades

type string (Obrigatório)O tipo do recurso de mídia. Deve ser definido como o valor fixo a seguir:
  • image: Uma URL de imagem.
Limite de recursos: forneça exatamente uma imagem.url string (Obrigatório)A URL do arquivo de imagem, que deve ser acessível publicamente.
  • Protocolos compatíveis: HTTP ou HTTPS.
  • Exemplo: https://example.com/image.jpg.
Restrições da imagem:
  • Formatos: JPG, JPEG, PNG, WEBP.
  • Proporção: de 1:4 a 4:1.
  • Tamanho do arquivo: até 50 MB.
parameters object (Opcional)Parâmetros de processamento de vídeo, como resolução e duração.

Propriedades

resolution string (Opcional)
A configuração de resolution afeta diretamente o custo. Antes de fazer a chamada, confira os preços dos modelos.
Especifica a faixa de resolução do vídeo gerado.O modelo dimensiona o vídeo para uma quantidade de pixels próxima à faixa selecionada, preservando a proporção da imagem de entrada.Os valores válidos são 720P e 1080P. O padrão é 720P.duration integer (Opcional)
A configuração de duration afeta diretamente o custo, cobrado por segundo. Quanto maior a duração, maior o custo. Antes da chamada, confira os preços dos modelos.
A duração do vídeo gerado, em segundos.Um número inteiro no intervalo [1, 10]. O padrão é 5.audio boolean (Opcional)watermark boolean (Opcional)Especifica se uma marca-d’água será adicionada. Ela fica no canto inferior direito do vídeo e contém o texto fixo "Generated by AI".
  • false: (Padrão) Nenhuma marca-d’água é adicionada.
  • true: Uma marca-d’água é adicionada.
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.
  • Imagem para vídeo
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/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "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
  • 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.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

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. 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 retornam o status 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
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

outputobjectInformaçõ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
  • 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.end_time stringO horário de conclusão da tarefa. Formato: YYYY-MM-DD HH:mm:ss.SSS.orig_prompt stringURL do vídeo. Retornada somente quando task_status é SUCCEEDED.O vídeo está no formato MP4 (codificação H.264). O link é válido 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 de saída, contabilizadas apenas para tarefas bem-sucedidas.

Propriedades

duration integerA duração total faturável do vídeo, em segundos.output_video_durationintegerA duração do vídeo de saída, em segundos.size stringA resolução do vídeo de saída.fps integerA taxa de quadros do vídeo de saída. É fixa em 24.SR stringA faixa de resolução do vídeo de saída.audio booleanIndica se a saída é um vídeo com áudio.video_count integerO número de vídeos de saída. É fixo em 1.
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": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Códigos de erro

Se uma chamada ao modelo falhar, consulte Mensagens de erro para solucionar o problema.