API Video Head Swap: análise, escolha do alvo e edição

Video Head Swap é um fluxo de API em duas etapas: analise um MP4 de 5 a 30 segundos, veja as prévias de cabeças numeradas e depois envie a posição escolhida e os retratos de substituição para a edição. Rosto, penteado, cor do cabelo e formato da cabeça mudam; corpo, figurino, movimento, áudio e todas as pessoas que você não seleciona permanecem como foram gravados.

Aqui você vê primeiro cada cabeça rastreada e indica qual quer, antes de pagar pela edição. Ela edita um vídeo existente; não anima duas fotos fixas até transformar em uma performance (use um modelo de imagem para vídeo para isso).

Escolha a troca certa

A troca de rosto é a opção mais barata e mais simples sempre que o cabelo do clipe puder ficar. A troca de cabeça compensa quando o cabelo novo faz parte do personagem, ao custo de uma emenda no pescoço que você precisa inspecionar.

Prepare a fonte e os retratos de referência

Use apenas imagens de pessoas que você está autorizado a processar: a sua, a de um intérprete com autorização assinada ou uma cabeça gerada. Todos os que aparecem precisam ser adultos. As duas chamadas são sem censura, então a SpicyAPI não adiciona nenhum filtro de conteúdo e essa verificação cabe a você.

Neste exemplo, um adulto fictício com jaqueta cor de ferrugem se vira para outro adulto durante uma conversa de doze segundos. Substitua apenas a cabeça da primeira pessoa; mantenha a segunda pessoa, a roupa e o diálogo.

Exporte a fonte final antes da análise: MP4, até 90 MB, de 5 a 30 segundos. video_url aceita um link HTTPS público que devolva o próprio MP4, não uma página HTML de player, ou um URI spicy:// do fluxo de upload gratuito, que é o caminho mais confiável para um arquivo local. Se depois você cortar, recortar ou recodificar a fonte, rode a análise de novo.

Prepare de 1 a 3 retratos do mesmo adulto substituto. Uma vista de frente e uma de três quartos formam um bom par inicial; acrescente um perfil se a fonte tiver uma virada acentuada. Mantenha cabelo e idade aparente coerentes em todo o conjunto. Combine também com o clipe: ilumine os retratos na direção em que o plano é iluminado, com a cabeça em ângulo semelhante. A emenda no pescoço é onde a inconsistência aparece e nenhum campo da solicitação compensa isso. Referências de figurino de corpo inteiro pertencem à troca de personagem; esta tarefa exige que a cabeça e o cabelo pretendidos estejam claramente visíveis.

Para uma imagem de referência fictícia, use um briefing como este:

Retrato fotográfico de referência de um homem adulto fictício, cerca de 35 anos, cabelo curto escuro, barba aparada e expressão neutra, usando uma camisa lisa totalmente abotoada. Luz suave e uniforme, rosto e cabelo sem obstrução, fundo simples. Vista de frente, sem outras pessoas, sem texto.

Crie os outros ângulos a partir dessa identidade aprovada, em vez de pedir pessoas sem relação entre si de forma independente. A edição não tem campo prompt, então as referências carregam todo o resultado.

Ilustração de um conjunto de referência frontal, de três quartos e de perfil.

Teste primeiro no Playground

1. Abra a página de edição do Video Head Swap e fique na aba Playground, na visão Form. Entre com uma conta com saldo para executar.
2. Passo 1, Find the people in your clip. Adicione o clipe em Input video (solte o MP4 ou use Asset URL) e escolha Resolution, 480p ou 720p. A edição precisa usar o mesmo valor, então escolha o que você quer que o clipe final tenha. Aperte Find people in this clip ($0,08).
3. Passo 2, Choose who to replace. Cada cabeça rastreada aparece como uma prévia numerada. Escolha a que você quer e acrescente de uma a três fotos de referência do adulto substituto. Defina um Seed apenas se quiser comparar conjuntos de referência de forma justa; caso contrário, omita.
4. Rode a edição e depois verifique mandíbula, pescoço, cabelo e gola no resultado com o som ligado.

A análise continua reutilizável por 24 horas, então você pode testar outro conjunto de referência a partir das mesmas prévias sem pagar o rastreamento de novo. Cada edição aceita, inclusive com novo conjunto de referência ou novo seed, é uma nova tarefa paga. Se nenhuma prévia mostrar a pessoa que você quer, um plano mais claro é a solução: uma cabeça nunca vista com nitidez não pode ser rastreada, e um clipe sem cabeça rastreável falha com a retenção liberada.

A página de análise executa o passo 1 sozinha; uma análise bem-sucedida é cobrada mesmo que você pare nela.

Depois rode pelo código

Instale o SDK Python (pip install spicyapi), defina SPICY_API_KEY no seu ambiente e salve isso como swap.py. analyze imprime as URLs das prévias; edit recebe o ID da tarefa de análise e a posição de prévia que você escolheu. A edição precisa usar a mesma chave de API e a mesma resolução da análise, e nenhum video_url: ela herda o clipe analisado.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              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')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

Rode python swap.py analyze, abra todas as prévias e anote o número do adulto que você quer (a posição 0 é a primeira imagem devolvida, não uma regra da esquerda para a direita; nunca volte para 0 se a sua pessoa não estiver lá), depois rode python swap.py edit <analysis_task_id> 1. A edição aceita de 1 a 10 alvos com de 1 a 3 imagens de referência da mesma pessoa cada; não há entrada de máscara, figurino, áudio ou prompt. Criação, espera, novas tentativas, chaves de idempotência e downloads estão no guia de tarefas e na referência do SDK Python; um arquivo local passa pelo fluxo de upload gratuito e volta como um URI spicy:// para video_url.

Ou deixe um agente executar

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

• CLI. Coloque o objeto input da análise (video_url, resolution) em analysis.json e então:

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

Rode a edição do mesmo jeito com edit.json. Veja a documentação da CLI; npx @spicyapi/cli funciona sem instalar.

• Servidor MCP. Adicione o servidor MCP e então pergunte: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Ele faz upload do arquivo com spicyapi_upload_file, chama spicyapi_task_create, que para para você confirmar o preço, e depois spicyapi_task_wait. Escolha a posição você mesmo e então peça a edição.
• 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.

Como fica uma edição finalizada

O exemplo de modelo publicado abaixo é um clipe de origem de dez segundos e a edição dele em 480p com um retrato de referência. Cabelo e rosto mudam; vestido, caminhada, contraluz e câmera permanecem. Verifique primeiro mandíbula e linha do pescoço, onde uma inconsistência de luz ou de ângulo aparece.

Quanto custa

A edição custa $0,064 por segundo cobrado em 480p e $0,12 em 720p. A cobrança avança em blocos de cinco segundos, com mínimo de cinco segundos e teto de trinta segundos. Um clipe de 10 segundos em 480p custa $0,72 no total: $0,08 de análise mais $0,64 de edição.

Antes da liquidação, a edição reserva o máximo de trinta segundos, $1,92 em 480p ou $3,60 em 720p. Um clipe de doze segundos em 720p fica retido em $3,60 mesmo com a cobrança de edição de $1,80; o resto é liberado quando a tarefa é liquidada.

Diagnostique seleção, identidade e entrega separadamente

Ilustração da revisão de cabelo, gola e uma mão em primeiro plano.

Reproduza o vídeo devolvido com som. A edição mantém o áudio e o movimento corporal da fonte; ela não muda a voz de quem fala, e o cenário não tem garantia de ser idêntico pixel a pixel. Inspecione também a pessoa não selecionada, especialmente durante os cruzamentos. Se uma mão cruzar o rosto substituído, percorra o contato e o reaparecimento quadro a quadro em vez de aprovar apenas um primeiro quadro bonito.

Guarde o vídeo aceito imediatamente no seu próprio armazenamento: os links de resultado duram cerca de 20 minutos e os resultados são mantidos por no máximo 14 dias, então um ID de análise, uma imagem de prévia e uma URL temporária de mídia não são uma cópia permanente.