Einführung
Das Modell überträgt ein Gesicht aus einem Bild auf die Person in einem anderen und gleicht dabei den Hautton zwischen beiden an. Wie viel übertragen wird, entscheidet die Engine: Sie blendet entweder nur das Gesicht oder den ganzen Kopf ein, je nachdem, was bei diesem Paar natürlicher wirkt – der Haaransatz bleibt also nicht immer unberührt. Pose, Kleidung, Licht und Hintergrund des Zielbilds bleiben, wie sie waren.
Face Swap Plus ist die steuerbare Stufe der Face-Swap-Reihe. Zusätzlich zu den beiden Bildern nimmt es eine kurze schriftliche Anweisung, ein Ausgabeformat und einen Seed entgegen und wird an spicyapi/face-swap-v1-plus/edit gesendet. Der Aufruf ist asynchron: Er liefert eine Task-ID, Sie fragen diese Task ab, und pro Anfrage kommt ein Bild zurück, abgerechnet je Ausgabebild – unabhängig vom gewählten Format.
Wichtige Funktionen und Highlights
Der Hautton wird für Sie angeglichen
Am häufigsten verrät sich ein Gesichtstausch an der Grenze: Eine Referenz unter warmem Licht in einem kühl beleuchteten Zielbild hinterlässt einen Ring um den Kiefer und einen Hals, der nicht mehr zum Kopf passt. Diese Engine gleicht den Ton zwischen beiden Fotos beim Tausch an, sodass ein Paar, das nah beieinander, aber nicht identisch ist, meist ohne nachträgliche Farbkorrektur passt. Die Lichtrichtung wird dadurch nicht egal – ein von der anderen Seite beleuchtetes Gesicht wirkt weiterhin falsch –, aber der häufigste Widerspruch ist Ihnen abgenommen.
Die Blendtiefe wird pro Paar entschieden
Das ist ein intelligenter Kopftausch: Für jedes Paar beurteilt die Engine, ob nur das Gesicht oder der ganze Kopf natürlicher wirkt, und es gibt keine Einstellung, die das eine oder andere erzwingt. Darin liegt der praktische Unterschied zum Rest der Reihe, bei dem der Haaransatz immer beim Zielbild bleibt. Deshalb kann ein Ergebnis auch mit einem etwas anderen Haaransatz zurückkommen als erwartet – die Engine hat die vollere Einblendung für die glaubwürdigere Option gehalten.
Request-Parameter
| Parameter | Pflicht | Beschreibung |
|---|---|---|
image_url | Ja | Das Bild, das verändert wird. mindestens 1 Zeichen |
reference_image_url | Ja | Das Bild, das die Gesichtszüge liefert. mindestens 1 Zeichen |
prompt | Nein | Optional – bauen Sie aber so, als gäbe es das Feld nicht. höchstens 200 Zeichen |
output_format | Nein | Das Dateiformat des zurückgegebenen Bildes. |
output_quality | Nein | Angeforderte Bildqualität des Ergebnisses, von 10 bis 100 (Standard 95). Am Preis ändert es nichts. |
seed | Nein | Verwenden Sie denselben Seed erneut, um zwei Läufe über dasselbe Bildpaar gegen eine identische Ziehung zu vergleichen, sodass sich nur das eine Geänderte bewegt. |
Preis
$0.16 / Bild
Anwendungsfälle
Avatar- und Profilbild-Pipelines in großer Menge
Eine Liste aus Ziel-Referenz-Paaren läuft programmatisch durch den Endpunkt, ein Aufruf pro Paar. Fixieren Sie den Seed pro Paar, wenn ein neuer Versuch mit dem ersten Lauf vergleichbar bleiben muss, und wählen Sie WebP, wenn die Ergebnisse direkt ins Web gehen.
Endkundenfunktionen hinter einem Upload-Formular
Die Interaktion besteht aus einem Foto der Nutzerin oder des Nutzers und einem Bild, das Sie bereitstellen. Es gibt nichts einzustellen und keinen Prompt zu schreiben – die ganze Funktion ist ein Formularfeld und ein Hintergrundjob.
Katalog- und Vorlagenarbeit
Ein Referenzgesicht über eine Reihe vorbereiteter Bilder ergibt eine stimmige Serie, ohne dass eines davon neu erzeugt wird. Die Formateinstellung liefert die Dateien in der Form, die Ihre Pipeline bereits erwartet; ein Accessoire, das eine Vorlage braucht, muss schon vor dem Tausch im Bild sein.
Unzensierte Motive: Die Grenze ist die Einwilligung, nicht das Thema
SpicyAPI setzt keinen eigenen Inhaltsfilter ein und verlangt kein Reife-Flag; der Request-Body enthält immer dieselben Felder, egal was das Bild zeigt. Nicht gelockert wird die Berechtigung: Sie brauchen die ausdrückliche, informierte Einwilligung der dargestellten Person für genau dieses Gesicht in genau diesem Material, und eine Einwilligung ergibt sich nie daraus, dass ein Foto öffentlich ist.
Prompt-Leitfaden und Praxistipps
Das Anweisungsfeld bewirkt hier nichts
prompt wird vom zugrunde liegenden Modell angenommen und ist auf 200 Zeichen begrenzt, aber wir konnten damit keine Änderung erreichen.
| Was wir gesendet haben | Was zurückkam |
|---|---|
add mirrored aviator sunglasses | Keine Sonnenbrille; identisch mit einer leeren Anfrage |
wearing black sunglasses | Keine Sonnenbrille; identisch mit einer leeren Anfrage |
restyle the hair into a sleek straight bob | Haare unverändert |
soften the expression into a faint half smile | Ausdruck unverändert |
a wide open-mouthed laugh | Ausdruck unverändert |
Fünf echte Aufrufe am 20.09.2026, jeweils verglichen mit derselben Anfrage ohne das Feld. Es gibt weder Fehler noch Warnung, die Antwort verrät also nicht, dass der Wert ignoriert wurde. Planen Sie ohne dieses Feld – brauchen Sie ein Accessoire oder einen anderen Ausdruck, bringen Sie ihn vor dem Tausch ins Zielbild.
Was die Engine für Sie entscheidet
Zwei Läufe über diesen Endpunkt kamen mit gegensätzlichen Entscheidungen zurück; so sieht man es am deutlichsten:
| Zielbild | Was übertragen wurde |
|---|---|
| Ein straffer schwarzer Pferdeschwanz | Der ganze Kopf – die roten Haare der Referenz kamen mit den Zügen mit |
| Nass zurückgekämmtes Haar | Nur das Gesicht – die Haare des Zielbilds blieben genau wie aufgenommen |
Wenn Sie ein Accessoire oder einen anderen Ausdruck brauchen
Mit dem Anweisungsfeld kommen Sie nicht dorthin; die Änderung muss also vor dem Tausch existieren:
| Was Sie wollten | Wo Sie es stattdessen umsetzen |
|---|---|
| Sonnenbrille, Hut, Schmuck | Der Person im Zielbild anlegen, bevor Sie diesen Endpunkt aufrufen |
| Ein anderer Ausdruck oder eine andere Frisur | Das Zielbild so fotografieren oder erzeugen; der Tausch behält beides |
Ausgabeformat und Seed wählen
Setzen Sie output_format, wenn der Dateityp später zählt, denn eine nachträgliche Umwandlung kostet eine erneute Kodierung: PNG für eine verlustfreie Datei, die weiterbearbeitet wird, WebP für Ergebnisse, die direkt ins Web gehen, JPEG, wenn Sie nichts angeben. Keins der drei ändert den Preis, wählen Sie also das Format, das Ihre Pipeline braucht, nicht das vermeintlich günstigere. Fixieren Sie seed nur, wenn Sie Läufe vergleichen wollen: Zwei Läufe über dasselbe Paar bekommen dieselbe Ziehung, sodass sich nur die eine geänderte Variable bewegt. Der Seed ist ein Vergleichswerkzeug, kein Versprechen eines byte-identischen Bildes. In der Produktion ist eine frische Ziehung pro Aufruf meist das Richtige.
Wenn das Ergebnis nicht passt
| Was Sie sehen | Was Sie zuerst ändern |
|---|---|
| Eine Naht am Kiefer trotz Tonangleich | Eine Referenz mit Licht aus derselben Richtung nehmen – der Ton wird angeglichen, die Richtung nicht |
| Der Haaransatz hat sich verändert, sollte aber bleiben | Hier erwartbar; nehmen Sie Face Swap oder Face Swap Pro |
| Die Anweisung hatte keine sichtbare Wirkung | Erwartbar – das Feld wirkt hier nicht; ändern Sie stattdessen das Zielbild |
| Die falsche Person wurde verändert | Das Zielbild auf eine Person zuschneiden |
| Die Züge wirken weich oder ungefähr | Eine Referenz mit größerem, schärferem Gesicht nehmen |
Den passenden Endpunkt wählen
| Was Sie brauchen | Endpunkt |
|---|---|
| Hautton-Abgleich und freie Wahl des Dateiformats | Dieser Endpunkt |
| Präzise Gesichtspunkte und Originaltextur, ohne Regler | Face Swap Pro |
| Der einfache Tausch mit Seed, die Haare bleiben immer unberührt | Face Swap |
| Der ganze Kopf, Haare inklusive, jedes Mal | Head Swap |
| Ein Gesicht über einen bewegten Clip hinweg | Video Face Swap |
Als Batch ausführen
Zwei Pflichtfelder und drei Standardwerte machen einen Batch zu einer Schleife über Paare. Senden Sie jeden Create-Aufruf mit einem Idempotency-Key und speichern Sie die Task-ID beim auslösenden Datensatz. Bricht eine Verbindung ab, liefert die Wiederholung mit demselben Schlüssel die ursprüngliche Task, statt eine zweite mit zweiter Abrechnung zu starten. Fragen Sie alle paar Sekunden ab und kopieren Sie jedes Ergebnis in Ihren eigenen Speicher – erzeugte Dateien werden nach 14 Tagen gelöscht, hochgeladene Ausgangsbilder nach einem Tag.
API-Schnellstart
# 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/face-swap-v1-plus/edit",
"input": {
"image_url": "https://example.com/reference.png",
"output_format": "jpeg",
"reference_image_url": "https://example.com/reference.png"
}
}'
# 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"
Authentifizierung, vollständiges Schema, Polling und Fehlerbehandlung stehen in der API-Referenz.
