Sostituzione di persone

Alcuni modelli non generano una scena nuova: sostituiscono una persona. Un volto portato da una foto a un’altra, una testa intera oppure un’intera figura dentro una clip video. Il catalogo li raccoglie sotto un’unica etichetta, toolkit: "subject-swap", e si presentano in due forme: una chiamata oppure due chiamate con una scelta in mezzo.

Per il resto non hanno nulla di particolare. Sono normali attività asincrone, i loro parametri arrivano dal rispettivo inputSchema e i risultati compaiono in output.assets[].

toolkit ti dice che il modello è uno di questi

toolkit è un’etichetta di classificazione su una voce del catalogo ed è presente sia nella risposta autenticata di GET /api/v1/models sia nel catalogo pubblico. Oggi ha un solo valore, subject-swap, e nei modelli che non appartengono ad alcun toolkit il campo non c’è affatto: controlla quindi il valore, mai la presenza della chiave.

È un campo puramente informativo. Non decide quale chiave può chiamare un modello, come viene calcolato il prezzo della richiesta o che cosa il modello accetta. Un valore che non conosci va trattato come una voce sconosciuta di badges: ignoralo.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -r '.data.items[]
      | select(.toolkit == "subject-swap" and .enabled and .available)
      | [.model, (.tasks | join(",")), .family] | @tsv'

Ogni riga è un endpoint richiamabile. A decidere tutto il resto di questa pagina è la colonna tasks: una family che ha un endpoint video-analyze è una family a due chiamate, e l’endpoint video-edit che la accompagna non si può chiamare da solo.

Quale delle due forme ho davanti?

Entrambe le forme sono async: true: crei un’attività e poi recuperi il risultato con il polling o con un webhook.

Una chiamata

Qui non cambia nulla rispetto a qualsiasi altro modello di modifica. Leggi l’inputSchema dell’endpoint, compilalo, crea l’attività:

const created = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8814-swap-1',
  },
  body: JSON.stringify({
    model: swap.model, // una delle voci della query al catalogo qui sopra
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

I nomi dei campi cambiano da un endpoint all’altro: alcuni accettano un prompt, un seed o un formato di uscita, altri nient’altro che le due immagini. L’elenco valido è lo schema; non portare i nomi dei campi da un endpoint a un altro. Un riferimento può essere un URL HTTPS pubblico, una piccola immagine in Base64 scritta direttamente nella richiesta oppure un URI spicy:// già caricato; vedi File multimediali.

Due chiamate

La prima chiamata guarda la tua clip e riferisce che cosa ci ha trovato, sotto forma di una serie ordinata di fotogrammi di anteprima. Sei tu a decidere quali sostituire. Il lavoro vero e proprio lo fa la seconda chiamata.

la tua clip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (un fotogramma per soggetto)
                                          │
                      scegli le posizioni │ 0 e 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ la clip finita

Perché non in una sola chiamata? Perché in una scena con quattro persone una chiamata sola dovrebbe indovinare a chi ti riferivi, e un’ipotesi sbagliata è un video finito e addebitato in cui è stata sostituita la persona sbagliata. Dividere il lavoro rende la scelta esplicita e verificabile.

const analysis = await createTask({
  model: analyze.model, // la voce i cui tasks contengono "video-analyze"
  input: {
    video_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
    resolution: '720p',
  },
});
const analysisTaskId = analysis.taskId;

{
  "state": "succeeded",
  "output": {
    "assets": [
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" },
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" }
    ]
  },
  "settled": true
}

const swapped = await createTask({
  model: edit.model, // la voce "video-edit" della stessa family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // lo stesso valore con cui è girata l’analisi
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Che cosa verifica la seconda chiamata prima di accettare

Questi controlli avvengono alla creazione, quindi una richiesta rifiutata non crea nulla e non blocca nulla.

Quando la seconda chiamata viene rifiutata

Sono tutti HTTP 400 con codice di business code: 400. Il campo msg vale uno di questi:

Quanto costano le due chiamate

Analisi e sostituzione sono due attività distinte con due prezzi distinti, ciascuna bloccata e addebitata per conto proprio. Una seconda chiamata rifiutata non costa nulla; un’analisi riuscita viene addebitata anche se poi decidi di non sostituire niente.

• L’analisi di solito ha prezzo per_request: un addebito per chiamata, qualunque sia la durata della clip e quanti soggetti trovi.
• La sostituzione di solito ha prezzo per_second, a blocchi interi, e la durata arriva dalla clip e non da un campo che imposti tu. L’importo indicato prima dell’invio vale quindi per la clip più lunga che l’endpoint accetta: l’importo indicato è quello bloccato, l’addebito finale si calcola sulla durata arrotondata per eccesso e non supera mai il blocco, e la differenza torna sul tuo saldo quando l’attività viene chiusa. Vedere un blocco più alto dell’addebito finale, qui, è normale. Leggi Fatturazione prima di farci un budget.

Leggi entrambi i prezzi dal catalogo invece di darli per scontati e, se l’importo esatto conta, chiedi un preventivo per ciascuna chiamata.

Passi successivi