Einführung
Face Swap überträgt die Gesichtszüge aus einem Bild auf die Person in einem anderen. Nur die Züge wandern: Frisur, Haaransatz, Kopfsilhouette, Pose, Kleidung, Licht und Hintergrund des Zielbilds bleiben, wie sie waren. Genau deshalb sitzt das Ergebnis im Originalfoto statt darauf.
Die Anfrage besteht aus zwei Bild-URLs und einem optionalen seed: image_url ist das Foto, das verändert wird, reference_image_url liefert das Gesicht. Ein Prompt-Feld gibt es nicht, und pro Anfrage kommt ein Bild zurück.
Wichtige Funktionen und Highlights
Die Aufnahme bleibt, die Identität wechselt
Das ist die schmale Wahl, wenn das Zielfoto bereits die richtigen Haare, die richtige Pose, Kleidung, den Bildausschnitt und die Umgebung hat. Übertragen wird die Gesichtsidentität, der Rest der freigegebenen Komposition bleibt geschützt – eine Neubesetzung wird so nicht zu einer kompletten Bildgenerierung.
Gebaut für wiederholbare Bildpaare
Der Ablauf ist bewusst einfach: ein freigegebenes Zielbild und eine freigegebene Referenz mit passendem Winkel und Licht vorbereiten, dann Kieferlinie, Augen und Hautübergang prüfen. Das macht den Endpunkt nützlich für kontrollierte Varianten von Avataren, Katalogbildern und Kampagnen, bei denen die Aufnahme wiedererkennbar bleiben muss.
Den Umfang des Tauschs vorher festlegen
Nutzen Sie Face Swap, wenn Frisur und Kopfsilhouette des Zielbilds zur Komposition gehören. Soll die neue Identität ihre Haare und die ganze Kopfform mitbringen, schicken Sie den Auftrag an Head Swap. Wer den richtigen Umfang wählt, spart sich einen vermeidbaren zweiten Lauf.
Request-Parameter
| Parameter | Pflicht | Beschreibung |
|---|---|---|
image_url | Ja | Das Bild, das verändert wird. Kopfform, Haare, Pose, Garderobe und Hintergrund dieser Person bleiben erhalten – ersetzt werden nur ihre Gesichtszüge. mindestens 1 Zeichen |
reference_image_url | Ja | Das Bild, das die Gesichtszüge liefert. Genommen wird nur das Gesicht, nicht Kopfform oder Haare. mindestens 1 Zeichen |
face_mapping | Nein | Für Gruppenbilder: Geben Sie an, welches Gesicht der Referenz auf welches Gesicht im Ziel kommt – ein Paar pro Eintrag, Gesichter ab 0 in Erkennungsreihenfolge nummeriert. höchstens 10 Einträge |
style | Nein | Finish für das getauschte Gesicht: realistic (Standard) behält natürlichen Hautton und Textur, beautify glättet und hellt die Haut auf, lossless bewahrt die meisten Gesichtsdeta… |
face_enhance | Nein | Führt nach dem Tausch einen Gesichtsverbesserungs-Durchgang aus, der das neue Gesicht höher aufgelöst ausgibt. Standardmäßig aus. Standardwert: |
seed | Nein | Denselben seed erneut nutzen, um zwei Läufe über dasselbe Bildpaar auf identischem Zug zu vergleichen; leer lassen oder auf 0 setzen für einen zufälligen Zug bei jedem Aufruf. |
Preis
$0.013 / Bild
Anwendungsfälle
Ein neues Gesicht für ein Porträt, dessen Haare schon stimmen
Nutzen Sie diesen Endpunkt, wenn Frisur, Haaransatz und Kopfsilhouette des Zielfotos zur Komposition gehören und sich nur die Gesichtszüge ändern sollen. Senden Sie das Zielbild als image_url und das Gesicht als reference_image_url und vergleichen Sie Augen und Kieferlinie in voller Größe mit der Vorlage, bevor Sie das Ergebnis abnehmen.
Eine Stock- oder generierte Aufnahme neu besetzen
Nehmen Sie eine Aufnahme, deren Licht, Pose und Set bereits funktionieren, und setzen Sie ein anderes Gesicht ein, statt das ganze Bild neu zu erzeugen und die bereits freigegebene Komposition zu verlieren.
Avatar- und Profilbild-Pipelines in großer Menge
Ohne Prompt lässt sich eine Liste von Ziel-Referenz-Paaren programmatisch durch den Endpunkt schicken. Fixieren Sie den Seed pro Paar, wenn ein neuer Versuch mit dem ersten Lauf vergleichbar bleiben muss.
Durchgängige Figuren über ein Shooting hinweg
Erzeugen Sie eine Reihe von Szenen mit einem beliebigen Modell und bringen Sie dann ein Gesicht in alle, damit die Serie als dieselbe Person gelesen wird. Weil Haare und Kleidung beim jeweiligen Zielbild bleiben, übersteht die erzeugte Vielfalt den Durchgang.
Prompt-Leitfaden und Praxistipps
Klären Sie die Rechte an beiden Gesichtern
Vor allem Technischen: Zielbild und Referenz zeigen beide Menschen, und Sie brauchen eine Berechtigung sowohl für das Gesicht, das Sie übertragen, als auch für das Bild, in das Sie es setzen. Bewahren Sie die Freigabe beim Auftragsdatensatz auf.
Beide Bilder hosten und das Paar senden
image_url ist das Bild, das verändert wird; reference_image_url liefert das Gesicht. Ein Prompt ist nicht beteiligt. Ein allgemeiner Bildeditor bräuchte eine Anweisung wie: „Face swap: take the face and hairline of the woman in the second image and place it onto the woman in the first image. Keep the first image's pose, outfit, magazine layout, lighting, framing and colour grade completely unchanged. Match skin tone and lighting so the result reads as one photograph.“ – dieser Endpunkt braucht weder das eine noch das andere.
Das Ergebnis prüfen, bevor Sie iterieren
Beide Bilder sollten ein gut sichtbares, einigermaßen frontales, gut beleuchtetes Gesicht zeigen; starke Profilwinkel, Bewegungsunschärfe, dichte Verdeckung und sehr kleine Gesichter sind die Stellen, an denen die Übertragung nachlässt oder ganz scheitert. Ein großer Unterschied in Lichtrichtung oder Hautton zwischen den beiden Bildern zeigt sich an der Kieferlinie; wählen Sie also eine Referenz, deren Licht ungefähr zum Zielbild passt. Standardmäßig wird pro Bild ein Gesicht getauscht; bei einem Gruppenfoto geben Sie die Paare in face_mapping an (welches Referenzgesicht auf welches Zielgesicht kommt, ab 0 nummeriert). Es gibt keinen Prompt, keine Maske und keine Stärke-Einstellung: Stimmt das Ergebnis nicht, hilft ein anderes Bildpaar, keine umformulierte Anfrage.
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/edit",
"input": {
"image_url": "https://example.com/reference.png",
"reference_image_url": "https://example.com/reference.png",
"style": "realistic"
}
}'
# 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.
