Video Character Swap: riferimenti, scelta del bersaglio e revisione

Usa Character Swap quando la sostituzione deve cambiare l'aspetto complessivo di una persona, corporatura e abbigliamento compresi, mentre scena, movimento di camera e audio originale restano invariati. Character Swap ti lascia scegliere quale persona del clip viene sostituita: analizza il clip finale, ispeziona le anteprime numerate, poi invia l'indice di anteprima scelto insieme a da una a tre immagini della persona sostitutiva. Se l'abbigliamento originale deve restare, usa invece un flusso head swap o face swap.

Su SpicyAPI, l'analisi e l'editing sono attività a pagamento separate. Una sorgente di sette secondi costa in totale $0.72 a 480p o $1.28 a 720p: un'analisi più l'editing, che arrotonda fino a dieci secondi. Il Playground esegue entrambi i passaggi nel browser e l'API accetta gli stessi input. Ti serve un'autorizzazione sia per il footage sia per la somiglianza nelle immagini di riferimento.

Preparare una scena di sette secondi e una sostituzione a figura intera

Il nostro esempio è un'inquadratura di sette secondi in cui qualcuno porta una cassetta degli attrezzi chiusa verso un banco mentre un altro adulto sta in piedi accanto. La persona che porta viene sostituita da un'adulta fittizia con giacca da lavoro blu marina e pantaloni grigio antracite, l'aspetto delle illustrazioni qui sotto. Banco, cassetta degli attrezzi, l'altra persona e la performance originale restano.

Esporta esattamente la sorgente di sette secondi che intendi editare. Conserva la presa iniziale, l'azione di trasporto e il rilascio quando la cassetta degli attrezzi raggiunge il banco. L'input è un MP4 di 5–30 secondi fino a 90 MB. Caricare il file è la via più affidabile; un link diretto deve puntare al file MP4 stesso, perché una pagina con un lettore fallisce (l'addebito viene rimborsato). Ritagliare o ricodificare dopo l'analisi richiede una nuova analisi.

Il tracker segue le persone che restano ragionevolmente grandi e visibili, quindi taglia sul passaggio che conta ed evita periodi lunghi in cui la persona che vuoi è completamente nascosta. Un taglio più breve costa anche meno, perché l'editing viene fatturato a blocchi di cinque secondi.

Per la sostituzione prepara una vista a figura intera frontale e una a tre quarti della stessa adulta, con lo stesso outfit. Un riferimento chiaro è accettato; tre è il massimo per bersaglio. Un ritratto testa e spalle lascia corporatura e abbigliamento all'approssimazione, quindi mostra maniche, mani e calzature e illumina i riferimenti come il footage invece di scegliere il ritratto più nitido. Non combinare il volto di una persona, i pantaloni di un'altra e una giacca diversa nella terza immagine. Il servizio riceve questi come riferimenti per una sostituzione, non come strati di abbigliamento assegnati separatamente.

Un brief utilizzabile per generare l'immagine è:

Ritratto di riferimento a figura intera di una donna adulta fittizia, circa 30 anni, con giacca da lavoro blu marina liscia, pantaloni grigio antracite e scarpe basse scure. Posa rilassata frontale, mani visibili, maniche e calzature leggibili, sfondo neutro. Nessuna cassetta degli attrezzi, nessun'altra persona, nessuna scrittura.

Genera o fotografa un secondo angolo dello stesso design già stabilito se serve. L'editing character swap non ha un campo prompt testuale, né un selettore di abbigliamento o una maschera del corpo, quindi l'abbigliamento desiderato deve essere nelle immagini di riferimento.

Illustrazione di un set di riferimenti a figura intera, frontale e in tre quarti.

Provala prima nel Playground

1. Apri la pagina del modello Video Character Swap e resta nella scheda Playground in vista Form. Accedi con un account con credito per eseguire.
2. In Step 1, Find the people in your clip, aggiungi l'MP4 di sette secondi sotto Input video (caricare è più affidabile di un link) e scegli la Resolution desiderata per il clip finale, 480p o 720p. L'editing deve usare lo stesso valore.
3. Premi Find people in this clip ($0.08). Ogni persona rilevata compare in Step 2, Choose who to replace, come un'anteprima ritagliata per persona.
4. Scegli l'anteprima della persona che porta la cassetta degli attrezzi, aggiungi da una a tre immagini di riferimento della sostituzione e avvia l'editing. Un Seed è opzionale.

La posizione 0 è la prima anteprima restituita, non necessariamente la persona più a sinistra o la più grande, perché l'ordine viene dal tracking e non dalla posizione sullo schermo. Se chi porta è la seconda anteprima, quello è l'indice 1. Mantieni l'ordine restituito quando salva le anteprime: nomi di file alfabetici o una galleria ordinata possono cambiare silenziosamente l'indice.

Se la persona prevista non ha un'anteprima, non pagare un editing indovinando un numero vicino. Nessuna immagine di riferimento può far tornare una persona senza anteprima, quindi usa una ripresa in cui quella persona sia chiaramente visibile. Un'analisi che non trova nessuno finisce come fallita e la sua prenotazione viene rilasciata; un'analisi riuscita viene addebitata anche se decidi di non fare lo swap.

Poi chiamala dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY ed esegui quanto segue. Carica il clip e due riferimenti, esegue l'analisi, stampa i link delle anteprime, chiede quale indice sostituire e poi invia l'editing. Entrambe le attività vengono addebitate.

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

Caricamenti, attese, errori e ripetizioni sono nella guida subject swap, nella documentazione delle task e nel riferimento dell'SDK Python. Usa la stessa chiave API per entrambi i passaggi ed esegui l'editing entro 24 ore dall'analisi (anche un clip caricato scade dopo un giorno); un'analisi può alimentare più editing addebitati separatamente. Le persone che non elenchi restano intatte e un indice appartiene a questa analisi, quindi non riutilizzarlo come ID personaggio in un'altra ripresa.

Una sostituzione dell'intero personaggio intende conservare scena, movimento di camera, coreografia e audio originale. Questo perimetro non promette pixel di sfondo invariati né una voce nuova.

Oppure fai eseguire a un agente

Se un assistente deve eseguire lo swap, dagli la CLI o il server MCP. Entrambi mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento. La Skill aggiunge istruzioni sopra l'uno o l'altro.

• CLI. spicyapi esegue una task da terminale (npx @spicyapi/cli funziona senza installazione):

``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 contiene {"video_url": "spicy://...", "resolution": "720p"}. Guarda le anteprime, poi esegui il comando con video-edit, la sua chiave workshop-edit-v1 e un input.json con analysis_task_id, resolution e swap_targets. Riutilizza una chiave solo per una richiesta invariata; una nuova sorgente, un nuovo bersaglio o un nuovo set di riferimenti richiede una chiave nuova.

• Server MCP. Aggiungi il server MCP (il suo snippet di configurazione è su quella pagina) al tuo assistente, poi chiedi: "Analizza ./workshop-seven-seconds.mp4 a 720p con Character Swap e mostrami le anteprime." Dopo aver scelto la persona, dite: "Sostituisci l'indice 1 usando ./replacement-front.png e ./replacement-three-quarter.png." Chiama spicyapi_upload_file, poi spicyapi_task_create (che si ferma per la tua conferma del prezzo), poi spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installa la Agent Skill, che insegna a un assistente di programmazione a leggere lo schema attivo e a riutilizzare le chiavi di idempotenza. Non può eseguire task da solo, quindi usala con la CLI o MCP. Quale anteprima sostituire resta una tua decisione.

Capire l'addebito prima di fare le varianti

I prezzi provengono dal catalogo pubblico (ottobre 2026).

La durata dell'editing viene arrotondata a blocchi interi di cinque secondi, con un minimo di cinque secondi e un tetto di trenta secondi. Una sorgente di 5 secondi usa un blocco; 5,1 secondi ne usano due. Prima dell'invio, la stima dell'editing riserva il massimo di trenta secondi, $1.92 a 480p o $3.60 a 720p, e la differenza viene restituita quando la task si assesta. Un controllo di budget deve quindi consentire la prenotazione, non solo l'importo finale previsto. Una richiesta respinta in fase di creazione (risoluzione diversa, ID analisi errato, indice ripetuto) non crea né addebita nulla.

Due editing a 720p della sorgente di sette secondi, riutilizzando un'analisi, costano $2.48 in totale: $0.08 più due volte $1.20. Cambiare riferimenti o seed è un nuovo editing a pagamento, non una revisione gratuita.

Correggi il problema giusto

Illustrazione della revisione di un fotogramma stampato.

Guarda insieme chi porta, la cassetta degli attrezzi e l'adulto non selezionato a velocità normale. Poi ispeziona presa, contatto con il banco e rilascio. Un volto nuovo può sembrare eccellente mentre l'azione centrale fallisce. Se il difetto è solo nell'ultimo mezzo secondo, ritagliare può bastare; se la presa è rotta per tutto il corso, scegli una sorgente più chiara o usa un perimetro di sostituzione della testa più stretto quando il corpo e l'abbigliamento originali possono restare.

Copia il clip accettato nel tuo archivio prima che scada: i risultati sono conservati per circa 14 giorni (vedi conservazione e consegna dei media).