Workflow API di face swap con IA: caricamenti autorizzati, job asincroni e consegna affidabile

Confrontare foto di riferimento e colore prima dello scambio.

Su SpicyAPI il Face Swap è una famiglia di endpoint senza censura che ricevono due immagini (o un'immagine e un clip), nessun prompt e nessuna maschera. Questa guida spiega quale endpoint chiamare, come provarlo prima nel Playground e poi dal codice o con un agent, cosa controllare nell'output e come conservare il risultato dopo che la piattaforma lo ha eliminato.

Scegli l'endpoint giusto per il lavoro

Parti da Face Swap a $0.013. Passa a Pro quando il volto scambiato appare più liscio o più nitido rispetto al resto dell'inquadratura, e a Plus quando le due foto hanno toni di pelle o colori di luce nettamente diversi. 200 varianti di avatar costano $2.60 con Face Swap e $32 con Pro, quindi prova la coppia più difficile su entrambe. Plus ha un campo prompt che non ha alcun effetto, lascialo fuori e metti invece occhiali o espressione nella foto di destinazione.

Video Face Swap fattura il clip di origine a blocchi interi da 10 secondi, così un clip da 12 secondi viene fatturato come 20 secondi ($0.52) e un clip da 40 secondi come $1.04. All'invio viene trattenuta la stima di 40 secondi ($1.04) e la differenza viene rilasciata quando il job viene fatturato. Taglia fino al limite di un blocco prima di inviare.

Cosa fanno gli endpoint con i volti reali

Questi endpoint sono elencati come senza censura: SpicyAPI non aggiunge alcuna scansione del volto per richiesta né controlli su persone reali. I fallimenti riguardano di solito l'input (nessun volto rilevabile, un file non raggiungibile), anche se un singolo modello può comunque rifiutare una richiesta. L'Informativa sull'uso accettabile vieta l'appropriazione di identità, l'uso intimo o sessualizzato senza consenso dell'aspetto di una persona reale e qualsiasi cosa che riguardi minori; dopo una segnalazione SpicyAPI può rimuovere gli asset memorizzati e sospendere l'accesso. Una foto pubblica o una relazione pregressa non sono consenso. Il registro dei consensi spetta a te e va tenuto prima del pulsante di caricamento:

• L'utente che ha effettuato l'accesso conferma di avere il permesso della persona ritratta sia per le due immagini sia per questo uso; conserva la conferma insieme al progetto (chi, quale asset, quale uso, quando).
• Nessuna immagine di minori e nessun uso che imiti una persona reale per ingannare.

Conserva questi dati come documentazione di prodotto, non nei prompt, negli eventi di analisi o nei log.

Preparare input che non falliranno

Non c'è alcun parametro di intensità da regolare, quindi un risultato scarso significa una coppia di input diversa.

• Volti frontali, grandi e nitidi. Angoli di profilo marcati, sfocatura da movimento, occlusione fitta (mani, maschere, grandi occhiali da sole) e volti molto piccoli degradano il trasferimento o fanno fallire la richiesta. Un volto di riferimento grande, nitido e frontale dà il risultato migliore.
• Stessa direzione di luce. Lo scambio non rillumina la destinazione, quindi un riferimento illuminato dal lato opposto mostra una cucitura sulla linea della mascella. Fai corrispondere la direzione e tonalità di pelle approssimativa, oppure scegli un altro riferimento. Plus uniforma solo la tonalità di pelle; non corregge uno scostamento della direzione di luce.
• Un volto per immagine. Per le foto di gruppo, Face Swap e Video Face Swap accettano face_mapping: fino a 10 voci, ciascuna che abbina un volto di riferimento a un volto di destinazione, numerati da 0 in ordine di rilevamento. Ricontrolla la numerazione ogni volta che modifichi un'immagine. Plus e Pro presumono un solo volto; ritaglia prima.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

Questo scambia il volto di riferimento 0 sul secondo volto trovato nella destinazione. Ometti il campo per scambiare un solo volto.

• Link diretti ai file. Gli URL delle immagini devono raggiungere il file senza richiedere un login. Per i video, una pagina che riproduce il clip restituisce HTML anziché un clip e la chiamata fallisce con il rimborso dell'addebito; carica invece il file.
• I ruoli non sono intercambiabili. image_url è l'immagine che viene modificata; reference_image_url fornisce il volto. Scambiarli produce una richiesta valida con un risultato diverso e senza alcun errore, quindi uno scambio al contrario sembra un bug del modello.

Limiti per i video: MP4 fino a 90 MB e da 3 a 40 secondi, immagine di riferimento JPG, PNG o WEBP fino a 10 MB. Tieni il volto grande nell'inquadratura e non girato di spalle a lungo. L'endpoint funziona meglio con una sola persona in scena; per un clip con più persone aggiungi face_mapping (stessa forma di sopra, numerato in ordine di rilevamento) oppure ritaglia sulla persona.

Provalo prima nel Playground

Apri la pagina del task Face Swap e usa la scheda Playground (configura, stima, esegui). Inserisci l'immagine di destinazione e l'immagine del volto di riferimento, controlla la stima di prezzo per le tue impostazioni ed esegui. Prova qui la coppia più difficile prima di scrivere codice: se il risultato è sbagliato nel Playground, sarà sbagliato anche tramite API, e la correzione è una coppia di input diversa. Head Swap ha la stessa scheda per gli scambi di testa intera.

Poi chiamalo dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY nell'ambiente ed esegui:

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
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 {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

Esegui un processo per file di job. Se l'attesa scade, riavvia con lo stesso file per riprendere il job salvato. Se è stato l'invio stesso a scadere prima di restituire un ID, conserva il file e riconcilia quella richiesta prima di riprovare; la protezione di idempotenza non è permanente. Usa un nuovo nome di file di job solo quando intendi una nuova richiesta a pagamento.

Caricamenti, attesa, errori e nuovi tentativi sono descritti nella guida di Subject Swap e nel riferimento dell'SDK Python. Video Face Swap usa spicyapi/face-swap-video-v1/video-edit con video_url e reference_image_url.

Oppure fai eseguire il lavoro a un agent

Se un assistente deve eseguire gli scambi al posto tuo, dagli la CLI o il server MCP. Entrambi mostrano il prezzo e ti chiedono conferma prima di una chiamata a pagamento. La Skill aggiunge istruzioni a entrambi.

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

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json contiene lo stesso oggetto input di sopra, con gli URI spicy://. Questo blocco avvia un nuovo job. Conserva la chiave e l'ID del task stampati; dopo un timeout, riprendi quel task invece di rieseguire il blocco con una chiave nuova.

• Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Chiama spicyapi_upload_file, poi spicyapi_task_create (che si ferma per la tua conferma del prezzo) e poi spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che insegna a un assistente di programmazione a leggere lo schema attivo, a riutilizzare le chiavi di idempotenza e a salvare i risultati invece di indovinare. Non può eseguire i task da solo, quindi usalo insieme alla CLI o a MCP.

Il registro dei consensi e la copia dei risultati nel tuo storage valgono per le chiamate di un agent esattamente quanto per le tue.

Controlla prima di dare per finito

succeeded significa che la generazione è terminata. Prima del download, verifica che l'asset abbia un URL utilizzabile e che né pending né unavailable siano veri; finché pending è vero o l'URL manca, continua a interrogare lo stesso job. La disponibilità alla consegna non significa comunque che l'immagine sia approvata. Per i video, controlla i tagli e i movimenti rapidi, non solo il primo fotogramma. Un punteggio di similarità è un segnale diagnostico, non un consenso né un'approvazione alla pubblicazione.

Due controlli che cambiano cosa fai dopo:

• I capelli fanno parte del design (un personaggio di gioco, una mascotte). Face Swap mantiene la pettinatura della destinazione, quindi il nuovo volto finisce sotto i capelli vecchi. Usa invece Head Swap, con un'immagine fissa della scheda del personaggio come riferimento, e confronta ogni output con la scheda: un volto che deriva su una composizione stabile è un problema di identità, il contrario è un problema di inquadratura, e un nuovo tentativo ne risolve solo uno dei due.
• Un ritratto su più layout. Esegui Face Swap una volta per layout con lo stesso riferimento e lo stesso seed. Accetta un output quando il volto è riconoscibile rispetto al ritratto nel ritaglio che pubblicherai, quando occhiali e linea dell'attaccatura dei capelli non hanno derivato e quando non compaiono persone extra; conserva insieme la revisione del riferimento, la revisione della destinazione e l'ID del task.

Consegna: copia il risultato da solo

I file sorgente caricati vengono eliminati dopo un giorno e i risultati dopo al massimo 14 giorni (retention.outputsExpireAt contiene l'orario esatto). Scarica il risultato e conservalo tu stesso; il link del risultato dura circa 20 minuti. Vedi la guida sulla conservazione.

Quando qualcosa va storto

FAQ

L'API rifiuterà il volto di una persona reale?

SpicyAPI non controlla: non c'è alcun controllo su persone reali né scansione per richiesta, e i fallimenti riguardano di solito l'input. Un singolo modello può comunque rifiutare, e l'Informativa sull'uso accettabile vieta l'appropriazione di identità, l'uso intimo senza consenso e i minori. Costruisci tu stesso il registro delle autorizzazioni.

Posso inviare un video e un'immagine in una sola chiamata?

Sì, con Video Face Swap: un MP4 e una foto di riferimento. Per più persone in un clip usa lì face_mapping, oppure il flusso Video Head Swap in due passaggi quando ti servono intere teste.

API ospitata o scambio open source ospitato da te?

L'endpoint ospitato costa $0.013 per immagine e ti evita il provisioning delle GPU e la manutenzione dei modelli. L'hosting autonomo sostituisce le tariffe per immagine con costi di GPU e di gestione; se sia più conveniente dipende dal volume e dall'utilizzo. Un volume alto e costante può distribuire questi costi su più immagini, ma devi comunque mantenere i controlli su consenso e conservazione.

È la stessa cosa di un'API generale di modifica delle immagini?

No. Un endpoint di scambio riceve due immagini (o un'immagine e un clip), nessun prompt e nessuna maschera, e ogni endpoint decide cosa resta della destinazione: Face Swap mantiene i capelli, Head Swap li sostituisce. La stessa coppia di input può superare la revisione in modo diverso su ciascuno, quindi scegli prima l'endpoint.

Devo conservare i ritratti originali insieme all'output?

Solo se hai una ragione chiara e una politica di conservazione dichiarata. I file sorgente caricati su SpicyAPI vengono comunque eliminati dopo un giorno, quindi conserva invece gli ID di revisione del riferimento e della destinazione e l'ID del task come tracciabilità, anziché una copia permanente di ogni ritratto.

Mi servono webhook o basta il polling?

Il polling da solo funziona ed è il percorso di recupero: leggi ogni pochi secondi, oppure aggiungi wait (fino a 60 s) a createTask per gli scambi di immagine brevi. Aggiungi un webhook per una latenza inferiore, salva ogni evento una sola volta e considera il polling come la riconciliazione delle callback perse.

Cosa devi saper rispondere

Una funzione di face swap si guadagna la fiducia quando il tuo team sa dire quali immagini sono state usate, quali revisioni sono entrate, se il job è stato accettato una sola volta, perché è stato consegnato un risultato e come viene rimosso. I registri dei consensi, le chiavi di idempotenza, il tuo storage e un passaggio di revisione sono ciò che produce queste risposte.