API de Vídeo Wan 3.0
Parâmetros, combinações de mídia, tarefas assíncronas, downloads e cobrança por segundo para wan3.0-video no APIMaster.
API de Vídeo Wan 3.0
wan3.0-video é o modelo Wan 3 padrão; é um modelo separado de wan3.0-video-prime. Ele suporta texto, imagens, vídeo, áudio, documentos e páginas web públicas. Cada tarefa bem-sucedida produz um vídeo MP4/H.264, com até 30 segundos. Integração revisada: 2026-11-17.
Cada solicitação aceita no máximo 20 itens de mídia no total. O vídeo gerado usa 30 fps.
Endpoints e autenticação
| Operação | Endpoint |
|---|---|
| Criar | POST https://apimaster.ai/v1/videos |
| Consultar | GET https://apimaster.ai/v1/videos/{task_id} |
| Baixar | GET https://apimaster.ai/v1/videos/{task_id}/content |
Authorization: Bearer YOUR_API_KEY · Content-Type: application/json
Todos os parâmetros da requisição
Use um formato de mídia por solicitação. Use metadata.input.media para combinar mídias de referência ou incluir documentos.
| Parâmetro | Tipo | Obrigatório / padrão | Significado e valores válidos |
|---|---|---|---|
model |
string | Obrigatório | Exatamente wan3.0-video; não substitua por Prime |
prompt |
string | Obrigatório | Descreva o resultado em chinês ou inglês; limite oficial de 20.000 caracteres, textos nativos mais longos são truncados. Refira-se a Image 1, Video 1, Audio 1 na ordem da mídia; cada tipo de mídia tem sua própria numeração |
duration |
integer | 5 |
2–30 segundos de saída; -1 permite que o modelo selecione a duração. Com vídeo de referência, a duração de entrada somada à de saída não pode exceder 30 segundos |
seconds |
string | Opcional | Alias de duração, p. ex. "5" ou "-1"; deve corresponder a duration quando ambos forem fornecidos |
resolution |
string | 1080P |
480P, 720P, 1080P; valores de nível superior em minúsculas são normalizados |
aspect_ratio |
string | adaptive |
adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
ratio |
string | Opcional | Alias de aspect_ratio; recomenda-se adaptive para extensão de vídeo |
size |
string | Opcional | Alias de compatibilidade: nível de resolução, ou um mapeamento de pixels suportado como 1280x720; prefira resolução e proporção explícitas, e não tamanhos de pixel arbitrários |
generate_audio |
boolean | true no upstream |
Define se a saída tem uma faixa de áudio. false explícito é preservado. O áudio não altera a tarifa por segundo |
audio |
boolean | Opcional | Alias de generate_audio; use apenas um interruptor de áudio |
prompt_extend |
boolean | true |
Reescrita inteligente do prompt; false explícito é preservado. Deve ser true para entrada de documento/página |
watermark |
boolean | false no upstream |
Adiciona uma marca d'água à saída; false explícito é preservado |
seed |
integer | Aleatório | -1 ou 0–2147483647. A omissão ou -1 solicita uma semente aleatória; 0 é encaminhado. Sementes repetidas não garantem saída idêntica |
input_reference |
string | Opcional | URL da imagem do primeiro quadro; substitui o array de mídia nativo. Não misture estilos de entrada |
images |
string[] | Opcional | Array de conveniência anexado como itens reference_image quando input_reference está ausente |
metadata |
object | Opcional | Contêiner para os objetos nativos abaixo; não pode alterar o modelo selecionado |
metadata.input |
object | Opcional | Objeto de entrada nativo |
metadata.input.prompt |
string | Opcional | Substituição do prompt nativo; mantenha o prompt obrigatório de nível superior |
metadata.input.media |
object[] | Opcional | Array de mídia ordenado. Cada item exige type e url; veja os limites abaixo |
metadata.input.media[].type |
string | Obrigatório por item | first_frame, last_frame, reference_image, reference_video, reference_audio, file, link |
metadata.input.media[].url |
string | Obrigatório por item | URL pública HTTP(S) da mídia; tipos de imagem também aceitam uma string data:{MIME_type};base64,.... Mídia que não seja imagem exige uma URL pública |
metadata.parameters |
object | Opcional | Objeto de parâmetros nativo; não pode ser null |
metadata.parameters.resolution |
string | 1080P |
480P, 720P, 1080P em maiúsculas |
metadata.parameters.ratio |
string | adaptive |
Os mesmos valores de proporção listados acima |
metadata.parameters.duration |
integer | 5 |
2–30, ou -1; mesma restrição de duração combinada |
metadata.parameters.audio |
boolean | true no upstream |
Mesmo interruptor de áudio de saída |
metadata.parameters.prompt_extend |
boolean | true |
Mesmo interruptor de reescrita de prompt; file/link exige true |
metadata.parameters.watermark |
boolean | false no upstream |
Mesmo interruptor de marca d'água |
metadata.parameters.seed |
integer | Aleatório | Mesmo intervalo de semente, incluindo 0 explícito |
Os campos nativos negative_prompt, img_url, first_frame_url, last_frame_url e audio_url não são controles de mídia do Wan 3. Use o array de mídia documentado.
Limites de mídia e combinações válidas
| Tipo de mídia | Contagem e restrições |
|---|---|
first_frame, last_frame |
No máximo um de cada. O último quadro exige o primeiro quadro. Os controles de quadro não podem ser combinados com nenhum tipo de referência, arquivo ou link |
reference_image |
No máximo 10. JPEG/JPG, PNG sem transparência, BMP ou WEBP; cada lado 240–8,000 pixels, proporção de aspecto no máximo 8:1, cada arquivo no máximo 20 MB |
reference_video |
No máximo 5 clipes MP4/MOV; cada um com 1–15 segundos, entrada combinada no máximo 15 segundos; pelo menos 16 fps; cada lado 240–4,096 pixels, proporção de aspecto no máximo 8:1, cada arquivo no máximo 100 MB |
reference_audio |
No máximo 5 clipes WAV/MP3; cada um com 1–15 segundos, combinados no máximo 15 segundos; cada arquivo no máximo 15 MB |
file |
No máximo um arquivo DOCX/DOC/XLSX/XLS/PPTX/PPT/PDF/TXT/KEY/PAGES/NUMBERS/MD; no máximo 100 MB. Documentos paginados PDF, DOCX, DOC, PPTX, PPT e KEY/PAGES têm limite de 50 páginas |
link |
No máximo uma página acessível publicamente sem login; não combine com file |
Imagens, vídeos e áudios de referência podem ser combinados. Um arquivo ou link pode acompanhar mídia de referência. O modo de primeiro/último quadro aceita apenas controles de quadro; use o modo de imagem de referência mais áudio de referência para geração orientada por áudio. A análise de mídia e a moderação de conteúdo permanecem sujeitas a verificações upstream.
Texto para vídeo usa um prompt sem mídia. A animação de primeiro quadro usa first_frame; as transições usam first_frame mais last_frame. A geração por referência usa os tipos de referência. Para edição ou extensão, forneça reference_video e descreva a edição ou a extensão no prompt; use adaptive para extensão.
Exemplos
Texto para vídeo
curl "https://apimaster.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"wan3.0-video","prompt":"A paper boat drifting on a quiet pond, static camera.","duration":2,"resolution":"480P","aspect_ratio":"16:9","generate_audio":false,"prompt_extend":false,"watermark":false,"seed":0}'
Primeiro e último quadros
{"model":"wan3.0-video","prompt":"Move smoothly from the first frame to the last.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}
Imagem e áudio de referência
{"model":"wan3.0-video","prompt":"Animate Image 1 to the rhythm of Audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}
Edição / extensão de vídeo e duração inteligente
{"model":"wan3.0-video","prompt":"Extend Video 1 forward as the camera follows the paper boat.","duration":-1,"resolution":"480P","aspect_ratio":"adaptive","metadata":{"input":{"media":[{"type":"reference_video","url":"https://example.com/input.mp4"}]}}}
Documento / página web
{"model":"wan3.0-video","prompt":"Create a product introduction based on this document.","duration":10,"resolution":"720P","prompt_extend":true,"metadata":{"input":{"media":[{"type":"file","url":"https://example.com/product.pdf"}]}}}
Substitua todos os URLs de exemplo por mídia pública real. Para entrada via web, substitua o item de arquivo por {"type":"link","url":"https://example.com/product"}. O exemplo de primeiro quadro também funciona sem seu item de último quadro.
Respostas, polling, downloads e logs
A criação retorna um ID de tarefa do APIMaster, não o ID upstream:
{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video","status":"queued"}
| Campo de resposta | Significado |
|---|---|
id / task_id |
Identificador de tarefa da plataforma usado para consulta e download |
status |
queued, in_progress, completed, failed |
progress |
Indicador de progresso; aguarde o status final |
error.code, error.message |
Informações de falha quando aplicável |
metadata.url |
Local do conteúdo quando retornado na conclusão |
Faça polling aproximadamente a cada 15 segundos usando a mesma chave de API. Não crie outra tarefa para verificar o progresso. Os IDs de tarefa e as URLs de saída do provedor nativo expiram após 24 horas; baixe e retenha os resultados bem-sucedidos prontamente. O endpoint de conteúdo autenticado do APIMaster é preferível a armazenar URLs upstream temporárias.
curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
-H "Authorization: Bearer YOUR_API_KEY" -o wan3.mp4
O log de uso contém a tarefa e o resultado de vídeo bem-sucedido. Verifique a cobrança final após a conclusão; a aceitação não é prova de sucesso da geração. O polling repetido não cria outra taxa de geração.
Cobrança
Consulte as tarifas por segundo no cartão do modelo.
A APIMaster soma a duração de todos os vídeos de entrada à duração do vídeo de saída, arredonda o total para cima uma única vez ao segundo inteiro e aplica a tarifa por segundo da resolução de saída selecionada. Uma entrada de 2,3 s e uma saída de 5 s são cobradas como 8 s. Sem vídeo de entrada, só a duração de saída é cobrada. A solicitação dispensa cotação e informação sobre a duração de entrada. Se a geração falhar, o valor reservado é liberado. O valor final está no registro de uso.
Erros e correções
| Sintoma | Correção |
|---|---|
| Duração/resolução/proporção inválida | Use o enum e os intervalos acima; a duração inteligente é exatamente -1 |
| Conflito de quadro/referência, último quadro sem o primeiro | Siga as regras de combinação |
| Arquivo/link com reescrita desativada | Defina prompt_extend:true |
| Falha na obtenção/formato/duração da mídia | Use arquivos públicos que atendam a todas as restrições de tamanho, formato e duração |
| Prompt ausente | Mantenha um prompt de nível superior não vazio para a API do APIMaster |
| Tarefa falhou ou foi moderada | Inspecione error, depois corrija a solicitação; não considere a aceitação como sucesso |
