Video Character Swap: referências, escolha do alvo e revisão

Use Character Swap quando a substituição tiver de mudar a aparência inteira de uma pessoa, incluindo compleição e roupa, enquanto a cena, o movimento de câmera e o áudio original permanecem. O Character Swap deixa você escolher qual pessoa do clipe será trocada: analise o clipe final, inspecione as pré-visualizações numeradas e então envie o índice de pré-visualização escolhido junto com uma a três imagens da pessoa substituta. Se a roupa original precisa permanecer, use um fluxo de head swap ou face swap.

Na SpicyAPI, a análise e a edição são tarefas pagas separadas. Uma fonte de sete segundos custa $0,72 a 480p ou $1,28 a 720p no total: uma análise mais a edição, que arredonda para dez segundos. O Playground executa as duas etapas no navegador, e a API aceita as mesmas entradas. Você precisa de autorização tanto para o material quanto para a semelhança nas imagens de referência.

Prepare uma cena de sete segundos e uma substituta de corpo inteiro

Nosso exemplo é um plano de sete segundos de alguém levando uma caixa de ferramentas fechada até uma bancada enquanto outro adulto fica ao lado. A pessoa que carrega é substituída por uma adulta fictícia com jaqueta de trabalho azul-marinho e calça grafite, o visual das ilustrações abaixo. A bancada, a caixa de ferramentas, a outra pessoa e a performance original permanecem.

Exporte exatamente a fonte de sete segundos que você pretende editar. Preserve a pegada inicial, o ato de carregar e a soltura quando a caixa de ferramentas chega à bancada. A entrada é MP4 de 5 a 30 segundos com até 90 MB. Enviar o arquivo é o caminho mais confiável; um link direto precisa apontar para o próprio arquivo MP4, porque uma página com player falha (a cobrança é estornada). Cortar ou recodificar depois da análise exige uma nova análise.

O rastreador segue pessoas que permanecem razoavelmente grandes e visíveis, então corte no trecho que importa e evite períodos longos em que a pessoa desejada está totalmente oculta. Um corte mais curto também custa menos, porque a edição é cobrada em blocos de cinco segundos.

Para a substituta, prepare uma visão de corpo inteiro de frente e uma de três quartos da mesma adulta, com o mesmo look. Uma referência clara é aceita; três é o máximo por alvo. Um retrato de cabeça e ombros deixa compleição e roupa por conta da aproximação, então mostre mangas, mãos e calçado, e ilumine as referências como o material em vez de escolher o retrato mais nítido. Não combine o rosto de uma pessoa, a calça de outra e uma jaqueta diferente na terceira imagem. O serviço recebe isso como referências para uma substituição, não como camadas de roupa atribuídas separadamente.

Um briefing utilizável para gerar a imagem é:

Retrato de referência de corpo inteiro de uma mulher adulta fictícia, cerca de 30 anos, com jaqueta de trabalho azul-marinho lisa, calça grafite e sapatos flats escuros. Pose relaxada de frente, mãos visíveis, mangas e calçado legíveis, fundo neutro. Sem caixa de ferramentas, sem outras pessoas, sem letras.

Gere ou fotografe um segundo ângulo do mesmo design já estabelecido, se precisar. A edição de character swap não tem campo de prompt de texto, seletor de roupa nem máscara corporal, então a roupa desejada precisa estar nas imagens de referência.

Ilustração de um conjunto de referências de corpo inteiro, frontal e de três quartos.

Teste primeiro no Playground

1. Abra a página do modelo Video Character Swap e fique na aba Playground na visão Form. Entre com uma conta com saldo para executar.
2. Em Step 1, Find the people in your clip, adicione o MP4 de sete segundos em Input video (enviar é mais confiável que link) e escolha a Resolution desejada para o clipe final, 480p ou 720p. A edição precisa usar o mesmo valor.
3. Aperte Find people in this clip ($0,08). Todas as pessoas rastreadas aparecem em Step 2, Choose who to replace, uma pré-visualização recortada por pessoa.
4. Escolha a pré-visualização de quem carrega a caixa de ferramentas, adicione uma a três imagens de referência da substituta e execute a edição. Um Seed é opcional.

A posição 0 é a primeira pré-visualização retornada, não necessariamente a pessoa mais à esquerda ou a maior, porque a ordem vem do rastreamento e não da posição na tela. Se quem carrega for a segunda pré-visualização, esse é o índice 1. Mantenha a ordem retornada ao salvar as pré-visualizações: nomes de arquivo em ordem alfabética ou uma galeria ordenada podem mudar o índice silenciosamente.

Se a pessoa pretendida não tiver pré-visualização, não pague uma edição adivinhando um número próximo. Nenhuma imagem de referência traz de volta uma pessoa que não tem pré-visualização, então use uma tomada em que essa pessoa esteja claramente visível. Uma análise que não encontra ninguém termina como falha e a reserva é liberada; uma análise bem-sucedida é cobrada mesmo que você decida não trocar.

Depois chame pelo código

Instale o SDK Python (pip install spicyapi), defina SPICY_API_KEY e execute o que segue. Ele envia o clipe e duas referências, roda a análise, imprime os links das pré-visualizações, pergunta qual índice trocar e então envia a edição. As duas tarefas são cobradas.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
RESOLUTION = "720p"     # must be identical in both calls

clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")

analysis_task = client.create_task(
    model="spicyapi/character-swap-v1/video-analyze",
    input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
    raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")

previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
    raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews):  # keep the returned order
    print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
    raise ValueError("Choose one of the returned preview indices before creating an edit")

edit_task = client.create_task(
    model="spicyapi/character-swap-v1/video-edit",
    input_data={
        "analysis_task_id": analysis["taskId"],  # video_url is inherited from the analysis
        "resolution": RESOLUTION,
        "swap_targets": [{"object_index": chosen,
                          "image_urls": [front["uri"], angled["uri"]]}],
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
    raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy it to your own storage now

Envios, esperas, erros e novas tentativas estão no guia de subject swap, na documentação de tarefas e na referência do SDK Python. Use a mesma chave de API nas duas etapas e rode a edição em até 24 horas após a análise (um clipe enviado também expira depois de um dia); uma análise pode alimentar várias edições cobradas separadamente. As pessoas que você não listar permanecem intactas, e um índice pertence a esta análise, então não o reutilize como ID de personagem em outra tomada.

A substituição de personagem inteiro tem a intenção de preservar cena, movimento de câmera, coreografia e áudio original. Esse escopo não promete pixels de fundo inalterados nem uma voz nova.

Ou deixe um agente executar

Se um assistente deve rodar a troca, dê a ele a CLI ou o servidor MCP. Ambos mostram o preço e pedem confirmação antes de uma chamada paga. A Skill adiciona instruções por cima de qualquer um dos dois.

• CLI. spicyapi executa uma tarefa a partir de um terminal (npx @spicyapi/cli funciona sem instalar):

``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``

analysis.json contém {"video_url": "spicy://...", "resolution": "720p"}. Olhe as pré-visualizações e então rode o comando com video-edit, a chave própria workshop-edit-v1 e um input.json com analysis_task_id, resolution e swap_targets. Reutilize uma chave só para uma requisição inalterada; uma nova fonte, um novo alvo ou um novo conjunto de referências precisa de chave nova.

• Servidor MCP. Adicione o servidor MCP (o trecho de configuração está naquela página) ao seu assistente e então pergunte: "Analise ./workshop-seven-seconds.mp4 a 720p com Character Swap e mostre as pré-visualizações." Depois de escolher a pessoa, diga: "Substitua o índice 1 usando ./replacement-front.png e ./replacement-three-quarter.png." Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para sua confirmação de preço) e depois spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala a Agent Skill, que ensina um assistente de programação a ler o schema atual e a reutilizar chaves de idempotência. Ela não roda tarefas sozinha, então use-a com a CLI ou o MCP. Qual pré-visualização trocar continua sendo sua decisão.

Entenda a cobrança antes de fazer variantes

Os preços vêm do catálogo público (outubro de 2026).

A duração da edição é arredondada para blocos inteiros de cinco segundos, com mínimo de cinco segundos e teto de trinta segundos. Uma fonte de 5 segundos usa um bloco; 5,1 segundos usam dois. Antes do envio, a estimativa da edição reserva o máximo de trinta segundos, $1,92 a 480p ou $3,60 a 720p, e a diferença volta quando a tarefa é liquidada. Uma checagem de orçamento precisa portanto permitir a reserva, não apenas o valor final esperado. Uma requisição rejeitada na criação (resolução divergente, ID de análise errado, índice repetido) não cria nem cobra nada.

Duas edições em 720p da fonte de sete segundos, reutilizando uma análise, custam $2,48 no total: $0,08 mais duas vezes $1,20. Mudar referências ou seed é uma nova edição paga, não uma revisão gratuita.

Conserte o problema certo

Ilustração da revisão de um quadro impresso.

Assista a quem carrega, à caixa de ferramentas e ao adulto não selecionado juntos, na velocidade normal. Depois inspecione pegada, contato com a bancada e soltura. Um rosto novo pode parecer excelente enquanto a ação central falha. Se apenas a último meio segundo tiver defeito, cortar pode bastar; se a pegada estiver quebrada do começo ao fim, escolha uma fonte mais clara ou use um escopo mais estreito de substituição de cabeça quando o corpo e a roupa originais puderem permanecer.

Copie o clipe aceito para o seu próprio armazenamento antes que ele expire: os resultados são mantidos por cerca de 14 dias (veja retenção e entrega de mídia).