Face Swap API: Gesichtstausch mit einem API-Aufruf in deine App

Mit einer Face Swap API setzt deine App das Gesicht einer Person mit einer einzigen HTTP-Anfrage in ein anderes Foto ein. Diese Anleitung zeigt die Anfrage in curl, JavaScript und Python, wie du lange Jobs und Gruppenfotos handhabst, was Fehler bedeuten, was es kostet und wie du die API verantwortungsvoll nutzt.

Morfran-Team · 4 Min. Lesezeit · aktualisiert am 22 Nov. 2026

Was eine Face Swap API macht

Eine Face Swap API nimmt zwei Bilder und gibt ein neues zurück. Das Quellbild zeigt das Gesicht, das du verwenden willst. Das Zielbild ist das Foto, das du verändern willst. Die API findet das Gesicht im Zielbild, ersetzt es durch das Gesicht aus dem Quellbild und gleicht Hautton, Licht und Winkel an, damit das Ergebnis wie ein einziges Foto aussieht.

Entwickler nutzen sie zum Beispiel für personalisierte Grußkarten, Kampagnen nach dem Motto „Setz dich selbst aufs Plakat“, Avatar- und Profil-Tools, Spielfiguren und Fotobox-Apps auf Veranstaltungen. Statt eigene Modelle zu trainieren und zu hosten, sendest du eine HTTP-Anfrage und bekommst ein Bild zurück.

Bevor du loslegst

Du brauchst drei Dinge:

  1. Ein Morfran-Konto. Neue Konten erhalten 50 kostenlose Credits, genug für zehn einzelne Face Swaps.
  2. Einen API-Key. Erstelle ihn in deinem Dashboard unter API-Keys. Bewahre ihn auf deinem Server auf und setze ihn nie in Browser- oder Mobile-App-Code ein.
  3. Zwei öffentliche Bild-URLs. JPG, PNG oder WebP. Das Quellbild sollte ein deutliches Gesicht zeigen, das ungefähr in die Kamera blickt.

Jede Anfrage sendet den Key im Header X-API-Key. Die Basis-URL ist https://api.morfran.com.

Dein erster Face Swap mit curl

curl -X POST https://api.morfran.com/v1/face-swap \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'

Standardmäßig ist der Aufruf synchron: Die API wartet auf das Ergebnis (bis zu etwa 60 Sekunden) und gibt eine JSON-Antwort mit einem Link zum fertigen Bild auf cdn.morfran.com sowie den verbrauchten Credits zurück. Lade das Bild sofort herunter, denn Ergebnisse werden nach einer Stunde gelöscht.

Dieselbe Anfrage in JavaScript (Node.js)

const res = await fetch("https://api.morfran.com/v1/face-swap", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.MORFRAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    SourceImageUrl: "https://example.com/face.jpg",
    TargetImageUrl: "https://example.com/photo.jpg",
  }),
});
const data = await res.json();
console.log(res.status, data);

Führe das auf deinem Server aus, nicht im Browser, damit dein Key privat bleibt.

Dieselbe Anfrage in Python

import os
import requests

res = requests.post(
    "https://api.morfran.com/v1/face-swap",
    headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
    json={
        "SourceImageUrl": "https://example.com/face.jpg",
        "TargetImageUrl": "https://example.com/photo.jpg",
    },
    timeout=90,
)
print(res.status_code, res.json())

Lange Jobs: den Async-Modus nutzen

Wenn deine App nicht auf eine offene Anfrage warten soll, hänge ?async=true an die URL an. Die API antwortet sofort mit einer Task-ID. Frage das Ergebnis dann alle paar Sekunden mit GET /v1/face-swap/{taskId} ab, bis es fertig ist. Das funktioniert gut hinter einer Job-Queue oder wenn dein eigener Server ein kurzes Request-Timeout hat.

Gruppenfotos: bis zu acht Gesichter tauschen

Für ein Teamfoto oder ein Familienbild verwendest du POST /v1/face-swap/group. Damit werden bis zu acht Gesichter in einem Aufruf getauscht; MaxFaces legt die Grenze fest. Ein Gruppen-Face-Swap kostet 10 Credits, ein einzelner Face Swap 5 Credits. Die vollständige Liste der Felder findest du in der API-Dokumentation und im OpenAPI-Schema.

Fehler und Credits behandeln

  • 401: Der API-Key fehlt oder ist falsch. Prüfe den Header X-API-Key.
  • 402: Nicht genug Credits. Kaufe ein Credit-Paket in deinem Dashboard.
  • 422: Es wurde kein Gesicht gefunden. Bitte um ein deutlicheres Foto mit einem Gesicht.

Fehlgeschlagene Anfragen werden nicht berechnet. Credits werden nur für fertige Bilder abgezogen, ein erneuter Versuch nach einem 422 kostet also nicht doppelt. Deinen Kontostand kannst du jederzeit mit GET /v1/credits/balance abfragen, das ist kostenlos.

Tipps für bessere Ergebnisse

  • Verwende ein deutliches Quellgesicht. Eine Person, Blick in die Kamera, Augen offen, keine Sonnenbrille, gutes Licht.
  • Achte auf den Winkel. Ein Gesicht, das geradeaus blickt, fügt sich am besten in ein Zielbild ein, in dem die Person ebenfalls ungefähr in die Kamera schaut.
  • Gesichter müssen groß genug sein. Ein Gesicht, das im Zielbild nur wenige Pixel breit ist, lässt sich nicht gut tauschen.
  • Ähnliches Licht hilft. Ein bei Tageslicht aufgenommenes Gesicht wirkt in einem Zielfoto bei Tageslicht am natürlichsten.
  • Teste mit deinen echten Bildern. Verwende ein paar der kostenlosen Credits für Fotos, wie sie deine Nutzer hochladen werden.

Einwilligung und Datenschutz

Tausche nur das Gesicht einer Person, die dem zugestimmt hat. Nutze Face Swap nicht, um Menschen zu täuschen, dich als jemand anderes auszugeben oder Inhalte zu erstellen, die einer realen Person schaden. Wenn du Ergebnisse veröffentlichst, kennzeichne sie als KI-generiert. Hochgeladene Bilder und Ergebnisse werden innerhalb einer Stunde aus unserem Speicher gelöscht, und wir verwenden sie nicht zum Training von KI-Modellen. Missbrauch kannst du über die Kontaktseite melden; er wird innerhalb von 48 Stunden bearbeitet.

Nutzung über einen KI-Agenten

Derselbe Face Swap ist auf Morfrans MCP-Server unter https://api.morfran.com/mcp verfügbar, sodass Assistenten wie Claude ihn mit deinem API-Key aufrufen können. Die Einrichtung ist im MCP-Abschnitt der Dokumentation beschrieben.

Fragen

Was kostet die Face Swap API?

Ein einzelner Face Swap kostet 5 Credits, ein Gruppen-Face-Swap (bis zu acht Gesichter) 10 Credits. Neue Konten erhalten 50 kostenlose Credits. Danach kaufst du Credit-Pakete; es gibt kein Abo. Die Pakete findest du unter Preise.

Wie lange dauert ein Face Swap?

Die meisten Ergebnisse kommen innerhalb der synchronen Wartezeit von etwa 60 Sekunden zurück. Für lange Jobs oder kurze Server-Timeouts nutzt du ?async=true und fragst das Ergebnis mit der Task-ID ab.

Kann ich Bilder als Base64 statt als URLs senden?

Die Beispiele hier verwenden öffentliche URLs, das ist der einfachste Weg. Das OpenAPI-Schema listet jedes Eingabefeld auf, das der Endpoint akzeptiert.

Wie lange werden Ergebnisse gespeichert?

Hochgeladene Bilder und Ergebnisse werden innerhalb einer Stunde gelöscht. Speichere das Ergebnisbild auf deiner Seite, sobald du es erhältst.

Kann ich es ausprobieren, ohne Code zu schreiben?

Ja. Melde dich an und öffne den Playground. Er führt denselben Face Swap im Browser aus und zeigt die passende API-Anfrage.