Introduction¶
Ce guide propose un tutoriel technique pour intégrer l’API iSamurai dans vos applications Python.
Le SDK Python iSamurai encapsule notre API REST et gère les tâches complexes comme l’envoi de fichiers, l’interrogation des résultats (polling) et la gestion des erreurs. Grâce à ce SDK, vous pouvez traiter des vidéos sur nos GPU cloud sans gérer votre propre infrastructure.
Ce tutoriel couvre :
1. Installation et configuration
2. Face Swap (visage unique et multi-visages)
3. Génération de Ralenti
4. Bonnes pratiques pour la production
1. Installation et configuration¶
Prérequis¶
- Python 3.8 ou supérieur.
- Une clé API iSamurai (disponible dans votre Profil développeur).
Installer le SDK¶
Installez le package officiel directement depuis GitHub avec pip :
pip install git+https://github.com/isamurai-ai/iSamurai-SDK.git
Authentification¶
Initialisez le client avec votre clé API. Nous recommandons d’utiliser des variables d’environnement pour la sécurité.
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¶
La fonction principale de l’API est de remplacer un visage dans une vidéo ou une image cible par un visage source.
Face Swap simple (un seul visage)¶
Cet exemple illustre le flux standard : envoi des fichiers, soumission d’une tâche et attente du résultat.
# 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}")
Avancé : Face Swap multi-visages¶
Si votre vidéo cible contient plusieurs personnes, vous pouvez vouloir remplacer certains visages spécifiques tout en laissant les autres inchangés.
Étape 1 : Analyser la vidéo¶
Détectez d’abord les visages dans la vidéo cible pour obtenir leurs identifiants.
# 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']}")
Étape 2 : Créer un mapping¶
Associez le person_id détecté à l’image source souhaitée.
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")
})
Étape 3 : Traiter¶
Envoyez le mapping au endpoint de swap multi-visages.
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. Créer un Ralenti IA¶
Vous pouvez utiliser l’API pour générer un ralenti à haute fréquence d’images à partir d’une vidéo standard. Cette fonction utilise l’interpolation d’images par IA pour créer un mouvement fluide.
# 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
Combiner les fonctionnalités¶
Un flux de travail courant consiste à enchaîner ces opérations :
1. Face Swap : Traiter une vidéo pour changer l’identité.
2. Appliquer le Ralenti : Récupérer l’URL de sortie de l’étape 1 et l’envoyer à l’API de Ralenti.
4. Bonnes pratiques¶
Utiliser la Galerie¶
Si vous utilisez fréquemment la même image source (par exemple, la photo de profil d’un utilisateur), ne l’envoyez pas à chaque requête. Envoyez-la une seule fois dans la Galerie pour économiser de la bande passante.
# Upload once
client.upload_to_gallery(["profile.jpg"])
# (Future SDK updates will allow referencing these IDs directly)
Polling efficace¶
L’assistant wait_for_job est utile pour les scripts, mais pour les applications web en production, vous devriez utiliser les Webhooks. Cela permet à votre serveur d’être notifié immédiatement lorsqu’une tâche est terminée, plutôt que de garder une connexion ouverte.
Consultez la Documentation de l’API pour la configuration des webhooks.
Gestion des erreurs¶
Encadrez toujours vos appels API avec des blocs try/except. Les erreurs courantes incluent :
* 402 Payment Required : Crédits insuffisants.
* 400 Bad Request : Formats de fichiers ou paramètres invalides.
5. Questions fréquentes (FAQ)¶
Q : Puis-je utiliser l’API pour des applications commerciales ?
R : Oui. Vous conservez l’intégralité des droits commerciaux sur les médias générés via l’API iSamurai. Vous pouvez créer des produits SaaS, des applications mobiles ou des outils internes en utilisant notre infrastructure.
Q : Quelles sont les limites de débit ?
R : Par défaut, les comptes sont limités à une tâche simultanée à la fois. Si vous soumettez une deuxième tâche pendant que la première est en cours, elle sera mise en file d’attente. Pour des limites de concurrence plus élevées, contactez le support pour une offre Entreprise.
Q : Mes données sont-elles privées ?
R : Oui. Les images sources et les vidéos cibles sont utilisées uniquement pour traiter la tâche demandée. Nous n’utilisons pas les données des utilisateurs pour entraîner nos modèles.
Q : Quel est le coût ?
R : Le coût varie selon l’opération (Face Swap, Ralenti, etc.) et la résolution. Des tarifs détaillés sont disponibles sur notre page Tarifs.
Résumé¶
Le SDK iSamurai simplifie l’ajout de fonctionnalités vidéo IA à vos projets Python.
Tutoriels et fonctionnalités connexes¶
- Découvrez l’éditeur visuel : Face Swap Studio PRO UI
- Consultez notre documentation complète pour développeurs : Documentation de l’API
