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
- Erstellen Sie ein Konto bei iSamurai
- Gehen Sie zu Ihrer Profilseite und generieren Sie einen API-Schlüssel
- Fügen Sie den API-Schlüssel in Ihre Request-Header ein
- 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.
Offizielles SDK
Vollständiger Python-Wrapper mit automatischem Polling, Typ-Hinweisen und Fehlerbehandlung.
Auf GitHub ansehen →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)
/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)
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
source_image_base64 | string | Erforderlich | Base64-kodiertes Quellgesichtsbild |
target_image_base64 | string | Erforderlich | Base64-kodiertes Zielbild (aus Video oder Bild) |
instance | UUID | Optional | Vorhandene FaceSwap-Instanz-ID |
enhance | boolean | Optional | Gesichtsverbesserung 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)
/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)
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
source_image | File | Erforderlich | Gesichtsbilddatei (JPG/PNG) |
target_media | File | Erforderlich | Videodatei (MP4/MOV) oder Bild |
gquality | string | Erforderlich | 480p, 720p oder 1080p |
name | string | Optional | Jobname (max. 20 Zeichen) |
description | string | Optional | Beschreibung (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
/api/swap-progress/?id={instance_id}
Fragen Sie diesen Endpunkt ab, um den Jobfortschritt zu überwachen, bis der Status Done ist.
Statuswerte
| Status | Beschreibung |
|---|---|
Queued | Wartet in der Warteschlange |
Processing | Wird gerade verarbeitet |
Done | Abgeschlossen – Ausgabe verfügbar |
Failed | Fehler aufgetreten |
Cancelled | Vom 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
/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)
/api/analyse-frame/
Erkennen Sie alle Gesichter in einem Video-Frame. Senden Sie einen base64-kodierten Frame aus Ihrem Zielvideo.
Request-Body (JSON)
| Parameter | Typ | Beschreibung |
|---|---|---|
target_image_base64 | string | Base64-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)
/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
/api/multiple-face-swap/
Verarbeiten Sie das vollständige Video mit allen Gesichtszuordnungen. Verwenden Sie multipart/form-data.
Request-Parameter (multipart/form-data)
| Parameter | Typ | Beschreibung |
|---|---|---|
target_media | File | Videodatei (MP4/MOV) |
gquality | string | 480p, 720p oder 1080p |
analysis_results | JSON string | Array mit source_image base64 für jedes Gesicht |
Schritt 4: Fortschritt prüfen
/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
| Faktor | Kosten pro Sekunde | Anwendungsfall |
|---|---|---|
| 2x Slow | 2 Credits/Sek. | Sanfte Zeitlupe |
| 4x Ultra | 3 Credits/Sek. | Dramatische Zeitlupe |
| 8x Super | 7 Credits/Sek. | Extreme Zeitlupe |
Zeitlupenprojekt erstellen
/api/slowmotion/
Laden Sie ein Video hoch und konfigurieren Sie die Zeitlupeneinstellungen.
Request-Parameter (multipart/form-data)
| Parameter | Typ | Optionen | Beschreibung |
|---|---|---|---|
source_video | File | - | Zu verlangsamendes Video (MP4/MOV) |
slowdown_factor | int | 2, 4, 8 | Wie stark verlangsamt werden soll |
quality | string | 480p, 720p, 1080p | Ausgabequalität |
mode | string | slowmo, fps | slowmo = 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
/api/faceswap/slowmotion/process/
Starten Sie die Zeitlupenverarbeitung.
{ "project_id": "uuid" }
/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.
/api/restore-image/
Verarbeiten Sie ein Bild mit KI-Restaurierung oder -Verbesserung.
Request-Parameter (multipart/form-data)
| Parameter | Typ | Optionen |
|---|---|---|
image | File | JPG/PNG-Bild |
mode | string | restore 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.
/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"
}
🖼️ Galerie-API
Verwalten Sie Ihre hochgeladenen Quellbilder. Laden Sie Bilder einmal hoch und verwenden Sie sie in mehreren Face-Swap-Jobs erneut.
Quellbilder hochladen
/api/gallery/sources/
Laden Sie ein oder mehrere Quellbilder in Ihre Galerie hoch. Verwenden Sie multipart/form-data mit dem Feld images.
Request-Parameter (multipart/form-data)
| Parameter | Typ | Beschreibung |
|---|---|---|
images | File(s) | Ein oder mehrere Bilddateien (JPG/PNG). Feld für mehrere Uploads wiederholen. |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# Mehrere Bilder hochladen
files = [
("images", ("face1.jpg", open("face1.jpg", "rb"), "image/jpeg")),
("images", ("face2.jpg", open("face2.jpg", "rb"), "image/jpeg")),
]
response = requests.post(
f"{BASE_URL}/gallery/sources/",
headers={"Authorization": f"Api-Key {API_KEY}"},
files=files
)
result = response.json()
print(f"Uploaded: {result['message']}")
for img in result["images"]:
print(f" ID: {img['id']} - {img['name']}")
Antwort
{
"message": "2 images uploaded successfully",
"images": [
{"id": "uuid-1", "name": "face1.jpg", "url": "/media/sources/..."},
{"id": "uuid-2", "name": "face2.jpg", "url": "/media/sources/..."}
]
}
Quellbilder auflisten
/api/gallery/sources/
Listen Sie Ihre hochgeladenen Quellbilder mit Paginierung auf.
Query-Parameter
| Parameter | Standard | Beschreibung |
|---|---|---|
page | 1 | Seitennummer |
per_page | 20 | Einträge pro Seite (max. 50) |
Antwort
{
"images": [{"id": "uuid", "name": "face.jpg", "url": "..."}],
"has_next": true,
"total": 45
}
Quellbilder löschen
/api/gallery/sources/{image_id}/
Löschen Sie ein einzelnes Quellbild anhand der ID.
/api/gallery/sources/bulk-delete/
Löschen Sie mehrere Quellbilder auf einmal.
{"ids": ["uuid-1", "uuid-2", "uuid-3"]}
Vorschauen (generierte Swaps)
/api/gallery/previews/
Listen Sie Ihre gespeicherten Vorschaubilder aus Face-Swap-Vorgängen auf.
⚠️ 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.
| Statuscode | Bedeutung | Aktion |
|---|---|---|
| 400 | Bad Request | Request-Parameter prüfen |
| 401 | Unauthorized | Prüfen, ob der API-Schlüssel gültig ist |
| 403 | Forbidden | Unzureichendes Guthaben oder fehlende Berechtigungen |
| 404 | Not Found | Ressource existiert nicht |
| 500 | Server Error | Support 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.