Tutorial de integração da API Wan 3.0: curl, Python e todos os parâmetros

O Wan 3.0 Standard (wan3.0-video) usa a interface assíncrona unificada do HiAPI: envie com POST /v1/tasks, receba o taskId e depois obtenha o resultado com GET /v1/tasks/{taskId}. Basta uma frase de prompt para gerar um vídeo com som; também é possível adicionar primeiro frame, último frame, ou até 10 imagens de referência, 5 vídeos de referência e 5 áudios de referência para controlar a geração em conjunto. Este artigo traz exemplos de curl e Python prontos para executar, todos os parâmetros atuais e alguns pontos de atenção antes de ir para produção.

Primeiro, os preços

Resolução	Por segundo	5 segundos
480P	$0.04	$0.20
720P	$0.08	$0.40
1080P (padrão)	$0.16	$0.80

Preço atual do HiAPI, verificado em 18 de outubro de 2026. O som vem ativado por padrão, sem cobrança extra.

Atenção aos padrões: sem resolution, o padrão é 1080P; sem duration, o padrão é 5 segundos, totalizando $0.80. Ao testar prompts, lembre-se de escrever explicitamente "resolution": "480P".

Para gerar mais rápido, use a versão acelerada wan3.0-video-prime; o preço é mais que o dobro da versão standard (480P a $0.0875 por segundo).

Um vídeo real gerado

480P, 16:9, 5 segundos, com som:

A steaming noodle stall at a night market, close on the cook's hands as she lifts a tangle of noodles from a boiling pot and swirls them into a blue-rimmed bowl; slow push-in, warm tungsten light against cool blue street glow, steam drifting through the frame. Sound: rolling boil, the clink of a ladle, crowd murmur and a scooter passing in the distance.

Gerar com este prompt →

wan3.0-video, 480P, 5 segundos, $0.20.

Executando o primeiro

Preparação: crie uma API Key no console. Novos usuários ganham 200 créditos ao se registrar.

curl: enviar tarefa

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Retorna o taskId imediatamente; a geração ocorre em segundo plano:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: consultar resultado

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Depois que data.status se torna success, data.output[0].url é o endereço do vídeo. O endereço temporário expira em cerca de 7 dias; baixe e armazene o quanto antes. fail indica falha, sem cobrança.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "wan3.0-video",
    "input": {
        "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
        "resolution": "480P",
        "duration": 5,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(10)

print(d["output"][0]["url"] if d["status"] == "success" else d)

Vídeos curtos geralmente ficam prontos em alguns minutos; um intervalo de polling de 10 segundos é suficiente.

Todos os parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Texto	Descreva cena, ação, câmera, iluminação e som aqui; no modo de referência, use Image1, Video1, Audio1 para se referir aos materiais
resolution	Não	480P / 720P / 1080P (padrão)	Define o preço por segundo
duration	Não	Inteiro 2–30, padrão 5	A duração total dos vídeos de referência somada à duração de saída não pode exceder 30 segundos
aspect_ratio	Não	adaptive (padrão) / 16:9 / 4:3 / 1:1 / 3:4 / 9:16	adaptive escolhe automaticamente conforme materiais e prompt
audio	Não	Booleano, padrão true	Se inclui trilha de áudio sincronizada
seed	Não	0–2147483647	Fixo para facilitar a reprodução
first_frame_url	Não	1 URL de imagem	Modo primeiro frame
last_frame_url	Não	1 URL de imagem	Usado junto com o primeiro frame para especificar o último frame
reference_image_urls	Não	Até 10	Imagens de referência
reference_video_urls	Não	Até 5, cada um de 1–15 segundos, total ≤15 segundos	Vídeos de referência
reference_audio_urls	Não	Até 5 WAV/MP3	Deve ser usado junto com imagens ou vídeos
reference_file_urls	Não	Até 1	Documento ou apresentação
reference_link_urls	Não	Até 1	Página da web sem necessidade de login

Os dois modos não podem ser misturados: o modo primeiro/último frame e o modo de referência reference_* são mutuamente exclusivos; escolha apenas um por requisição.

Exemplo de uso do modo de referência:

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "Use Image1 as the product: slow quarter orbit around it on a wooden counter, soft morning window light. Sound: gentle pouring water.",
    "reference_image_urls": ["https://example.com/product.jpg"],
    "resolution": "480P",
    "duration": 5
  }
}

Erros comuns

Todos são retornados de forma síncrona no envio com HTTP 400, sem criar tarefa nem cobrar:

• duration: maximum: got 99, want 30: duração excede 30 segundos.
• resolution: value must be one of '480P', '720P', '1080P': a resolução deve ter P maiúsculo.
• additional properties 'negative_prompt', 'image_urls' not allowed: este modelo não tem prompt negativo; o campo de imagem de referência se chama reference_image_urls, não image_urls.
• API Key incorreta retorna HTTP 401; saldo insuficiente retorna 402.

Falhas após a criação da tarefa aparecem na consulta de resultado como status: "fail", e o código HTTP continua sendo 200, então verifique data.status.

Atenção antes de ir para produção

• Use callback em vez de polling: adicione no nível superior do corpo da requisição "callback": {"url": "https://seu-dominio/hiapi/callback", "when": "final"}; ao terminar a tarefa, o HiAPI notifica você ativamente. O callback fica no nível superior, não dentro de input.
• Evite cobrança duplicada: inclua o cabeçalho Idempotency-Key no envio. Em retentativas por timeout de rede, use a mesma key; será retornado o taskId original, sem criar outra tarefa.
• Armazene a tempo: o endereço temporário expira em cerca de 7 dias. Para armazenamento de longo prazo, envie "storage": "persistent" na criação ou converta depois para armazenamento persistente; consulte a documentação de criação de tarefas.

Perguntas frequentes

Dá para usar sem imagens de referência?

Sim. Basta escrever o prompt para gerar o vídeo; materiais de referência são opcionais.

O som custa a mais?

Não. audio vem ativado por padrão; o preço depende apenas da resolução e dos segundos. Para não ter som, envie false.

Quero vídeo vertical?

Envie aspect_ratio como 9:16.

Dá para usar primeiro frame e imagem de referência juntos?

Não, escolha um dos dois.

Para mais formas de escrever prompts, consulte o Guia completo de prompts do Wan 3.0, com vídeos reais para os 4 cenários. Você também pode copiar diretamente o prompt da barraca de macarrão acima e gerar um por $0.20.