Einführung
Head Swap ersetzt den gesamten Kopf der Person im Zielbild durch den Kopf aus einem Referenzfoto. Gesicht, Frisur, Haarfarbe und Kopfsilhouette werden übertragen; Körper, Kleidung, Pose, Licht und Hintergrund des Zielbilds bleiben, wie sie waren.
Die Anfrage besteht aus zwei Bild-URLs und einem optionalen seed: image_url ist der Körper, der erhalten bleibt, reference_image_url liefert den Kopf. Es gibt keinen Prompt, keine Maske und keine Stärke-Einstellung, und pro Anfrage kommt ein Bild zurück.
Wichtige Funktionen und Highlights
Einen kompletten Figurenkopf in eine bestehende Aufnahme setzen
Head Swap verändert mehr als die Gesichtsidentität: Es ist der richtige Umfang, wenn Haare, Haarfarbe und Kopfsilhouette der neuen Figur mitkommen müssen. Das macht es nützlich für Neubesetzungen, Kostümkonzepte und Kontinuität, bei denen die Frisur des Zielbilds nicht bleiben soll.
Der Halsübergang ist der Abnahmetest
Wählen Sie Ausgangsmaterial mit passendem Kamerawinkel, passender Lichtrichtung und sichtbarem Halsbereich. Prüfen Sie Haaransatz, Ohren, Kiefer, Halsnaht und Schattenverlauf in voller Größe, bevor Sie ein Ergebnis abnehmen – an diesen Grenzen zeigt sich, ob die beiden Bilder wirklich zusammenpassen.
Mit einem kontrollierten Bildpaar arbeiten
Beginnen Sie mit einer klaren Person in jedem Bild und vermeiden Sie starke Unschärfe, Verdeckung oder extreme Profile. Sind die eigenen Haare und die Silhouette des Zielbilds für die Aufnahme wesentlich, wählen Sie Face Swap, statt einen Kopftausch zu erzwingen.
Request-Parameter
| Parameter | Pflicht | Beschreibung |
|---|---|---|
image_url | Ja | Das Bild, das verändert wird. Körper, Garderobe, Pose, Licht und Hintergrund bleiben erhalten; alles oberhalb des Halses wird ersetzt. mindestens 1 Zeichen |
reference_image_url | Ja | Das Bild, das den ganzen Kopf liefert, samt Form, Frisur und Haarfarbe. Wählen Sie eines, das aus ähnlicher Richtung beleuchtet ist und in ähnlichem Winkel steht wie das Ziel. mindestens 1 Zeichen |
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
Den ganzen Kopf ersetzen, nicht nur das Gesicht
Nutzen Sie diesen Endpunkt, wenn Frisur, Haarfarbe und Kopfsilhouette der neuen Person mitkommen müssen. Prüfen Sie Haaransatz, Ohren und Halsnaht in voller Größe, bevor Sie das Ergebnis abnehmen; gehören die eigenen Haare des Zielbilds zur Aufnahme, ist Face Swap das schmalere Werkzeug.
Eine Körperaufnahme neu besetzen, die Ihnen bereits gefällt
Wenn Kleidung, Pose und Licht eines Bildes schon stimmen, ist der Kopftausch günstiger und berechenbarer, als das ganze Bild neu zu erzeugen und zu hoffen, dass die Komposition überlebt.
Kostüm- und Cosplay-Aufnahmen
Setzen Sie den eigenen Kopf und die Frisur einer Figur auf einen Körper, der das von Ihnen erzeugte Kostüm trägt. Die Dienstmädchenuniform, die Pose und das Café-Set bleiben genau so, wie sie waren, die Arbeit am Outfit übersteht also den Durchgang.
Jede Szene mit einem Gesicht, für das eine Einwilligung vorliegt
Setzen Sie einen Kopf, den Sie verwenden dürfen, in Motive, die Sie selbst erstellt haben – ganz gleich, was sie zeigen. Der Endpunkt behandelt das Material nicht anders – maßgeblich ist die Einwilligungspflicht aus den Hinweisen unten, und die ist keine Formalität.
Prompt-Leitfaden und Praxistipps
Klären Sie die Rechte an beiden Personen
Beide Bilder zeigen eine Person, und Sie brauchen eine Berechtigung sowohl für den Kopf, den Sie übertragen, als auch für das Bild, in das Sie ihn setzen. Bewahren Sie die Freigabe beim Auftragsdatensatz auf, bevor die Integration beginnt.
Winkel angleichen, dann das Paar senden
image_url ist der Körper, der erhalten bleibt; reference_image_url liefert den Kopf. Ein allgemeiner Bildeditor bräuchte eine Anweisung wie: „Head swap: replace the entire head of the person in the first image — face, hairstyle and hair colour — with the head from the second image, keeping the first image's body, maid outfit, pose, cafe background, lighting and colour grade unchanged. Match the neck seam, skin tone and lighting direction so the result reads as one photograph.“ – hier gibt es überhaupt kein Prompt-Feld.
Das Ergebnis prüfen, bevor Sie iterieren
Die typische Fehlerstelle ist die Halsnaht: Ein Zielbild, dessen Hals von einem hohen Kragen, einem Schal oder Haaren verdeckt ist, oder dessen Kopf in einem deutlich anderen Winkel steht als in der Referenz, erzeugt eine sichtbare Fuge. Gleichen Sie Lichtrichtung und Hautton der beiden Vorlagen an und bevorzugen Sie ähnliche Kopfwinkel. Beide Bilder brauchen einen gut sichtbaren, einigermaßen frontalen, gut beleuchteten Kopf in ausreichender Größe; bei Gruppenfotos kann der Endpunkt nicht wissen, welche Person gemeint ist. Soll die Frisur des Zielbilds bleiben, nehmen Sie Face Swap – kein Parameter hier bewahrt sie. Es gibt keinen Prompt, keine Maske und keine Stärke-Einstellung; ein falsches Ergebnis behebt man mit einem anderen Bildpaar.
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/head-swap-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"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.
