Introduzione
Video Head Swap Analysis legge una clip e restituisce un fermo immagine di anteprima per ogni testa che riesce a seguire, in ordine fisso: la prima immagine è la posizione 0, la seconda la posizione 1, e così via. Sono queste posizioni che riceve la chiamata di sostituzione: guardi le immagini e rimandi indietro i numeri.
Qui non viene generato niente e la clip non viene modificata. Questa chiamata produce l'elenco di bersagli su cui lavora la chiamata di sostituzione ed è l'unico modo per sapere quante teste ci sono in un'inquadratura e quale è quale.
Caratteristiche principali
Scegli dalle immagini, non dalle coordinate
La maggior parte degli endpoint di sostituzione ti fa descrivere chi intendevi, oppure tira a indovinare. Qui l'analisi ti consegna i candidati come immagini numerate. L'ambiguità su chi viene sostituito si risolve prima che venga generato qualcosa, cioè nel momento in cui sbagliare non costa ancora niente.
Un'analisi sola serve più sostituzioni
Il risultato resta utilizzabile per 24 ore. Provi una persona, guardi come viene, poi mandi un altro gruppo di foto di riferimento sulla stessa analisi: l'analisi la paghi una volta sola. Dopo 24 ore i riferimenti scadono e la clip va analizzata di nuovo.
Legge il girato così com'è stato ripreso
Il tracciamento segue ogni testa attraverso stacchi, giri di testa e occlusioni parziali. Sono accettate clip da 5 a 30 secondi e l'analisi riporta ogni testa che riesce a tenere per tutta la durata dell'inquadratura, non solo quella in primo piano.
Parametri della richiesta
| Parametro | Obbligatorio | Nota |
|---|---|---|
video_url | Sì | La clip da analizzare, da 5 a 30 secondi. almeno 1 caratteri |
resolution | No | Risoluzione di tracciamento. La chiamata di sostituzione deve usare lo stesso valore, quindi scegli la risoluzione che deve avere la clip finita. |
Prezzi
$0.08 / analisi
L’analisi e la sostituzione si pagano separatamente.
Casi d’uso
Controllare una clip prima di pagare per sostituirla
La chiamata di sostituzione costa più dell'analisi. Analizzare prima ti dice se le teste che ti interessano sono davvero tracciabili in questo girato: sfocature pesanti, occlusioni lunghe e soggetti che escono dall'inquadratura si vedono come un'anteprima mancante o instabile.
Prendere una persona sola in mezzo alla folla
Analizza una scena con più persone in campo, leggi le anteprime e rimanda indietro solo la posizione che intendevi. La sostituzione lascia intatte tutte le altre.
Tenere lo stesso cast per tutta una serie
Genera un blocco di clip con un modello video qualsiasi, analizzale una per una e usa le anteprime per allineare lo stesso bersaglio in ogni inquadratura, così la serie si legge come una cosa sola.
Qualsiasi soggetto, con un interprete consenziente
Qualunque cosa mostri il materiale, nella richiesta non cambia niente. Non cambia nemmeno il requisito di autorizzazione nei limiti qui sotto: è una condizione vincolante, non una classificazione del contenuto.
Consigli avanzati
Usa la stessa risoluzione nelle due chiamate
Scegli la risoluzione che deve avere la clip finita e usala anche qui: la chiamata di sostituzione dovrà girare allo stesso valore. Non cambia quello che questa chiamata rileva, ma solo l'inquadratura in cui lavora la sostituzione.
Leggi l'ordine delle anteprime, non darlo per scontato
Le immagini tornano in ordine, ma l'ordine viene dal tracciamento, non dal posto sullo schermo né da quanto una persona sia in evidenza. La persona più a sinistra non è per forza la posizione 0. Guarda le immagini.
Manda lo stesso video a tutte e due le chiamate
La chiamata di sostituzione vuole la clip identica: stesso file, stessa codifica. Ometti video_url nella richiesta di sostituzione e viene ripreso dall'analisi, che è il modo più sicuro per garantire che coincidano.
Rianalizza se il girato cambia
Ricodificare, tagliare o riesportare la clip invalida l'analisi: le posizioni non puntano più alle stesse teste. Analizza il file che sostituirai davvero.
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-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# 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.
