Introduzione
Video Head Swap riceve l'id del task di un'analisi, le posizioni scelte fra le sue anteprime e da una a tre foto di riferimento per ciascuna, e restituisce la clip con quelle teste sostituite. Capelli, forma della testa e identità cambiano; corpo, costumi, movimento, inquadratura e traccia audio originale restano come sono stati girati. Le teste che non elenchi non vengono toccate.
Video Head Swap si svolge in due chiamate. La prima traccia ogni testa in una clip da 5 a 30 secondi e restituisce un fermo immagine di anteprima per testa, in ordine fisso. La seconda riceve le posizioni che hai scelto e da una a tre foto di riferimento per ciascuna, e restituisce la clip con quelle teste sostituite e l'audio originale intatto.
Caratteristiche principali
Chi cambia lo decidi tu
La maggior parte degli endpoint di questo tipo deve indovinare a quale persona ti riferivi. Qui la prima chiamata ti mostra ogni testa trovata, numerata, e la seconda tocca solo i numeri che rimandi indietro. In una clip con quattro persone ne cambi una e le altre tre restano esattamente come sono state girate.
Tieni video e risoluzione identici
Video Head Swap non è un endpoint ma una coppia. La prima chiamata, video-analyze, traccia tutte le teste di una clip da 5 a 30 secondi e restituisce un'anteprima per testa in ordine fisso, a tariffa fissa per richiesta, qualunque sia la durata della clip e quante teste trovi. La seconda chiamata, video-edit, riceve l'id del task di quell'analisi, le posizioni che hai scelto e da una a tre foto di riferimento per ciascuna, e restituisce una sola clip con la traccia audio originale intatta, addebitata al secondo di girato in 480p o 720p. I dati di tracciamento non arrivano mai fino a te: lavori con il tuo id del task e con posizioni numerate da zero, che corrispondono esattamente alle anteprime che hai visto. Le due chiamate devono usare lo stesso video e la stessa risoluzione, e in caso di scostamento la seconda viene rifiutata invece di passare in silenzio.
Parametri della richiesta
| Parametro | Obbligatorio | Nota |
|---|---|---|
analysis_task_id | Sì | L'id del task della chiamata di analisi di questa clip. Le sue anteprime sono elencate nello stesso ordine di |
swap_targets | Sì | Una voce per ogni testa da sostituire; quelle che ometti non vengono toccate. |
video_url | No | Facoltativo. Se lo ometti viene usato il video dell'analisi. almeno 1 caratteri |
resolution | No | Deve coincidere con la risoluzione con cui è girata l'analisi. È anche il campo che determina la fascia di prezzo. |
seed | No | Seme casuale; zero chiede un seme a caso. |
Prezzi
L’addebito avviene a blocchi interi di 5 secondi della clip di origine: una clip da 6 secondi costa quanto 10 secondi. La stima mostrata prima dell’invio usa la durata reale di una clip caricata, oppure il massimo di 30 secondi per un URL video; l’eventuale differenza viene rilasciata al conguaglio.
| Specifiche | Prezzo |
|---|---|
| $0.064 / secondo |
| $0.12 / secondo |
Casi d’uso
Ricastare un'inquadratura che già funziona
La ripresa con luce, posizioni e movimento di macchina già approvati resta in piedi: cambi la testa invece di rigenerare tutta l'inquadratura e perdere l'interpretazione.
Qualsiasi soggetto, con un interprete consenziente
Qualunque cosa mostri il materiale, nella richiesta non cambia nulla. Nemmeno il requisito di autorizzazione descritto più sotto cambia: è una condizione rigida, non una formalità.
Una stessa persona in tutta una serie generata
Genera un lotto di clip con qualsiasi modello video, analizza ciascuna e porta la stessa testa autorizzata attraverso tutte, così che la serie si legga come una sola persona.
Folle in cui cambia una persona sola
Analizza una scena con più persone in quadro, guarda le anteprime e rimanda indietro solo la posizione che intendevi. Tutte le altre restano intatte.
Consigli avanzati
Verifica i diritti su ogni testa coinvolta
Sia il girato sia le foto di riferimento ritraggono persone. Ti serve l'autorizzazione per l'immagine che stai spostando e per il girato in cui la collochi. Conserva la liberatoria insieme al registro del lavoro.
Prima analizza, poi leggi l'ordine delle anteprime
L'analisi restituisce le anteprime in ordine fisso. La prima immagine è object_index 0, la seconda 1, e così via. Quella posizione è l'unico appiglio che ti serve: la rimandi indietro in swap_targets.
Tieni video e risoluzione identici
Entrambe le chiamate devono girare sullo stesso video alla stessa risoluzione. Se ometti video_url nella seconda, viene copiato dall'analisi; se lo mandi, deve coincidere. Una risoluzione diversa viene rifiutata, non ritracciata in silenzio.
Avvio rapido dell’API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/head-swap-video-v1/video-edit",
"input": {
"analysis_task_id": "example",
"resolution": "720p",
"swap_targets": [
{
"image_urls": [
"example"
],
"object_index": 0
}
]
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Nel riferimento dell’API trovi autenticazione, schema completo, polling e gestione degli errori.
