API Wan 3.0 Video Prime

Use wan3.0-video-prime através da API de vídeo assíncrona do APIMaster. A integração atual oferece 480P / 720P / 1080P, 2–30 segundos inteiros e um vídeo por tarefa. Revisão de parâmetros e integração: 2026-10-26.

Endpoints e autenticação

Operação	Método e URL
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

Use Authorization: Bearer YOUR_API_KEY em todas as requisições e Content-Type: application/json ao criar uma tarefa. Use uma chave de API do APIMaster, não uma chave do Alibaba Cloud. O APIMaster fornece o cabeçalho assíncrono upstream; você não precisa de X-DashScope-Async.

O endpoint de criação compatível /videos/generations retorna um envelope de resposta diferente; os exemplos abaixo usam consistentemente /videos.

Capacidades atuais das rotas

Duas integrações atualmente atendem este modelo: a rota nativa do Alibaba Cloud e a rota GMI. Campos avançados exigem a rota correspondente; enviar um campo não seleciona essa rota. Confirme qual rota sua chave de API pode acessar antes de usar exemplos específicos de rota.

Capacidade	Nativa do Alibaba Cloud	GMI
Texto para vídeo, primeiro quadro, primeiro/último quadros, imagens de referência	Integrado	Integrado, com campos de mídia diferentes
Áudio de referência	metadata.input.media	audio_url
Documento / página web pública	Campos de mídia nativos são encaminhados; não cobertos pela verificação de geração concluída	Não suportado
Vídeo de referência, edição, extensão	Bloqueado antes do envio	Não suportado
Duração automática -1	Bloqueado	Bloqueado
Proporção de aspecto 21:9	Aceito	Rejeitado
Chave explícita de áudio	generate_audio / audio	Não suportado; omita estes campos
Desativar reescrita de prompt / seed fixo 0	A serialização atual não preserva prompt_extend: false nem seed: 0; não dependa deles	false e 0 explícitos são preservados

Um vídeo silencioso de 5 segundos em 720P pela rota nativa foi concluído, baixado e decodificado com sucesso na verificação de aceitação de 2026-10-24. Outras combinações de mídia são descritas a partir do adaptador e do contrato oficial, em vez de serem apresentadas como combinações testadas em geração. A disponibilidade e os preços das rotas podem mudar; consulte o cartão do modelo.

Parâmetros comuns completos da requisição

Envie estes campos no nível superior. Para a maior compatibilidade, use duration, resolution e aspect_ratio explícitos, um prompt não vazio de no máximo 5.000 caracteres e omita opções específicas de rota.

Campo	Tipo	Obrigatório / padrão	Comportamento do APIMaster
model	string	Obrigatório	Exatamente wan3.0-video-prime
prompt	string	Obrigatório em ambas as rotas	Não vazio, inclusive na geração por imagem. O GMI valida 1–5.000 caracteres; o adaptador nativo exige texto não vazio. O limite oficial nativo é 20.000; evite depender desse limite maior entre rotas
duration	integer	5	2–30 segundos; sem -1, frações ou duração automática
seconds	string	Opcional	Alias em string, ex.: "5"; deve concordar com duration quando ambos forem fornecidos
resolution	string	720P	480P, 720P, 1080P; valores minúsculos no nível superior são normalizados. Este padrão do APIMaster difere do padrão nativo oficial
aspect_ratio	string	16:9	Valores comuns: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4. 21:9 apenas na rota nativa
ratio	string	Opcional	Alias de aspect_ratio; use um campo e não envie valores conflitantes
size	string	Opcional	Alias de dimensão como 1280x720; aplica-se validação específica de rota. Prefira resolution e aspect_ratio. O GMI exige que o lado menor corresponda ao nível de resolução; o nativo aceita apenas seus mapeamentos de dimensão suportados
input_reference	string	Opcional	URL da imagem do primeiro quadro. Use uma URL HTTP(S) publicamente baixável para compatibilidade entre rotas; não combine com outras entradas de primeiro quadro
prompt_extend	boolean	Nativo true; GMI deixa o padrão do provedor quando omitido	Reescrita de prompt. O nativo atualmente não consegue desativá-la de forma confiável com false; o GMI encaminha um booleano explícito
watermark	boolean	Padrão nativo oficial false; GMI deixa o padrão do provedor quando omitido	Chave de marca d'água
seed	integer	Aleatório quando omitido	Faixa fixa portátil: 1–2147483647. O nativo também aceita -1 para aleatório; 0 nativo é omitido durante a serialização. O GMI aceita 0–2147483647 e rejeita -1. Um seed fixo não garante saída idêntica

Os aliases de dimensão nativos são 832x480, 480x832, 1280x720, 720x1280, 1920x1080 e 1080x1920 para os casos usuais de paisagem/retrato. Alguns mapeamentos de dimensão quadrada reduzem para 1:1; outras dimensões mapeadas ainda podem falhar na validação de proporção de aspecto. Não use size para solicitar dimensões arbitrárias.

Tabelas de parâmetros específicos de rota

Campos GMI

Estes são campos de nível superior além da tabela comum. O adaptador GMI rejeita campos não reconhecidos, incluindo metadata, images, image_urls, audio, generate_audio, video_urls e reference_video.

Campo	Tipo	Obrigatório / padrão	Comportamento
negative_prompt	string	Opcional	No máximo 500 caracteres
first_frame	string	Opcional	URL de imagem HTTP(S) pública; alternativa a input_reference
last_frame	string	Opcional	URL de imagem HTTP(S) pública do quadro final; forneça também um primeiro quadro
reference_image	string ou string[]	Opcional	1–10 URLs HTTP(S) públicas de imagem de referência; use um array para múltiplas imagens
audio_url	string	Opcional	URL HTTP(S) pública de áudio de referência; sujeita à validação de mídia do provedor

Use controles de quadro ou imagens de referência em uma única requisição. metadata.input.media nativo não é traduzido para estes campos no GMI.

Campos nativos do Alibaba Cloud

Entradas estruturadas nativas pertencem dentro de metadata. Enviar objetos oficiais input ou parameters diretamente no nível superior não é o contrato do APIMaster. Sempre mantenha o prompt obrigatório no nível superior.

Campo	Tipo	Obrigatório / padrão	Comportamento
generate_audio	boolean	Padrão nativo oficial true	Se a saída contém uma faixa de áudio; false é preservado
audio	boolean	Opcional	Alias de generate_audio; forneça apenas um
images	string[]	Opcional	Convertido em entradas de mídia reference_image; não são quadros primeiro/último ordenados. Não combine com input_reference
metadata	object	Opcional	Envolve input e parameters nativos; não pode alterar model
metadata.input	object	Opcional	Contêiner de entrada nativo
metadata.input.prompt	string	Opcional	Substituição de prompt nativo; prefira apenas o prompt de nível superior
metadata.input.media	object[]	Opcional	Coleção de mídia nativa, com type e url em cada item
metadata.input.media[].type	string	Obrigatório por item	first_frame, last_frame, reference_image, reference_audio, file, link; reference_video é atualmente rejeitado
metadata.input.media[].url	string	Obrigatório por item	Localização da mídia; URLs HTTP(S) públicas são recomendadas. URLs temporárias oficiais do OSS exigem um contexto de upload upstream válido separadamente; o APIMaster não fornece esse contexto de upload
metadata.parameters	object	Opcional	Contêiner de parâmetros nativo; não pode ser null
metadata.parameters.resolution	string	720P	Maiúsculas 480P, 720P, 1080P
metadata.parameters.ratio	string	16:9	Proporções de aspecto nativas incluindo adaptive e 21:9
metadata.parameters.duration	integer	5	2–30; sem -1
metadata.parameters.audio	boolean	Padrão nativo oficial true	Chave de áudio da saída
metadata.parameters.prompt_extend	boolean	true	Deve permanecer true para file / link; false explícito tem a limitação de serialização acima
metadata.parameters.watermark	boolean	Padrão nativo oficial false	Chave de marca d'água
metadata.parameters.seed	integer	Aleatório	-1 ou 0–2147483647; 0 tem a limitação de serialização acima

Opções nativas de nível superior substituem seus parâmetros de metadata correspondentes. input_reference de nível superior substitui o array de mídia nativo; images acrescenta entradas de imagem de referência quando input_reference está ausente. Use um estilo de entrada e um estilo de parâmetro para evitar substituições acidentais. Não use img_url, first_frame_url, last_frame_url ou audio_url legados dentro de input nativo; o adaptador rejeita esses campos de mídia legados para Wan 3.0.

Restrições de mídia

As regras de mídia nativas oficiais abaixo também explicam a validação do lado do provedor; um adaptador aceitar uma URL não prova que a mídia é válida.

Mídia	Limites / notas de integração
Primeiro / último quadros	No máximo um de cada; um último quadro exige um primeiro quadro. Não misture controles de quadro com reference_image
Imagens de referência	No máximo 10; JPEG/JPG, PNG sem transparência, BMP ou WEBP; cada lado 240–8.000 px, proporção de aspecto no máximo 8:1, no máximo 20 MB por imagem
Áudio de referência	Nativo: no máximo 5, WAV/MP3, cada um 1–15 segundos, combinados no máximo 15 segundos, no máximo 15 MB por arquivo. O GMI expõe um audio_url
Arquivo / página web	Apenas nativo: no máximo um arquivo ou uma página publicamente legível; não combine file e link. Formatos de arquivo oficiais: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS, MD; no máximo 100 MB, com limite de 50 páginas para formatos paginados aplicáveis. Mantenha prompt_extend: true
Vídeo de referência	Oficialmente disponível, mas atualmente bloqueado pela validação de cobrança nativa do APIMaster; não exposto no GMI. Não use exemplos de edição ou extensão de vídeo da API oficial aqui

O teto oficial nativo de mídia combinada é de 20 itens; limites individuais e de combinação ainda se aplicam. URLs de dados Base64 de imagem fazem parte do formato de entrada nativo oficial, mas não são aceitas pela validação de URL do GMI. Prefira URLs HTTP(S) baixáveis entre rotas.

Exemplos

Texto para vídeo, campos comuns

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

Primeiro quadro, campos comuns

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

Primeiro / último quadros GMI

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

Primeiro / último quadros nativos e saída silenciosa

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"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 nativos

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood 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"}]}}}

Substitua as URLs de mídia de exemplo por arquivos públicos reais. Exemplos específicos de rota exigem a rota correspondente e permanecem sujeitos a verificações de combinação upstream.

Resposta, polling e download

A criação retorna um ID de tarefa do APIMaster, por exemplo:

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

Campo	Significado
id / task_id	Identificador de tarefa do APIMaster, não um identificador de tarefa upstream
status	queued, in_progress, completed, failed
progress	Progresso reportado; não é garantia de conclusão
error.code / error.message	Detalhes da falha quando aplicável
metadata.url	Endereço de conteúdo autenticado quando retornado na conclusão

Faça polling a cada 10–20 segundos com a mesma chave de API até um status terminal; sucesso na criação significa apenas aceitação. A geração pode levar vários minutos. Faça polling de uma tarefa aceita em vez de criar repetidamente tarefas pagas.

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 wan-prime.mp4

Baixe e salve o vídeo concluído prontamente; URLs de resultado upstream podem expirar. O polling repetido não cria outra cobrança de geração.

Cobrança e erros comuns

A cobrança é por segundo na resolução solicitada, com preços de rota/conta mostrados no cartão do modelo. O envio reserva a cobrança estimada. A conclusão nativa usa a duração faturável retornada e o preço congelado no envio; o GMI segue o contrato de duração reservada. Tarefas com falha liberam/reembolsam sua reserva de geração. Áudio desativado não implica uma faixa mais barata. Use o log de uso para o valor final.

Erro / sintoma	Ação
duration must be an integer from 2 to 30	Use um inteiro explícito; -1 não está integrado
unsupported Wan request field ...	Remova um campo não suportado pelo GMI ou confirme o acesso à rota nativa correspondente
unsupported aspect ratio	Use uma proporção comum; 21:9 exige roteamento nativo
reference video requires an input-duration quote	Remova o vídeo de referência; esta capacidade está atualmente bloqueada
prompt is required / falha ao buscar mídia	Adicione texto no nível superior; use mídia válida e publicamente baixável
prompt_extend: false ou seed: 0 não tem efeito no nativo	Limitação de serialização atual; use um seed positivo e não dependa de desativar a reescrita

Fontes: informações oficiais do modelo, referência oficial da API nativa e guia de uso oficial. Capacidade oficial não significa que o mesmo campo é exposto em todas as rotas do APIMaster.