API Video Head Swap: analisi, scelta del soggetto e montaggio

Video Head Swap è un flusso API in due fasi: analizza un MP4 di 5–30 secondi, guarda le anteprime numerate delle teste e poi invia la posizione scelta e i ritratti sostitutivi al montaggio. Viso, acconciatura, colore dei capelli e forma della testa cambiano; corpo, abbigliamento, movimento, audio e tutte le persone che non selezioni restano come sono stati ripresi.

Qui vedi prima ogni testa rilevata e indichi quella che vuoi, prima di pagare il montaggio. Monta un video esistente; non anima due foto fisse trasformandole in una performance (per questo usa un modello da immagine a video).

Scegli lo scambio giusto

Lo scambio di volto è la scelta più economica e più semplice ogni volta che i capelli della clip possono restare. Lo scambio di testa conviene quando i nuovi capelli fanno parte del personaggio, al costo di una giunzione al collo che devi ispezionare.

Prepara la sorgente e i ritratti di riferimento

Usa solo immagini di persone che sei autorizzato a elaborare: la tua, quella di un performer con un'autorizzazione firmata o una testa generata. Tutte le persone visibili devono essere adulte. Entrambe le chiamate sono senza censura, quindi SpicyAPI non aggiunge alcun filtro sui contenuti e questa verifica spetta a te.

In questo esempio, un adulto fittizio con una giacca color ruggine si volta verso un altro adulto durante una conversazione di dodici secondi. Sostituisci solo la testa della prima persona; mantieni la seconda persona, i vestiti e il dialogo.

Esporta la sorgente definitiva prima dell'analisi: MP4, fino a 90 MB, 5–30 secondi. video_url accetta un link HTTPS pubblico che restituisce l'MP4 stesso, non una pagina di lettore HTML, oppure un URI spicy:// dal flusso di caricamento gratuito, che è la via più affidabile per un file locale. Se in seguito tagli, ritagli o ricodifichi la sorgente, riesegui l'analisi.

Prepara da 1 a 3 ritratti dello stesso adulto sostitutivo. Una vista frontale e una a tre quarti sono una buona coppia di partenza; aggiungi un profilo se la sorgente contiene una rotazione significativa della testa. Mantieni capelli ed età apparente coerenti nell'intero set. Allinea anche i ritratti alla clip: illuminali dalla direzione in cui è illuminato il piano, con la testa a un angolo simile. La giunzione al collo è il punto in cui si vede una discordanza e nessun campo della richiesta la compensa. I riferimenti di guardaroba a figura intera appartengono alla sostituzione del personaggio; questo compito richiede che la testa e i capelli previsti siano chiaramente visibili.

Per un'immagine di riferimento fittizia, usa un brief come questo:

Ritratto fotografico di riferimento di un uomo adulto fittizio, circa 35 anni, capelli corti scuri, barba curata ed espressione neutra, con indosso una camicia semplice completamente abbottonata. Luce morbida e uniforme, volto e capelli liberi, sfondo semplice. Vista frontale, nessun'altra persona, nessun testo.

Crea gli altri angoli partendo da quell'identità approvata, invece di chiedere persone non correlate tra loro. Il montaggio non ha un campo prompt, quindi i riferimenti portano tutto il risultato.

Illustrazione di un set di riferimenti frontale, a tre quarti e di profilo.

Provalo prima nel Playground

1. Apri la pagina di montaggio di Video Head Swap e resta sulla scheda Playground, in vista Form. Accedi con un account con credito per eseguire.
2. Passo 1, Find the people in your clip. Aggiungi la clip sotto Input video (trascina l'MP4 o usa Asset URL) e scegli Resolution, 480p o 720p. Il montaggio deve usare lo stesso valore, quindi scegli quello che vuoi per la clip finale. Premi Find people in this clip ($0.08).
3. Passo 2, Choose who to replace. Ogni testa rilevata compare come anteprima numerata. Scegli quella che vuoi e aggiungi da una a tre foto di riferimento dell'adulto sostitutivo. Imposta un Seed solo se vuoi confrontare i set di riferimenti in modo equo; altrimenti omettilo.
4. Esegui il montaggio, poi controlla mandibola, collo, capelli e colletto nel risultato con l'audio attivo.

L'analisi resta riutilizzabile per 24 ore, così puoi provare un altro set di riferimenti partendo dalle stesse anteprime senza pagare di nuovo il tracciamento. Ogni montaggio accettato, anche con un nuovo set di riferimenti o un nuovo seed, è una nuova task a pagamento. Se nessuna anteprima mostra la persona che vuoi, la soluzione è una ripresa più chiara: una testa mai chiaramente visibile non può essere tracciata e una clip senza teste tracciabili fallisce con la trattenuta rilasciata.

La pagina di analisi esegue il passo 1 da sola; un'analisi riuscita viene addebitata anche se ti fermi lì.

Poi eseguilo dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY nel tuo ambiente e salva questo come swap.py. analyze stampa gli URL delle anteprime; edit prende l'ID della task di analisi e la posizione dell'anteprima che hai scelto. Il montaggio deve usare la stessa chiave API e la stessa risoluzione dell'analisi, e nessun video_url: eredita la clip analizzata.

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

Esegui python swap.py analyze, apri ogni anteprima e annota il numero dell'adulto che vuoi (la posizione 0 è la prima immagine restituita, non una regola da sinistra a destra; non ripiegare mai sulla 0 se la tua persona non c'è), poi python swap.py edit <analysis_task_id> 1. Il montaggio accetta da 1 a 10 soggetti con da 1 a 3 immagini di riferimento della stessa persona ciascuno; non ci sono input per maschera, abbigliamento, audio o prompt. Creazione, attesa, nuovi tentativi, chiavi di idempotenza e download sono trattati nella guida alle task e nel riferimento dell'SDK Python; un file locale passa dal flusso di caricamento gratuito e torna come URI spicy:// per video_url.

Oppure lascia che sia un agente a eseguirlo

Quando un assistente deve eseguire le due chiamate, tutti e tre gli strumenti ufficiali mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento.

• CLI. Metti l'oggetto input dell'analisi (video_url, resolution) in analysis.json, poi:

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

Esegui il montaggio allo stesso modo con edit.json. Vedi la documentazione della CLI; npx @spicyapi/cli funziona senza installazione.

• Server MCP. Aggiungi il server MCP, poi chiedi: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Carica il file con spicyapi_upload_file, chiama spicyapi_task_create, che si ferma per la tua conferma del prezzo, poi spicyapi_task_wait. Scegli tu la posizione, poi chiedi il montaggio.
• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che fa leggere a un assistente di programmazione lo schema del modello in tempo reale invece di indovinare i campi.

Come appare un montaggio finito

L'esempio di modello pubblicato qui sotto è una clip sorgente di dieci secondi e il suo montaggio a 480p con un ritratto di riferimento. Capelli e volto cambiano; vestito, andatura, controluce e camera restano. Controlla prima mandibola e linea del collo, dove si vede una discordanza di luce o di angolo.

Quanto costa

Il montaggio costa $0.064 per secondo addebitato a 480p e $0.12 a 720p. La fatturazione procede a blocchi di cinque secondi, con un minimo di cinque secondi e un tetto di trenta secondi. Una clip di 10 secondi a 480p costa $0.72 in tutto: $0.08 di analisi più $0.64 di montaggio.

Prima della liquidazione il montaggio riserva il massimo di trenta secondi, $1.92 a 480p o $3.60 a 720p. Una clip di dodici secondi a 720p viene trattenuta a $3.60 anche se il suo montaggio viene addebitato a $1.80; il resto viene rilasciato quando la task viene liquidata.

Diagnosticare separatamente selezione, identità e consegna

Illustrazione della revisione di capelli, colletto e una mano in primo piano.

Riproduci il video restituito con l'audio. Il montaggio mantiene l'audio e i movimenti del corpo della sorgente; non cambia la voce di chi parla e la scena non è garantita identica pixel per pixel. Ispeziona anche la persona non selezionata, soprattutto durante gli incroci. Se una mano attraversa il volto sostituito, scorri il contatto e la riapparizione passo dopo passo invece di approvare solo un primo fotogramma accattivante.

Salva subito il video accettato nel tuo archivio: i link del risultato durano circa 20 minuti e i risultati vengono conservati per al massimo 14 giorni, quindi un ID di analisi, un'immagine di anteprima e un URL temporaneo dei media non sono una copia permanente.