AI-Face-Swap-API-Workflow: autorisierte Uploads, asynchrone Jobs und zuverlässige Auslieferung

Referenzfotos und Farben vor dem Tausch vergleichen.

Face Swap auf SpicyAPI ist eine Familie unzensierter Endpunkte, die zwei Bilder (oder ein Bild und einen Clip), keinen Prompt und keine Maske erwarten. Dieser Leitfaden zeigt, welchen Endpunkt Sie aufrufen, wie Sie es zuerst im Playground und dann aus dem Code oder über einen Agenten ausprobieren, was Sie in der Ausgabe prüfen und wie Sie das Ergebnis behalten, nachdem die Plattform es gelöscht hat.

Den passenden Endpunkt wählen

Beginnen Sie mit Face Swap für $0.013. Wechseln Sie zu Pro, wenn das getauschte Gesicht glatter oder schärfer wirkt als der Rest des Bildes, und zu Plus, wenn die beiden Fotos deutlich unterschiedliche Hauttöne oder Lichtfarben haben. 200 Avatar-Varianten kosten $2.60 mit Face Swap und $32 mit Pro, testen Sie Ihr schwierigstes Paar also auf beiden. Plus hat ein prompt-Feld, das keine Wirkung hat, lassen Sie es weg und setzen Sie stattdessen eine Brille oder einen Ausdruck in das Zielfoto.

Video Face Swap rechnet den Quellclip in vollen 10-Sekunden-Blöcken ab, ein 12-Sekunden-Clip kostet daher 20 Sekunden ($0.52) und ein 40-Sekunden-Clip $1.04. Beim Absenden wird die 40-Sekunden-Schätzung ($1.04) reserviert und die Differenz freigegeben, wenn die Task abgerechnet wird. Schneiden Sie vor dem Absenden auf eine Blockgrenze zu.

Was die Endpunkte mit echten Gesichtern machen

Diese Endpunkte sind als unzensiert gelistet: SpicyAPI fügt weder eine Gesichtserkennung pro Anfrage noch eine Realperson-Prüfung hinzu. Fehlschläge liegen meist an der Eingabe (kein erkennbares Gesicht, eine nicht erreichbare Datei), ein einzelnes Modell kann eine Anfrage aber weiterhin ablehnen. Die Acceptable-Use-Richtlinie verbietet Identitätsvortäuschung, nicht einverstandene intime oder sexualisierte Nutzung der Ähnlichkeit einer realen Person sowie alles, was Minderjährige betrifft; nach einer Meldung kann SpicyAPI gespeicherte Assets entfernen und den Zugang sperren. Ein öffentliches Foto oder eine frühere Beziehung ist keine Einwilligung. Die Einwilligungsakte liegt bei Ihnen, und sie gehört vor den Upload-Button:

• Der angemeldete Nutzer bestätigt, dass er für beide Bilder und für diese Nutzung die Erlaubnis der abgebildeten Person hat; speichern Sie die Bestätigung beim Projekt (wer, welches Asset, welche Nutzung, wann).
• Keine Bilder von Minderjährigen und keine Nutzung, die eine reale Person täuscht, indem sie sie nachahmt.

Bewahren Sie das als Produktunterlagen auf, nicht in Prompts, Analyse-Ereignissen oder Logs.

Eingaben vorbereiten, die nicht fehlschlagen

Es gibt keine Stärke-Einstellung zum Optimieren, ein schlechtes Ergebnis bedeutet also ein anderes Eingabepaar.

• Frontale, große, scharfe Gesichter. Starke Profilwinkel, Bewegungsunschärfe, dichte Verdeckung (Hände, Masken, große Sonnenbrillen) und sehr kleine Gesichter verschlechtern die Übertragung oder lassen die Anfrage scheitern. Ein großes, scharfes, frontales Referenzgesicht liefert das beste Ergebnis.
• Gleiche Lichtrichtung. Der Tausch beleuchtet das Ziel nicht neu, eine von der anderen Seite beleuchtete Referenz zeigt sich deshalb als Naht an der Kieferlinie. Passen Sie Richtung und ungefähren Hautton an oder wählen Sie eine andere Referenz. Plus gleicht nur den Hautton ab, es behebt keine Abweichung der Lichtrichtung.
• Ein Gesicht pro Bild. Bei Gruppenaufnahmen akzeptieren Face Swap und Video Face Swap face_mapping: bis zu 10 Einträge, jeder paart ein Referenzgesicht mit einem Zielgesicht, nummeriert ab 0 in Erkennungsreihenfolge. Prüfen Sie die Nummerierung jedes Mal neu, wenn Sie ein Bild ändern. Plus und Pro gehen von einem Gesicht aus, schneiden Sie zuerst zu.

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

Das tauscht Referenzgesicht 0 auf das zweite im Ziel gefundene Gesicht. Lassen Sie das Feld weg, um ein einzelnes Gesicht zu tauschen.

• Direkte Dateilinks. Bild-URLs müssen ohne Anmeldung auf die Datei auflösen. Bei Video liefert eine Seite, die den Clip abspielt, HTML statt eines Clips, und der Aufruf scheitert mit erstatteter Gebühr; laden Sie stattdessen die Datei hoch.
• Die Rollen sind nicht austauschbar. image_url ist das Bild, das verändert wird; reference_image_url liefert das Gesicht. Vertauschen Sie beide, ist das eine gültige Anfrage mit einem anderen Ergebnis und ohne Fehlermeldung, ein falsch herum getauschter Tausch sieht also wie ein Modellfehler aus.

Grenzen für Video: MP4 bis 90 MB und 3 bis 40 Sekunden, Referenzbild JPG, PNG oder WEBP bis 10 MB. Halten Sie das Gesicht groß im Bild und nicht lange abgewandt. Der Endpunkt funktioniert am besten mit einer Person im Bild; für einen Clip mit mehreren Personen ergänzen Sie face_mapping (gleiche Form wie oben, in Erkennungsreihenfolge nummeriert) oder schneiden Sie auf die Person zu.

Zuerst im Playground ausprobieren

Öffnen Sie die Face-Swap-Task-Seite und nutzen Sie den Tab Playground (konfigurieren, schätzen, ausführen). Geben Sie das Zielbild und das Referenzgesicht ein, prüfen Sie die Preisschätzung für Ihre Einstellungen und starten Sie den Lauf. Probieren Sie Ihr schwierigstes Paar hier, bevor Sie Code schreiben: Ist das Ergebnis im Playground falsch, ist es über die API falsch, und die Abhilfe ist ein anderes Eingabepaar. Head Swap hat denselben Tab für Kopftausche.

Dann aus dem Code aufrufen

Installieren Sie das Python SDK (pip install spicyapi), setzen Sie SPICY_API_KEY in der Umgebung und führen Sie aus:

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

Führen Sie einen Prozess pro Job-Datei aus. Läuft das Warten in einen Timeout, starten Sie mit derselben Datei neu, um die gespeicherte Task fortzusetzen. Lief bereits das Absenden in einen Timeout, bevor eine ID zurückkam, behalten Sie die Datei und gleichen Sie diese Anfrage ab, bevor Sie es erneut versuchen; der Idempotenzschutz ist nicht dauerhaft. Verwenden Sie einen neuen Job-Dateinamen nur, wenn Sie eine neue kostenpflichtige Anfrage beabsichtigen.

Uploads, Warten, Fehler und Wiederholungen stehen im Leitfaden zu Subject Swap und in der Python-SDK-Referenz. Video Face Swap nutzt spicyapi/face-swap-video-v1/video-edit mit video_url und reference_image_url.

Oder einen Agenten die Arbeit erledigen lassen

Wenn ein Assistent die Tausche für Sie ausführen soll, geben Sie ihm die CLI oder den MCP-Server. Beide zeigen den Preis und fragen vor einem kostenpflichtigen Aufruf nach Bestätigung. Der Skill ergänzt Anweisungen für beides.

• CLI. spicyapi führt eine Aufgabe aus einem Terminal oder Skript aus (npx @spicyapi/cli funktioniert ohne Installation):

``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 enthält dasselbe input-Objekt wie oben, mit den spicy://-URIs. Dieser Block startet einen neuen Job. Behalten Sie den gedruckten Key und die Task-ID; nach einem Timeout setzen Sie diese Task fort, statt den Block mit neuem Key erneut zu starten.

• MCP-Server. Fügen Sie Ihrem Assistenten den MCP-Server hinzu und fragen Sie dann: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Er ruft spicyapi_upload_file, dann spicyapi_task_create (das für Ihre Preisbestätigung anhält), dann 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 installiert den Agent Skill, der einen Coding-Assistenten das aktuelle Schema lesen lässt, Idempotenzschlüssel wiederverwendet und Ergebnisse speichert, statt zu raten. Er kann keine Aufgaben selbst ausführen, verwenden Sie ihn also zusammen mit CLI oder MCP.

Die Einwilligungsakte und das Kopieren der Ergebnisse in Ihren eigenen Speicher gelten für die Aufrufe eines Agenten genauso wie für Ihre eigenen.

Prüfen, bevor Sie es erledigt nennen

succeeded bedeutet, dass die Generierung abgeschlossen ist. Prüfen Sie vor dem Download, ob das Asset eine nutzbare URL hat und weder pending noch unavailable wahr ist; solange pending wahr ist oder die URL fehlt, fragen Sie dieselbe Task weiter ab. Auslieferungsbereitschaft bedeutet trotzdem nicht, dass das Bild freigegeben ist. Prüfen Sie bei Video Schnitte und schnelle Bewegungen, nicht nur das erste Bild. Ein Ähnlichkeitswert ist ein Diagnosesignal, keine Einwilligung und keine Freigabe zur Veröffentlichung.

Zwei Prüfungen, die ändern, was Sie als Nächstes tun:

• Das Haar gehört zum Design (eine Spielefigur, ein Maskottchen). Face Swap behält die Frisur des Ziels, das neue Gesicht sitzt also unter dem alten Haar. Nutzen Sie stattdessen Head Swap mit einem festen Charakter-Tafelbild als Referenz und vergleichen Sie jede Ausgabe mit der Tafel: Ein driftendes Gesicht auf einer stabilen Komposition ist ein Identitätsproblem, das Umgekehrte ein Bildaufbauproblem, und ein erneuter Versuch behebt nur eines der beiden.
• Ein Porträt über mehrere Layouts. Führen Sie Face Swap einmal pro Layout mit derselben Referenz und demselben seed aus. Akzeptieren Sie eine Ausgabe, wenn das Gesicht auf dem veröffentlichten Beschnitt erkennbar bleibt, Brille und Haaransatz nicht gedriftet sind und keine zusätzlichen Personen auftauchen; bewahren Sie Referenzrevision, Zielrevision und Task-ID zusammen damit auf.

Ausliefern: kopieren Sie das Ergebnis selbst

Hochgeladene Quellen werden nach einem Tag gelöscht, Ergebnisse nach spätestens 14 Tagen (retention.outputsExpireAt enthält die genaue Zeit). Laden Sie das Ergebnis herunter und speichern Sie es selbst; der Ergebnis-Link hält etwa 20 Minuten. Siehe den Aufbewahrungs-Leitfaden.

Wenn es schiefgeht

FAQ

Verweigert die API das Gesicht einer realen Person?

SpicyAPI prüft nicht: Es gibt keine Realperson-Prüfung und keinen Scan pro Anfrage, und Fehlschläge liegen meist an der Eingabe. Ein einzelnes Modell kann weiterhin ablehnen, und die Acceptable-Use-Richtlinie verbietet Identitätsvortäuschung, nicht einverstandene intime Nutzung und Minderjährige. Erstellen Sie die Erlaubnisakte selbst.

Kann ich Video und Bild in einem Aufruf senden?

Ja, bei Video Face Swap: ein MP4 und ein Referenzfoto. Für mehrere Personen in einem Clip nutzen Sie dort face_mapping oder den zweistufigen Video-Head-Swap-Ablauf, wenn Sie ganze Köpfe brauchen.

Gehostete API oder selbst gehosteter Open-Source-Tausch?

Der gehostete Endpunkt kostet $0.013 pro Bild und nimmt Ihnen GPU-Bereitstellung und Modellwartung ab. Selbsthosting ersetzt die Gebühren pro Bild durch GPU- und Betriebskosten; ob das günstiger ist, hängt von Durchsatz und Auslastung ab. Ein hohes, gleichmäßiges Volumen kann diese Kosten auf mehr Bilder verteilen, die Einwilligungs- und Aufbewahrungskontrollen müssen Sie aber weiterhin unterhalten.

Ist das dasselbe wie eine allgemeine Bildbearbeitungs-API?

Nein. Ein Tausch-Endpunkt erwartet zwei Bilder (oder ein Bild und einen Clip), keinen Prompt und keine Maske, und jeder Endpunkt entscheidet, was vom Ziel erhalten bleibt: Face Swap behält das Haar, Head Swap ersetzt es. Dasselbe Eingabepaar kann bei jedem anders durch die Prüfung fallen, wählen Sie also zuerst den Endpunkt.

Sollte ich die Originalporträts beim Output behalten?

Nur wenn Sie einen klaren Grund und eine offengelegte Aufbewahrungsrichtlinie haben. Hochgeladene Quellen werden bei SpicyAPI ohnehin nach einem Tag gelöscht, bewahren Sie also Referenz- und Ziel-Revision-IDs sowie die Task-ID als Herkunftsnachweis auf statt einer dauerhaften Kopie jedes Porträts.

Brauche ich Webhooks oder reicht Polling?

Polling allein funktioniert und ist der Wiederherstellungsweg: alle paar Sekunden lesen oder für kurze Bild-Tausche wait (bis zu 60 s) beim createTask ergänzen. Fügen Sie einen Webhook für geringere Latenz hinzu, speichern Sie jedes Ereignis einmal und behandeln Sie Polling als Abgleich für verpasste Callbacks.

Was Sie beantworten können müssen

Eine Face-Swap-Funktion verdient Vertrauen, wenn Ihr Team sagen kann, wessen Bilder verwendet wurden, welche Revisionen hineingingen, ob die Task einmal angenommen wurde, warum ein Ergebnis geliefert wurde und wie es entfernt wird. Einwilligungsakten, Idempotenzschlüssel, Ihr eigener Speicher und ein Prüfschritt erzeugen diese Antworten.