API reference-to-video do Wan 2.6: personagens a partir de clipes

O reference-to-video do Wan 2.6 recebe de um a três clipes curtos das pessoas, animais ou objetos que você quer, além de um prompt que descreve uma cena nova. Os clipes decidem quem ou o que aparece; o prompt decide onde eles estão, o que fazem e como a câmera e a luz os tratam. O resultado tem de 2 a 10 segundos em 720p ou 1080p, em um de cinco formatos de tela, como uma única tomada ou várias tomadas cortadas. Custa $0,065 por segundo em 720p e $0,0975 em 1080p, e os segundos de material de referência enviados também são cobrados.

Use quando o material é o assunto e o cenário é novo: um apresentador filmado uma vez e colocado em vários lugares, ou um clipe de produto remontado para uma nova temporada. Use Wan 2.6 image-to-video quando uma imagem aprovada precisa definir o quadro de abertura, o cenário e as proporções. Ela também aceita até duas imagens estáticas, junto com os clipes ou no lugar deles; continua sem campo de referência de áudio, e é a única tarefa do Wan 2.6 no nível Filtered.

Teste primeiro no Playground

1. Abra a página de reference-to-video e fique na aba Playground, na visão Form. Entre com uma conta com saldo para executar.
2. Em Reference videos, adicione de um a três clipes aparados com Add a file, ou cole links com Asset URL. O primeiro clipe que você adiciona é character1 no prompt, o segundo é character2, o terceiro é character3.
3. Escreva o Prompt como mostrado na seção de cena abaixo: o que cada clipe contribui, depois cenário, ação, câmera e luz.
4. Coloque Resolution em 720p, Duration em 5, um valor curto, Aspect ratio no formato que você entrega e Shot structure em Single take no primeiro teste.
5. Defina um Seed e mantenha-o enquanto troca um clipe por vez. Só acrescente Negative prompt para algo que continua aparecendo.
6. Confira a estimativa de preço, que inclui os segundos de referência, e execute. Passe para 1080p quando a inserção estiver correta.

O que a requisição recebe

A tarefa é alibaba/wan-2.6/reference-to-video.

Não copie um campo de outra tarefa do Wan 2.6: um image_url ou um campo de áudio neste payload é um erro de contrato, não um prompt fraco.

Escolha e apare os clipes de referência

Cada clipe deve mostrar um sujeito, grande no quadro, bem iluminado e, se possível, de mais de um ângulo. Um sujeito que fica pequeno ou em contraluz volta apenas de forma aproximada, e um clipe de um lugar vazio não dá nada ao modelo para inserir: o cenário vem do prompt. Um clipe com várias pessoas deixa pouco claro quem deve ser inserido, então recorte ou apare até o trecho em que seu sujeito está mais claro.

Apare antes de enviar. Os segundos de referência são cobrados, e alguns segundos claros transferem melhor do que uma tomada longa que se perde.

Adicione um segundo ou terceiro clipe só para um sujeito novo

Cada clipe extra acrescenta identidade, movimento e fundo que o modelo precisa resolver. Envie um segundo clipe quando a cena precisa de outro sujeito (um vendedor ao lado do mecânico) ou quando o primeiro clipe esconde uma característica que define um objeto, como a caixa de carga dianteira de uma bicicleta. Dê à segunda pessoa uma posição e uma ação distintas, porque rostos parecidos em lugares parecidos se embaralham. Se dois clipes mostram o mesmo sujeito com roupas diferentes, escolha um antes de enviar; um prompt que pede os dois devolve um meio-termo.

Para ver se um clipe adicional ajuda, mantenha fixos o seed, a duração, a resolução, o formato e o tipo de tomada, e mude apenas os clipes. O seed mantém o sorteio constante entre execuções, então o clipe que você adicionou é a principal coisa que muda; ele não promete uma repetição quadro a quadro.

Escreva a cena em torno dos clipes

Chame cada clipe de character1, character2 ou character3, na ordem em que você os enviou: o modelo só reconhece os personagens por esses nomes, então escrever “Clip 1” ou “o clipe do mecânico” o obriga a adivinhar. Diga o que cada um contribui, depois dê o cenário, a ação, a câmera e a luz. Não redescreva o que o material já mostra: isso consome os 1500 caracteres e compete com os clipes. Escreva uma tomada com uma ação clara, para você poder dizer se a inserção funcionou antes de pedir uma história.

character1 is the mechanic: keep the short silver hair and indigo apron.
character2 is the teal cargo bicycle: keep its front box and cream tires.
Place them in a quiet produce market at dawn. One continuous medium-wide shot:
character1 wheels character2 a few steps and stops beside a vegetable stall.
Slow sideways camera move, soft morning light, distant market ambience.

Use negative_prompt para o que continua aparecendo entre execuções, como uma pessoa a mais, legendas na tela ou um objeto do clipe, em vez de listar todas as exclusões com antecedência. Mude uma coisa entre as tentativas. Se a oficina vaza para o mercado, esclareça o destino e apare o clipe; mudar roupa, câmera e duração ao mesmo tempo não diz qual correção funcionou.

Tomada única ou vários planos

single mantém uma tomada contínua e é o teste certo para começar, porque você vê se o sujeito muda durante o movimento. multi deixa o modelo cortar entre planos dentro da cena; compensa a partir de cerca de 6 segundos, já que um clipe de 2 a 3 segundos raramente tem espaço para um corte. Dirija os cortes com uma lista numerada de planos no prompt, por exemplo uma chegada em plano médio geral seguida de uma vista de perto da bicicleta parando, e verifique se o sujeito continua igual depois do corte.

Formato, tamanho e duração

O formato é uma escolha da requisição, não algo tirado dos clipes, então um mesmo conjunto de referências pode ser entregue em vários formatos e uma entrega vertical não precisa de material vertical. Escreva a cena para o quadro escolhido: um panorama de mercado com a largura toda não cabe em uma entrega 9:16. Teste o formato final em vez de cortar um resultado largo depois, porque um corte pode esconder a parte que deu errado.

A duração é o principal fator de preço e também onde a semelhança se degrada. Reproduza o clipe inteiro, não o primeiro segundo, e olhe com atenção o último segundo antes de se comprometer com uma duração longa. A resolução define a tarifa e o tempo de renderização; ela não conserta um sujeito errado, então resolva a inserção em 720p e passe para 1080p no final.

Depois execute pelo código

Instale o SDK em Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor, troque os links de exemplo por clipes que você tem o direito de usar e execute:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="alibaba/wan-2.6/reference-to-video",
    input_data={
        "prompt": "character1 is the mechanic and character2 is the teal cargo bike. At a quiet "
                  "produce market at dawn, character1 wheels character2 forward and stops beside "
                  "a vegetable stall. One medium-wide continuous shot, slow sideways camera move, "
                  "distant market ambience.",
        "reference_video_urls": [
            "https://example.com/mechanic.mp4",
            "https://example.com/cargo-bike.mp4",
        ],
        "duration_seconds": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "shot_type": "single",
        "seed": 26017,
    },
    idempotency_key=str(uuid.uuid4()),
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"])  # copy the clip to your own storage now

Cotações, esperas, retentativas, callbacks e códigos de erro estão no guia de tarefas e na referência do SDK em Python; os resultados expiram, então veja retenção e entrega. A tarefa não tem entrada nem ajuste de áudio, mas o clipe volta com som gerado: descreva o que você quer ouvir no prompt (por exemplo, ambiente) e substitua na edição se precisar de um áudio específico.

Ou deixe um Agente executar

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

• CLI. Coloque o mesmo objeto input em input.json e execute spicyapi tasks create --model alibaba/wan-2.6/reference-to-video --input-file input.json --wait. Para um clipe no seu computador, spicyapi files upload ./mechanic.mp4 devolve um endereço spicy:// para usar em reference_video_urls. Veja a documentação da CLI.
• MCP server. Adicione o MCP server ao seu assistente e depois peça: "Cast the person in /path/to/mechanic.mp4 into a dawn produce market on Wan 2.6 reference-to-video, 5 seconds, 720p." Ele envia o arquivo com spicyapi_upload_file e depois chama spicyapi_task_create, que para para sua confirmação de preço.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que faz um assistente de programação ler o esquema do modelo ao vivo em vez de adivinhar campos.

Coloque os segundos de referência no orçamento

Os segundos cobrados são o comprimento da saída mais o comprimento dos clipes de referência, cada clipe arredondado para cima para um segundo inteiro, com no máximo cinco segundos de referência contados no total. Uma renderização de 5 segundos com um clipe de 3 segundos cobra 8 segundos; a mesma renderização com três clipes somando nove segundos cobra 10. A estimativa ao vivo antes de você enviar mostra o valor. Se o comprimento de um clipe não puder ser lido antes, a retenção assume cinco segundos de referência e a cobrança final usa o comprimento medido.

Os preços são as tarifas do catálogo ao vivo no momento da escrita. Uma referência mais curta e mais limpa é a maior economia: ela remove segundos cobrados e dá ao modelo um sujeito mais claro, e uma retentativa custa uma execução inteira.

Confira o resultado e corrija

Julgue a pessoa e o objeto separadamente, porque um pode se manter enquanto o outro falha. Para a pessoa: o rosto e a roupa continuam iguais mesmo em giros e depois de qualquer corte, e nenhuma pessoa extra substitui o sujeito. Para o objeto: a forma, não só a cor, sobrevive (a caixa de carga, o número de rodas), porque uma bicicleta verde-azulada comum também é verde-azulada. Olhe também para peças de cenário vindas do clipe, como a porta da oficina ou uma prateleira de ferramentas.

Se duas ou três revisões não acertarem o sujeito, troque de tarefa em vez de forçar: uma imagem composta com image-to-video, ou um dos modelos abaixo. Para um plano que você vai repetir, guarde juntos os clipes, a requisição completa e a saída sem edição.

Nível de conteúdo e consentimento

O image-to-video e o text-to-video do Wan 2.6 são Uncensored, mas o reference-to-video é Filtered. Com base nos nossos testes de setembro de 2026, um clipe de referência explícito foi recusado, então um elenco voltado a adultos pertence a outra tarefa; veja quais versões do Wan são uncensored. A inserção de referência leva um rosto reconhecível para uma cena que nunca aconteceu, então use personagens fictícios ou imagens de pessoas reais que consentiram, e marque resultados gerados como gerados onde um público poderia confundi-los com uma gravação.

A faixa mais rápida: Wan 2.6 Flash reference-to-video

Desde 14 de outubro, o Wan 2.6 Flash reference-to-video oferece a mesma inserção de personagens na faixa Flash do Wan 2.6, mais rápida e mais barata, com três diferenças que mudam o que você envia:

• Mais imagens estáticas. reference_image_urls aceita até cinco imagens em vez de duas, junto com até três clipes em reference_video_urls, cinco referências no total. As imagens não são cobradas em nenhuma das duas tarefas; os clipes somam seus segundos como descrito acima, até cinco no total.
• O som é um interruptor. generate_audio vem desligado por padrão e devolve só a imagem, a $0,0225 por segundo em 720p ou $0,03375 em 1080p. Ligado, acrescenta vozes, efeitos e ambiente gerados, a $0,045 ou $0,0675. A tarefa desta página sempre devolve som, a $0,065 por segundo em 720p.
• É Uncensored. Nos nossos testes de 14 de outubro, pedidos com referências adultas voltaram como pedido, sem nenhuma recusa.

Nomeie as referências no prompt como character1, character2 e assim por diante, primeiro os clipes e depois as imagens; a chamada é alibaba/wan-2.6-flash/reference-to-video. O Flash troca um pouco de detalhe fino por rapidez, então serve para rascunhos de elenco, volume e cenas voltadas a adultos. Fique nesta tarefa quando uma única tomada precisar carregar a textura mais fina da faixa completa do Wan 2.6.

Quando outro modelo serve melhor

Fique no reference-to-video do Wan 2.6 quando suas referências forem até três clipes e duas imagens estáticas e você quer a inserção Wan 720p mais barata ($0,065 por segundo contra $0,09 no Wan 3.0), com cortes multi-shot opcionais. Apare os clipes, nomeie cada um no prompt, teste em 720p em uma única tomada e abra a tarefa reference-to-video para conferir o preço ao vivo dos seus clipes antes de executar.