Wan 3.0 API: texto para vídeo, imagem para vídeo ou referência para vídeo

Wan 3.0 é uma família de modelos com três entradas, e o jeito de começar decide o que você controla, o que você paga e, nesta API, como ela trata conteúdo sem censura. Se você envia palavras, uma imagem fixa ou um monte de referências depende de uma única pergunta.

Resumindo: pergunte o que não pode mudar no clipe:

• Nada ainda, você ainda está procurando a cena: texto para vídeo. Um único campo, prompt, basta.
• O primeiro quadro (e opcionalmente o último): imagem para vídeo. A imagem é usada exatamente como quadro um, então o prompt só precisa descrever o movimento.
• Um personagem, uma sala, uma voz ou um estilo de movimento que precise continuar: referência para vídeo. Até dez imagens, cinco clipes e cinco faixas de áudio, mais um documento ou uma página web opcional, cada um com um papel no prompt.

As três devolvem de 2 a 30 segundos com som no mesmo arquivo, em 480p, 720p ou 1080p na base e na Prime (os níveis Pro renderizam 1080p, 2K ou 4K, com 2K e 4K ampliados a partir de um render 1080p). Os outros modelos de vídeo estão no catálogo de API de vídeo sem censura.

As três tarefas lado a lado

Nas três tarefas a duração vai de 2 a 30 segundos, ou -1 deixa o modelo escolher a duração (30 s são reservados antes e a cobrança se ajusta na duração entregue).

Se você enviar um campo que a tarefa não lista, como um image_url em texto para vídeo, a chamada de criação retorna 400. Pegue o esquema na página do modelo em vez de copiar um endpoint irmão.

Quanto custa um clipe

O preço por segundo é o mesmo para entrada de texto, imagem e referência.

Referência para vídeo traz um detalhe: os segundos de qualquer vídeo de referência são cobrados além da saída, e os clipes de referência somados à saída precisam ficar dentro de 30 segundos. Imagens, áudio, documentos e páginas web de referência não são cobrados. Uma cotação ou reserva para uma tarefa com clipes de referência pressupõe o máximo de 15 segundos; você paga apenas pelos segundos realmente usados.

O antigo Wan 2.6 é a alternativa de duração fixa: texto para vídeo e imagem para vídeo devolvem exatamente 5, 10 ou 15 segundos em 720p ($0,09 por segundo) ou 1080p ($0,135). A tarefa de referência para vídeo dele é outro contrato: aceita até três clipes de referência e nenhuma imagem, e carrega o rótulo Filtered content em vez de Unrestricted.

Texto para vídeo: escreva o plano, não o clima

Use quando a cena ainda está aberta, não existe imagem aprovada ou você quer um take longo com o próprio som. Nada ancora o quadro inicial, então coloque no prompt tudo o que o espectador deve ver: sujeito, uma ação, um movimento de câmera e depois luz e som. Uma ação clara vale mais que uma lista longa de adjetivos. Procure em outro lugar quando a composição de abertura tiver de casar com uma imagem aprovada: isso é imagem para vídeo.

{
  "model": "alibaba/wan-3.0/text-to-video",
  "input": {
    "prompt": "A ceramic bottle stands on a brushed-steel counter. One bead of condensation rolls down the glass while the camera pushes in slowly. Cool side light, no cut. Sound: a faint fridge hum and the tick of the droplet landing.",
    "duration_seconds": 10,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "generate_audio": true
  }
}

Essa requisição custa 10 x $0,09 = $0,90 na Wan 3.0 base. Três hábitos ajudam:

• Fixe o visual aos 5 segundos antes de pedir 30. Clipes longos derivam mais, então uma ideia ruim sai mais barata de encontrar curta.
• Para takes longos, divida o prompt em batidas com tempo. Um exemplo da comunidade escreveu uma batida de dois segundos por ação (massa, molho, recheios, forno) mais uma linha de continuidade para um clipe de 15 segundos.
• Deixe a expansão de prompt desligada quando o briefing estiver preciso. Ela ajuda prompts rasos e briga com os detalhados; vem ligada por padrão em texto para vídeo do Wan 3.0 Pro.

Imagem para vídeo: o quadro é o teto

Use quando o quadro um não é negociável: um packshot de produto com enquadramento fixo, um quadro de personagem aprovado, um keyframe de um clipe anterior. A imagem define figurino, cenário e luz, então o prompt carrega só o movimento. Procure em outro lugar quando a cena ainda estiver aberta (texto para vídeo) ou quando um personagem tiver de aparecer em vários planos (referência para vídeo). Deixe aspect_ratio de fora e o clipe herda o formato da imagem; um valor conflitante corta a imagem.

last_image_url faz o clipe terminar exatamente em uma segunda imagem. Passar o mesmo arquivo como primeiro e último quadro dá um loop sem emenda, como neste exemplo de frasco de produto: um quarto de volta para o brilho cruzar o vidro e depois de volta ao início.

Mesma imagem que image_url e last_image_url, som desligado; 5 s em 1080p custam $0,90.

{
  "model": "alibaba/wan-3.0/image-to-video",
  "input": {
    "image_url": "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png",
    "last_image_url": "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png",
    "prompt": "The bottle rotates a quarter turn so the highlight travels across the glass, then returns to its starting angle. Locked camera, single soft key from the left, no music.",
    "duration_seconds": 5,
    "resolution": "1080p",
    "generate_audio": false,
    "seed": 20260907
  }
}

Descreva o quadro que você forneceu e depois o movimento; nunca outra sala. Quando um prompt descreve uma cena diferente da imagem fixa, o Wan 3.0 pode abrir na imagem fixa e depois cortar para a cena nova. last_image_url sozinho é rejeitado; ele precisa de image_url.

Referência para vídeo: dê um papel a cada referência

Use quando alguma coisa precisa se repetir: o mesmo personagem em vários planos, uma sala específica, uma voz, um movimento ou um estilo de câmera. O Wan 3.0 lê as referências na ordem em que você as envia, e o prompt diz qual é qual; caso contrário, o modelo tira uma média delas e cria um sujeito que não corresponde a nenhum. Procure em outro lugar quando uma única imagem aprovada já diz tudo: referências extras competem e não dão mais controle automaticamente. O exemplo abaixo mantém um personagem da primeira imagem e uma sala da segunda.

Ilustração decorativa, não é uma saída do modelo nem um diagrama do exemplo seguinte.

{
  "model": "alibaba/wan-3.0/reference-to-video",
  "input": {
    "reference_image_urls": [
      "https://cdn.spicyapi.ai/models/examples/inputs/a4d8d93ce949c527.png",
      "https://cdn.spicyapi.ai/models/examples/inputs/27753da99f960815.png"
    ],
    "prompt": "The first image is the character: keep her face, hair and the black slip dress exactly. The second image is the room. She crosses from the doorway to the window and leans against the frame, looking out. Slow lateral track, one practical lamp, night ambience.",
    "duration_seconds": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "seed": 771120
  }
}

Duas imagens de referência, nenhum vídeo de referência: o clipe de 8 s custa 8 x $0,09 = $0,72.

O que você pode passar para ela:

• Imagens (até 10) para identidade, figurino e placas de cenário. A foto de uma pessoa real costuma ser recusada pela checagem de rostos ("The input content is suspected to include real human faces"). Use personagens ilustrados, renderizados em 3D ou gerados. Tarefas recusadas não são cobradas.
• Vídeo (até 5 clipes, de 1 a 15 s cada, 15 s no total) para movimento e estilo de câmera mais do que para um rosto. Confira a duração dos clipes antes de enviar; os limites são aplicados durante a geração, não na aceitação.
• Áudio (até 5 clipes, 15 s no total) para uma voz ou o tom da sala.
• Um documento ou uma página web pública (não os dois) que o modelo lê para personagens, figurino, ambientação e ação: um arquivo PDF, DOCX, TXT ou Markdown de até 100 MB e 50 páginas, ou uma página que abre sem login. Anexar qualquer um dos dois liga o thinking (indisponível nos níveis Pro) e a expansão de prompt, a menos que você os defina. Um tutorial de criadores mostra a ideia; uma leitura de página falha não é cobrada.

Se o quadro um tiver de ser exato, use imagem para vídeo. A referência para vídeo pode ser instruída a começar a partir de uma imagem (veja o guia de prompt do Wan 3.0 da Alibaba), mas só imagem para vídeo garante isso.

O que muda para o trabalho sem censura

Sem censura não é um único interruptor no Wan; a tarefa que você escolhe muda o resultado. Com base nos nossos testes de setembro de 2026 (grade completa no teste do Wan sem censura):

• O Wan 3.0 base entregou todos os níveis de intensidade no teste, do leve ao forte, com entrada de texto, imagem e referência, mas também vai além do que você pede: um prompt com tema de contenção voltava com frequência como outra cena com dois adultos, às vezes com uma segunda pessoa acrescentada.
• Imagem para vídeo do Wan 3.0 Prime suavizou uma cena com dois adultos, enquanto Prime com texto e referência entregou a cena. Se o seu trabalho parte de uma imagem fixa, experimente antes o Wan 3.0 base.
• Wan 3.0 Spicy e Prime Spicy existem só como imagem para vídeo (a partir de $0,057 por segundo em 480p). Eles pendem para o adulto sem ninguém pedir e muitas vezes trocam ou tiram a roupa. Se o traje precisa ficar, use o Wan 3.0 base.
• Referência para vídeo do Wan 2.6 recusou nosso material de referência.

O comportamento muda de endpoint para endpoint, então rode seu próprio prompt no que você escolher. Para continuar uma história além de 30 segundos, veja encadear clipes.

Teste primeiro no Playground

Cada tarefa tem sua própria página com uma aba Playground (fique na visão Form; entre com uma conta com saldo para executar). Rode ali um clipe curto e barato antes de escrever qualquer código.

1. Abra a página da sua tarefa: texto para vídeo, imagem para vídeo ou referência para vídeo.
2. Preencha as entradas que a tarefa pedir. Texto para vídeo: Prompt. Imagem para vídeo: Input image, mais Closing frame se o clipe precisar terminar em uma segunda imagem; Prompt é opcional. Referência para vídeo: Reference images, Reference videos e Reference audio (ao menos uma das entradas de referência); no prompt, diga o que cada uma controla.
3. Coloque Resolution em 480p e Duration em 5. Os dois são marcados como interferindo no preço, e a estimativa na página se atualiza quando você os muda.
4. Deixe Generate audio ligado, a menos que você mesmo avalie o clipe, e deixe Prompt expansion desligado assim que o prompt estiver preciso. Defina um Seed se quiser comparar duas mudanças.
5. Aperte Run model, veja o clipe em Output e depois aumente resolução e duração quando o visual estiver certo.

A visão JSON ao lado de Form mostra o corpo da requisição, e as abas de código ao lado mostram a mesma chamada, então um clipe que funciona aqui pode ser copiado para o seu código.

Depois rode pelo código

Instale o SDK de Python (pip install spicyapi), defina SPICY_API_KEY no seu ambiente e execute isto. Usa o corpo de texto para vídeo acima; troque o ID do modelo e input pelo de qualquer uma das outras duas tarefas. Mostra o preço e espera o seu sim antes de criar a tarefa:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
MODEL = "alibaba/wan-3.0/text-to-video"
body = {
    "prompt": "A ceramic bottle stands on a brushed-steel counter. One bead of condensation "
              "rolls down the glass while the camera pushes in slowly. Cool side light, no cut. "
              "Sound: a faint fridge hum and the tick of the droplet landing.",
    "duration_seconds": 10,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "generate_audio": True,
}

quote = client.quote_task(model=MODEL, input_data=body)
print("Estimated", quote["estimatedCost"], "maximum", quote["maxCharge"])
if input("Create the task? [y/N] ").strip().lower() != "y":
    raise SystemExit

task = client.create_task(
    model=MODEL,
    input_data=body,
    idempotency_key=str(uuid.uuid4()),
    quote_id=quote["quoteId"],
    expected_cost=quote["estimatedCost"],
)
print("Task", task["taskId"], flush=True)  # save it: after a timeout, look this task up instead of creating another
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise SystemExit(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(
    not asset.get("url") or asset.get("pending") or asset.get("unavailable")
    for asset in assets
):
    raise RuntimeError(f"{task['taskId']} has no complete downloadable output; look up this task before retrying")
print(assets[0]["url"])  # copy the clip to your own storage now

Para entradas de imagem, clipe ou áudio, use um link HTTPS público ou um arquivo enviado (guia de mídia). Tudo além dessa chamada está no guia de tarefas e na referência do SDK de Python; um serviço pode usar webhooks. Os clipes ficam guardados cerca de 14 dias, então copie os que quiser (retenção e entrega).

Ou deixe um Agent rodar

Quando um assistente deve rodar os clipes, as três ferramentas oficiais mostram o preço e pedem confirmação antes de uma chamada paga.

• CLI. Coloque o mesmo objeto input no input.json e depois:

``bash spicyapi tasks create --model alibaba/wan-3.0/text-to-video --input-file input.json --wait ``

Para uma imagem local, spicyapi files upload still.png devolve o endereço spicy:// para image_url. Veja a doc da CLI; npx @spicyapi/cli funciona sem instalar.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e pergunte: "Make a 10-second 9:16 clip at 720p with Wan 3.0 text-to-video from this prompt." Ele chama spicyapi_task_create, que para para sua confirmação de preço, e depois spicyapi_task_wait. Para um arquivo no seu computador, usa spicyapi_upload_file.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que faz um assistente de código ler o esquema do modelo ao vivo em vez de adivinhar campos.

Quando o resultado está errado, mude uma coisa só

Ao comparar duas tentativas, mude um campo e mantenha seed, prompt, duração e resolução fixos. Tempo limite, saldo e outros erros gerais estão na referência de erros.

Por qual nível começar

Comece no Wan 3.0 base em 480p e aumente a resolução quando o visual estiver certo. A Prime é mais rápida por 36 por cento a mais por segundo em 480p, ou 40 por cento a mais em 720p e 1080p; para 1080p a 4K use a Pro. Para durações fixas de 5, 10 ou 15 segundos, use o Wan 2.6 com entrada de texto ou imagem.

FAQ

Imagem para vídeo é melhor que referência para vídeo para preservar um rosto?

Se o rosto está no quadro de abertura, imagem para vídeo: ela usa a imagem exatamente como quadro um. Referência para vídeo é para um rosto que precisa continuar entre planos, e suas referências guiam em vez de fixar.

Imagem para vídeo é melhor que texto para vídeo?

Nenhuma é melhor em geral. Imagem para vídeo ganha quando o quadro um tem de ser um visual aprovado específico; texto para vídeo ganha quando você ainda está explorando uma cena com palavras, e não precisa de arquivo de origem.

O tipo de tarefa muda o preço?

Não. O preço por segundo depende só do nível e da resolução; referência para vídeo soma os segundos cobrados de qualquer clipe de referência.

Em resumo: palavras para explorar uma cena, uma imagem fixa para fixar o quadro um, referências para tudo o que precisa se repetir entre planos.