iSamurai Face Swap API-Dokumentation

Vollständiger Entwicklerleitfaden zur Integration von KI-gestütztem Face Swap, Zeitlupenvideo und Bildrestaurierung in Ihre Anwendungen.

🚀 Erste Schritte

Die iSamurai API bietet programmatischen Zugriff auf unsere Suite KI-gestützter Video- und Bildbearbeitungstools. Egal, ob Sie eine Content-Erstellungsplattform aufbauen, Face-Swap-Technologie in Ihre App integrieren oder filmische Zeitlupeneffekte hinzufügen möchten – unsere RESTful API macht es einfach.

Basis-URL

https://isamur.ai/api/

Schnellstart-Schritte

  1. Erstellen Sie ein Konto bei iSamurai
  2. Gehen Sie zu Ihrer Profilseite und generieren Sie einen API-Schlüssel
  3. Fügen Sie den API-Schlüssel in Ihre Request-Header ein
  4. Beginnen Sie mit API-Aufrufen!
💡

Guthabensystem: Alle Verarbeitungsvorgänge verbrauchen Guthaben (Credits). Prüfen Sie Ihren Kontostand unter /api/user-credits/, bevor Sie Jobs einreichen. Sehen Sie sich unsere Preispläne an für Guthaben-Pakete.

📦 SDK & Tools

Beschleunigen Sie Ihre Entwicklung mit unseren offiziellen Client-Bibliotheken und Codebeispielen.

Python

Offizielles SDK

Vollständiger Python-Wrapper mit automatischem Polling, Typ-Hinweisen und Fehlerbehandlung.

Auf GitHub ansehen →
Code

API-Beispiele

Rohe Skripte und Anwendungsbeispiele für die direkte API-Integration.

Auf GitHub ansehen →

🔐 Authentifizierung

Alle API-Endpunkte erfordern eine Authentifizierung. Fügen Sie Ihre Anmeldedaten bei jeder Anfrage in den Authorization-Header ein.

API-Schlüssel-Authentifizierung (empfohlen)

API-Schlüssel sind die empfohlene Authentifizierungsmethode für Server-zu-Server-Integrationen. Schlüssel laufen nie ab und bieten einen einfachen, sicheren Zugriff auf alle Endpunkte.

curl -H "Authorization: Api-Key isk_your_api_key_here" \
  https://isamur.ai/api/user-credits/

🎭 Face Swap API

Die Face Swap API ermöglicht es Ihnen, Gesichter in Videos und Bildern nahtlos zu tauschen. Verwenden Sie den Vorschau-Endpunkt, um zunächst mit einem einzelnen Frame zu testen, und verarbeiten Sie dann das vollständige Video.

Schnellvorschau (Einzelbild)

POST /api/preview-swap-api/

Erstellen Sie eine Einzelbild-Vorschau des Face Swaps, bevor Sie das vollständige Video verarbeiten. Verwendet base64-kodierte Bilder. Kostet ca. 1-2 Credits.

Request-Body (JSON)

ParameterTypErforderlichBeschreibung
source_image_base64stringErforderlichBase64-kodiertes Quellgesichtsbild
target_image_base64stringErforderlichBase64-kodiertes Zielbild (aus Video oder Bild)
instanceUUIDOptionalVorhandene FaceSwap-Instanz-ID
enhancebooleanOptionalGesichtsverbesserung anwenden (Standard: false)
import requests
import base64

API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"

# Bilder in base64 konvertieren
def to_base64(file_path):
    with open(file_path, "rb") as f:
        return base64.b64encode(f.read()).decode()

# Vorschau generieren
response = requests.post(
    f"{BASE_URL}/preview-swap-api/",
    headers={
        "Authorization": f"Api-Key {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "source_image_base64": to_base64("face.jpg"),
        "target_image_base64": to_base64("target_frame.jpg"),
        "enhance": False
    }
)

# Vorschaubild speichern
preview_base64 = response.json()["image_base64"]
with open("preview.jpg", "wb") as f:
    f.write(base64.b64decode(preview_base64))

Antwort

{
  "image_base64": "/9j/4AAQSkZJRgABAQAAAQ...",
  "preview_id": "abc123"
}

Vollständige Videoverarbeitung (Kombinierter Upload + Verarbeitung)

POST /api/full-process-swap/

Laden Sie Dateien hoch und starten Sie die Verarbeitung sofort in einer Anfrage. Dies ist der empfohlene Endpunkt für automatisierte Workflows. Es werden ca. 50 Credits pro Videominute abgezogen.

Request-Parameter (multipart/form-data)

ParameterTypErforderlichBeschreibung
source_imageFileErforderlichGesichtsbilddatei (JPG/PNG)
target_mediaFileErforderlichVideodatei (MP4/MOV) oder Bild
gqualitystringErforderlich480p, 720p oder 1080p
namestringOptionalJobname (max. 20 Zeichen)
descriptionstringOptionalBeschreibung (max. 20 Zeichen)
import requests

API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"

# Lokale Dateien hochladen und Verarbeitung starten
with open("face.jpg", "rb") as source, open("video.mp4", "rb") as target:
    response = requests.post(
        f"{BASE_URL}/full-process-swap/",
        headers={"Authorization": f"Api-Key {API_KEY}"},
        files={
            "source_image": ("face.jpg", source, "image/jpeg"),
            "target_media": ("video.mp4", target, "video/mp4")
        },
        data={
            "gquality": "720p",
            "name": "My Swap",
            "description": "Demo"
        }
    )

result = response.json()
instance_id = result["faceswap"]["id"]
print(f"Processing started: {instance_id}")

Fortschritt prüfen

GET /api/swap-progress/?id={instance_id}

Fragen Sie diesen Endpunkt ab, um den Jobfortschritt zu überwachen, bis der Status Done ist.

Statuswerte

StatusBeschreibung
QueuedWartet in der Warteschlange
ProcessingWird gerade verarbeitet
DoneAbgeschlossen – Ausgabe verfügbar
FailedFehler aufgetreten
CancelledVom Benutzer abgebrochen
import time

while True:
    response = requests.get(
        f"{BASE_URL}/swap-progress/",
        headers={"Authorization": f"Api-Key {API_KEY}"},
        params={"id": instance_id}
    )
    data = response.json()
    print(f"Status: {data['status']} - {data.get('progress_percentage', 0)}%")

    if data["status"] == "Done":
        print(f"Output: {data['output_media_url']}")
        break
    elif data["status"] in ["Failed", "Cancelled"]:
        print(f"Error: {data.get('error')}")
        break
    time.sleep(5)

Job stoppen/abbrechen

POST /api/stop-job/

Brechen Sie einen laufenden Job ab. Sie erhalten eine Rückerstattung von 50 % der Credits.

{"id": "instance_uuid", "type": "faceswap"}

👥 Multi-Face-Swap-API

Tauschen Sie mehrere Gesichter in einem einzigen Video. Analysieren Sie den Frame, um alle Gesichter zu erkennen, weisen Sie jedem Quellbilder zu und starten Sie dann die Verarbeitung.

Schritt 1: Frame analysieren (Gesichter erkennen)

POST /api/analyse-frame/

Erkennen Sie alle Gesichter in einem Video-Frame. Senden Sie einen base64-kodierten Frame aus Ihrem Zielvideo.

Request-Body (JSON)

ParameterTypBeschreibung
target_image_base64stringBase64-kodierter Frame aus dem Zielvideo
import base64

# Erfassen Sie einen Frame aus Ihrem Video (mit OpenCV, ffmpeg usw.)
with open("frame.jpg", "rb") as f:
    frame_b64 = base64.b64encode(f.read()).decode()

response = requests.post(
    f"{BASE_URL}/analyse-frame/",
    headers={
        "Authorization": f"Api-Key {API_KEY}",
        "Content-Type": "application/json"
    },
    json={"target_image_base64": frame_b64}
)

faces = response.json()["analysis"]
for face in faces:
    print(f"Face detected: {face['person_id']}")

Antwort

{
  "analysis": [
    {"person_id": "P1", "thumbnail": "base64...", "bbox": [x, y, w, h]},
    {"person_id": "P2", "thumbnail": "base64...", "bbox": [x, y, w, h]}
  ]
}

Schritt 2: Multi-Swap-Vorschau (optional)

POST /api/multi-preview-swap-api/

Sehen Sie sich eine Vorschau des Multi-Face-Swaps an einem einzelnen Frame an, bevor Sie die vollständige Verarbeitung starten.

Request-Body (JSON)

{
  "target_image_base64": "base64_frame...",
  "analysis_results": [
    {
      "person_id": "P1",
      "thumbnail": "base64...",
      "source_image": "base64_of_source_face_1"
    },
    {
      "person_id": "P2",
      "thumbnail": "base64...",
      "source_image": "base64_of_source_face_2"
    }
  ],
  "enhance": false
}

Antwort

{"preview_image": "base64_result..."}

Schritt 3: Vollständige Multi-Face-Verarbeitung

POST /api/multiple-face-swap/

Verarbeiten Sie das vollständige Video mit allen Gesichtszuordnungen. Verwenden Sie multipart/form-data.

Request-Parameter (multipart/form-data)

ParameterTypBeschreibung
target_mediaFileVideodatei (MP4/MOV)
gqualitystring480p, 720p oder 1080p
analysis_resultsJSON stringArray mit source_image base64 für jedes Gesicht

Schritt 4: Fortschritt prüfen

GET /api/swap-progress/?id={instance_id}&multi=True

Fragen Sie den Fortschritt ab. Fügen Sie multi=True für Multi-Face-Swap-Jobs hinzu.

⏱️ Zeitlupen- & FPS-Boost-API

Erstellen Sie beeindruckende Zeitlupenvideos mit KI-Frame-Interpolation. Unsere Zeitlupentechnologie erzeugt neue Frames zwischen den vorhandenen und ermöglicht es Ihnen, Aufnahmen bis zu 8-fach zu verlangsamen, während eine flüssige, gleichmäßige Bewegung erhalten bleibt.

Guthabenpreise

FaktorKosten pro SekundeAnwendungsfall
2x Slow2 Credits/Sek.Sanfte Zeitlupe
4x Ultra3 Credits/Sek.Dramatische Zeitlupe
8x Super7 Credits/Sek.Extreme Zeitlupe

Zeitlupenprojekt erstellen

POST /api/slowmotion/

Laden Sie ein Video hoch und konfigurieren Sie die Zeitlupeneinstellungen.

Request-Parameter (multipart/form-data)

ParameterTypOptionenBeschreibung
source_videoFile-Zu verlangsamendes Video (MP4/MOV)
slowdown_factorint2, 4, 8Wie stark verlangsamt werden soll
qualitystring480p, 720p, 1080pAusgabequalität
modestringslowmo, fpsslowmo = langsameres Video, fps = flüssigeres Video
with open("action_clip.mp4", "rb") as video:
    response = requests.post(
        f"{BASE_URL}/slowmotion/",
        headers={"Authorization": f"Api-Key {API_KEY}"},
        files={"source_video": video},
        data={
            "slowdown_factor": 4,
            "quality": "720p",
            "mode": "slowmo"
        }
    )

project = response.json()["slowmotion"]
print(f"Project ID: {project['id']}")

Verarbeitung starten

POST /api/faceswap/slowmotion/process/

Starten Sie die Zeitlupenverarbeitung.

{ "project_id": "uuid" }
GET /api/faceswap/slowmotion/progress/{project_id}/

Prüfen Sie den Fortschritt der Zeitlupenverarbeitung.

✨ Bildrestaurierungs- & Verbesserungs-API

Restaurieren Sie alte, beschädigte Fotos oder verbessern Sie die Gesichtsqualität mit unserem KI-gestützten Bildrestaurierungstool. Perfekt, um alten Fotografien neues Leben einzuhauchen oder niedrig aufgelöste Gesichtsbilder zu verbessern.

POST /api/restore-image/

Verarbeiten Sie ein Bild mit KI-Restaurierung oder -Verbesserung.

Request-Parameter (multipart/form-data)

ParameterTypOptionen
imageFileJPG/PNG-Bild
modestringrestore oder face_enhance

Antwort

{
  "url": "/api/media/restored/output.jpg",
  "image_base64": "/9j/4AAQSkZ...",
  "status": "success"
}

💳 Benutzer- & Guthaben-API

Überwachen Sie Ihren Guthabenstand und Kontostatus. Prüfen Sie Ihr Guthaben, bevor Sie Jobs einreichen, um sicherzustellen, dass Sie über ausreichendes Guthaben verfügen. Sehen Sie sich unsere Preispläne an, um weiteres Guthaben zu erwerben.

GET /api/user-credits/

Rufen Sie Ihren aktuellen Guthabenstand und Ihre Plan-Informationen ab.

Antwort

{
  "user_id": 123,
  "user_credits": 9500,
  "plan_id": 5,
  "plan_name": "Samurai"
}

⚠️ Fehlerbehandlung

Alle API-Fehler geben eine einheitliche JSON-Struktur mit einer Fehlermeldung zurück. Verwenden Sie HTTP-Statuscodes, um die Art des Fehlers zu bestimmen.

StatuscodeBedeutungAktion
400Bad RequestRequest-Parameter prüfen
401UnauthorizedPrüfen, ob der API-Schlüssel gültig ist
403ForbiddenUnzureichendes Guthaben oder fehlende Berechtigungen
404Not FoundRessource existiert nicht
500Server ErrorSupport kontaktieren

Fehlerantwortformat

{
  "error": "Insufficient credits: need 500, have 200",
  "success": false
}

🚦 Ratenbegrenzungen

Jeder Benutzer kann jeweils einen Job gleichzeitig ausführen. Warten Sie, bis Ihr aktueller Job abgeschlossen ist, bevor Sie einen neuen einreichen. Wenn Sie einen neuen Job einreichen, während ein anderer verarbeitet wird, wird er in die Warteschlange gestellt.

📚 Vollständige Codebeispiele

Vollständige, funktionierende Beispiele für gängige Anwendungsfälle.

Python: Vollständiger Face-Swap-Workflow

import requests
import time

API_KEY = "isk_your_key_here"
BASE_URL = "https://isamur.ai/api"
HEADERS = {"Authorization": f"Api-Key {API_KEY}"}

def face_swap(source_path, target_path, quality="720p"):
    # Schritt 1: Upload
    with open(source_path, "rb") as src, open(target_path, "rb") as tgt:
        resp = requests.post(f"{BASE_URL}/faceswap/", headers=HEADERS,
            files={"source_image": src, "target_media": tgt},
            data={"gquality": quality})
    job_id = resp.json()["faceswap"]["id"]

    # Schritt 2: Verarbeitung
    requests.post(f"{BASE_URL}/process-swap/",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"instance": job_id})

    # Schritt 3: Auf Abschluss warten
    while True:
        resp = requests.get(f"{BASE_URL}/swap-progress/",
            headers=HEADERS, params={"id": job_id})
        data = resp.json()
        print(f"Progress: {data.get('progress_percentage', 0)}%")

        if data["status"] == "Done":
            return data["output_media_url"]
        elif data["status"] == "Failed":
            raise Exception(data.get("error"))
        time.sleep(3)

# Verwendung
output = face_swap("face.jpg", "video.mp4")
print(f"Result: https://isamur.ai{output}")

JavaScript: Vollständiger Face-Swap-Workflow

const API_KEY = "isk_your_key_here";
const BASE_URL = "https://isamur.ai/api";

async function faceSwap(sourceFile, targetFile, quality = "720p") {
    // Schritt 1: Upload
    const formData = new FormData();
    formData.append("source_image", sourceFile);
    formData.append("target_media", targetFile);
    formData.append("gquality", quality);

    let resp = await fetch(`${BASE_URL}/faceswap/`, {
        method: "POST",
        headers: { "Authorization": `Api-Key ${API_KEY}` },
        body: formData
    });
    const jobId = (await resp.json()).faceswap.id;

    // Schritt 2: Verarbeitung
    await fetch(`${BASE_URL}/process-swap/`, {
        method: "POST",
        headers: {
            "Authorization": `Api-Key ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({ instance: jobId })
    });

    // Schritt 3: Auf Abschluss pollen
    while (true) {
        resp = await fetch(`${BASE_URL}/swap-progress/?id=${jobId}`, {
            headers: { "Authorization": `Api-Key ${API_KEY}` }
        });
        const data = await resp.json();
        console.log(`Progress: ${data.progress_percentage || 0}%`);

        if (data.status === "Done") return data.output_media_url;
        if (data.status === "Failed") throw new Error(data.error);
        await new Promise(r => setTimeout(r, 3000));
    }
}

Bereit loszulegen? Erstellen Sie Ihr Konto und generieren Sie einen API-Schlüssel auf Ihrer Profilseite.