Einführung¶
Dieser Leitfaden bietet eine technische Schritt-für-Schritt-Anleitung zur Integration der iSamurai API in Ihre Python-Anwendungen.
Das iSamurai Python SDK kapselt unsere REST API und übernimmt komplexe Aufgaben wie Datei-Uploads, Abfragen von Ergebnissen (Polling) und Fehlerbehandlung. Mit diesem SDK können Sie Videos über unsere Cloud-GPUs verarbeiten, ohne eigene Infrastruktur zu betreiben.
Dieses Tutorial behandelt:
1. Installation & Einrichtung
2. Face Swap (Single und Multi-Face)
3. Zeitlupen-Erstellung
4. Best Practices für den Produktivbetrieb
1. Installation und Einrichtung¶
Voraussetzungen¶
- Python 3.8 oder höher.
- Ein iSamurai API-Schlüssel (verfügbar in Ihrem Entwicklerprofil).
SDK installieren¶
Installieren Sie das offizielle Paket direkt von GitHub mit pip:
pip install git+https://github.com/isamurai-ai/iSamurai-SDK.git
Authentifizierung¶
Initialisieren Sie den Client mit Ihrem API-Schlüssel. Aus Sicherheitsgründen empfehlen wir die Verwendung von Umgebungsvariablen.
import os
from isamurai import Isamurai
# Initialize the client
api_key = os.getenv("ISAMURAI_API_KEY", "isk_YOUR_KEY_HERE")
client = Isamurai(api_key=api_key)
# Verify connection
credits = client.get_credits()
print(f"Connected. Credits available: {credits['credits']}")
2. Face Swap¶
Die Kernfunktion der API besteht darin, ein Gesicht in einem Zielvideo oder -bild durch ein Quellgesicht zu ersetzen.
Einfacher Single-Face-Swap¶
Dieses Beispiel zeigt den Standard-Workflow: Dateien hochladen, einen Job übermitteln und auf das Ergebnis warten.
# 1. Submit the job
job_id = client.process_face_swap(
source_path="face.jpg", # The face provider
target_path="video.mp4", # The target media
quality="1080p", # 720p or 1080p
enhance=True # Apply face enhancement
)
print(f"Job started: {job_id}")
# 2. Wait for completion
# The SDK handles polling automatically
try:
result = client.wait_for_job(job_id)
print(f"Download URL: {result['output_media_url']}")
except Exception as e:
print(f"Processing failed: {e}")
Fortgeschritten: Multi-Face-Swap¶
Wenn Ihr Zielvideo mehrere Personen enthält, möchten Sie möglicherweise nur bestimmte Gesichter austauschen und andere unverändert lassen.
Schritt 1: Video analysieren¶
Erkennen Sie zunächst die Gesichter im Zielvideo, um deren IDs zu erhalten.
# Analyze a representative frame from the video
faces = client.analyze_frame("target_frame.jpg")
# List all detected faces
for face in faces:
print(f"ID: {face['person_id']}, Location: {face['location']}")
Schritt 2: Zuordnung erstellen¶
Ordnen Sie die erkannte person_id Ihrem gewünschten Quellbild zu.
mapping = []
# Example: Swap the first detected face with 'user_face.jpg'
mapping.append({
"person_id": faces[0]['person_id'],
"source_image": client._to_base64("user_face.jpg")
})
Schritt 3: Verarbeiten¶
Übermitteln Sie die Zuordnung an den Multi-Swap-Endpunkt.
job_id = client.process_multi_face_swap(
target_path="video.mp4",
analysis_results=mapping
)
result = client.wait_for_job(job_id, multi=True)
print(result['output_media_url'])
3. KI-Zeitlupe erstellen¶
Sie können die API nutzen, um aus normalem Filmmaterial Zeitlupen mit hoher Bildrate zu erzeugen. Dabei kommt KI-Frame-Interpolation zum Einsatz, um flüssige Bewegungen zu erzeugen.
# 1. Upload and create project
# mode='slowmo' slows the video down (e.g. 30fps -> 30fps at 4x duration)
job_id = client.create_slow_motion(
video_path="input_video.mp4",
slowdown_factor=4, # Options: 2, 4, 8
mode="slowmo"
)
# 2. Start processing
client.process_slow_motion(job_id)
# 3. Monitor status (Custom polling logic required for SlowMo currently)
# See documentation for status endpoints
Funktionen kombinieren¶
Ein gängiger Workflow besteht darin, diese Vorgänge hintereinanderzuschalten:
1. Gesicht tauschen: Ein Video verarbeiten, um die Identität zu ändern.
2. Zeitlupe anwenden: Die Ausgabe-URL aus Schritt 1 übernehmen und an die Zeitlupen-API senden.
4. Best Practices¶
Die Galerie nutzen¶
Wenn Sie häufig dasselbe Quellbild verwenden (z. B. das Profilbild eines Nutzers), laden Sie es nicht bei jeder Anfrage erneut hoch. Laden Sie es einmalig in die Galerie hoch, um Bandbreite zu sparen.
# Upload once
client.upload_to_gallery(["profile.jpg"])
# (Future SDK updates will allow referencing these IDs directly)
Effizientes Polling¶
Der Helfer wait_for_job ist praktisch für Skripte, aber für produktive Webanwendungen sollten Sie Webhooks verwenden. So wird Ihr Server sofort benachrichtigt, sobald ein Job abgeschlossen ist, anstatt eine Verbindung offen zu halten.
Details zur Webhook-Konfiguration finden Sie in der API-Dokumentation.
Fehlerbehandlung¶
Kapseln Sie Ihre API-Aufrufe stets in try/except-Blöcke. Häufige Fehler sind:
* 402 Payment Required: Unzureichendes Guthaben.
* 400 Bad Request: Ungültige Dateiformate oder Parameter.
5. Häufig gestellte Fragen (FAQ)¶
F: Kann ich die API für kommerzielle Anwendungen nutzen?
A: Ja. Sie behalten die vollen kommerziellen Rechte an allen mit der iSamurai API erzeugten Medien. Sie können SaaS-Produkte, mobile Apps oder interne Tools auf Basis unserer Infrastruktur entwickeln.
F: Wie hoch sind die Ratenlimits?
A: Standardmäßig sind Konten auf einen gleichzeitigen Job begrenzt. Wenn Sie einen zweiten Job übermitteln, während der erste noch läuft, wird dieser in eine Warteschlange gestellt. Für höhere Concurrency-Limits kontaktieren Sie bitte den Support für einen Enterprise-Plan.
F: Sind meine Daten privat?
A: Ja. Quellbilder und Zielvideos werden ausschließlich zur Verarbeitung des angeforderten Jobs verwendet. Wir nutzen keine Nutzerdaten zum Training unserer Modelle.
F: Was kostet das?
A: Die Kosten hängen vom Vorgang (Face Swap, Zeitlupe usw.) und der Auflösung ab. Genauere Details finden Sie auf unserer Preisseite.
Zusammenfassung¶
Das iSamurai SDK vereinfacht das Hinzufügen von KI-Videofunktionen zu Ihren Python-Projekten.
Verwandte Tutorials & Funktionen¶
- Sehen Sie sich den visuellen Editor an: Face Swap Studio PRO UI
- Lesen Sie unsere vollständige Entwicklerdokumentation: API-Dokumentation
