Documentation de l'API iSamurai Face Swap
Guide complet pour développeurs afin d'intégrer le face swap propulsé par l'IA, la vidéo au ralenti, et la restauration d'images dans vos applications.
🚀 Pour commencer
L'API iSamurai offre un accès programmatique à notre suite d'outils de traitement vidéo et image propulsés par l'IA. Que vous construisiez une plateforme de création de contenu, que vous intégriez la technologie de face swap dans votre application, ou que vous ajoutiez des effets de ralenti cinématique, notre API RESTful rend tout cela simple.
URL de base
https://isamur.ai/api/
Étapes de démarrage rapide
- Créez un compte sur iSamurai
- Rendez-vous sur votre page de profil et générez une clé API
- Incluez la clé API dans les en-têtes de vos requêtes
- Commencez à effectuer des appels API !
Système de crédits : Toutes les opérations de traitement consomment des crédits. Vérifiez votre solde à l'adresse /api/user-credits/ avant de soumettre des tâches. Consultez nos formules tarifaires pour les packs de crédits.
📦 SDK & Outils
Accélérez votre développement grâce à nos bibliothèques clientes officielles et à nos exemples de code.
SDK officiel
Wrapper Python complet avec polling automatique, typage et gestion des erreurs.
Voir sur GitHub →Exemples d'API
Scripts bruts et exemples d'utilisation pour une intégration directe de l'API.
Voir sur GitHub →🔐 Authentification
Tous les endpoints de l'API nécessitent une authentification. Incluez vos identifiants dans l'en-tête Authorization à chaque requête.
Authentification par clé API (recommandée)
Les clés API constituent la méthode d'authentification recommandée pour les intégrations serveur à serveur. Les clés n'expirent jamais et offrent un moyen simple et sécurisé d'accéder à tous les endpoints.
curl -H "Authorization: Api-Key isk_your_api_key_here" \
https://isamur.ai/api/user-credits/
🎭 API Face Swap
L'API Face Swap vous permet d'échanger des visages en toute fluidité dans des vidéos et des images. Utilisez d'abord l'endpoint d'aperçu pour tester avec une seule image, puis traitez la vidéo complète.
Aperçu rapide (image unique)
/api/preview-swap-api/
Générez un aperçu du face swap sur une seule image avant de traiter la vidéo complète. Utilise des images encodées en base64. Coûte environ 1 à 2 crédits.
Corps de la requête (JSON)
| Paramètre | Type | Requis | Description |
|---|---|---|---|
source_image_base64 | string | Requis | Image source du visage, encodée en base64 |
target_image_base64 | string | Requis | Image cible encodée en base64 (issue d'une vidéo ou d'une image) |
instance | UUID | Optionnel | ID d'une instance FaceSwap existante |
enhance | boolean | Optionnel | Appliquer l'amélioration du visage (par défaut : false) |
import requests
import base64
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# Convertir les images en base64
def to_base64(file_path):
with open(file_path, "rb") as f:
return base64.b64encode(f.read()).decode()
# Générer l'aperçu
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
}
)
# Sauvegarder l'image d'aperçu
preview_base64 = response.json()["image_base64"]
with open("preview.jpg", "wb") as f:
f.write(base64.b64decode(preview_base64))
Réponse
{
"image_base64": "/9j/4AAQSkZJRgABAQAAAQ...",
"preview_id": "abc123"
}
Traitement vidéo complet (envoi + traitement combinés)
/api/full-process-swap/
Envoyez les fichiers et démarrez immédiatement le traitement en une seule requête. C'est l'endpoint recommandé pour les workflows automatisés. Les crédits sont déduits à raison d'environ 50 par minute de vidéo.
Paramètres de la requête (multipart/form-data)
| Paramètre | Type | Requis | Description |
|---|---|---|---|
source_image | Fichier | Requis | Fichier image du visage (JPG/PNG) |
target_media | Fichier | Requis | Fichier vidéo (MP4/MOV) ou image |
gquality | string | Requis | 480p, 720p, ou 1080p |
name | string | Optionnel | Nom de la tâche (20 caractères max) |
description | string | Optionnel | Description (20 caractères max) |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# Envoyer les fichiers locaux et démarrer le traitement
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}")
Vérifier la progression
/api/swap-progress/?id={instance_id}
Interrogez cet endpoint pour suivre la progression de la tâche jusqu'à ce que le statut soit Done.
Valeurs de statut
| Statut | Description |
|---|---|
Queued | En attente dans la file |
Processing | En cours de traitement |
Done | Terminé - le résultat est disponible |
Failed | Une erreur est survenue |
Cancelled | Annulé par l'utilisateur |
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)
Arrêter/Annuler une tâche
/api/stop-job/
Annulez une tâche en cours. Vous recevez un remboursement de 50 % des crédits.
{"id": "instance_uuid", "type": "faceswap"}
👥 API Multi-Face Swap
Échangez plusieurs visages dans une seule vidéo. Analysez l'image pour détecter tous les visages, associez des images source à chacun, puis lancez le traitement.
Étape 1 : Analyser une image (détection des visages)
/api/analyse-frame/
Détectez tous les visages dans une image de la vidéo. Envoyez une image encodée en base64 extraite de votre vidéo cible.
Corps de la requête (JSON)
| Paramètre | Type | Description |
|---|---|---|
target_image_base64 | string | Image encodée en base64 extraite de la vidéo cible |
import base64
# Capturer une image depuis votre vidéo (avec OpenCV, ffmpeg, etc.)
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']}")
Réponse
{
"analysis": [
{"person_id": "P1", "thumbnail": "base64...", "bbox": [x, y, w, h]},
{"person_id": "P2", "thumbnail": "base64...", "bbox": [x, y, w, h]}
]
}
Étape 2 : Aperçu du multi-swap (optionnel)
/api/multi-preview-swap-api/
Prévisualisez le multi-face swap sur une seule image avant le traitement complet.
Corps de la requête (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
}
Réponse
{"preview_image": "base64_result..."}
Étape 3 : Traitement multi-visages complet
/api/multiple-face-swap/
Traitez la vidéo complète avec toutes les correspondances de visages. Utilisez multipart/form-data.
Paramètres de la requête (multipart/form-data)
| Paramètre | Type | Description |
|---|---|---|
target_media | Fichier | Fichier vidéo (MP4/MOV) |
gquality | string | 480p, 720p, ou 1080p |
analysis_results | Chaîne JSON | Tableau avec l'image source en base64 pour chaque visage |
Étape 4 : Vérifier la progression
/api/swap-progress/?id={instance_id}&multi=True
Interrogez la progression. Ajoutez multi=True pour les tâches de multi-face swap.
⏱️ API Ralenti & Boost FPS
Créez de superbes vidéos au ralenti grâce à l'interpolation d'images par IA. Notre technologie de ralenti génère de nouvelles images entre les images existantes, ce qui vous permet de ralentir vos vidéos jusqu'à 8x tout en conservant un mouvement fluide.
Tarification en crédits
| Facteur | Coût par seconde | Cas d'usage |
|---|---|---|
| Ralenti 2x | 2 crédits/sec | Ralenti fluide |
| Ultra 4x | 3 crédits/sec | Ralenti dramatique |
| Super 8x | 7 crédits/sec | Ralenti extrême |
Créer un projet de ralenti
/api/slowmotion/
Envoyez une vidéo et configurez les paramètres de ralenti.
Paramètres de la requête (multipart/form-data)
| Paramètre | Type | Options | Description |
|---|---|---|---|
source_video | Fichier | - | Vidéo à ralentir (MP4/MOV) |
slowdown_factor | int | 2, 4, 8 | Facteur de ralenti |
quality | string | 480p, 720p, 1080p | Qualité de sortie |
mode | string | slowmo, fps | slowmo = vidéo plus lente, fps = vidéo plus fluide |
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']}")
Démarrer le traitement
/api/faceswap/slowmotion/process/
Démarrez le traitement du ralenti.
{ "project_id": "uuid" }
/api/faceswap/slowmotion/progress/{project_id}/
Vérifiez la progression du traitement du ralenti.
✨ API de restauration et d'amélioration d'image
Restaurez des photos anciennes ou endommagées, ou améliorez la qualité des visages grâce à notre outil de restauration d'image propulsé par l'IA. Parfait pour redonner vie à des photographies anciennes ou pour améliorer des images de visages en basse résolution.
/api/restore-image/
Traitez une image avec la restauration ou l'amélioration par IA.
Paramètres de la requête (multipart/form-data)
| Paramètre | Type | Options |
|---|---|---|
image | Fichier | Image JPG/PNG |
mode | string | restore ou face_enhance |
Réponse
{
"url": "/api/media/restored/output.jpg",
"image_base64": "/9j/4AAQSkZ...",
"status": "success"
}
💳 API Utilisateur & Crédits
Surveillez votre solde de crédits et le statut de votre compte. Vérifiez vos crédits avant de soumettre des tâches afin de vous assurer d'avoir un solde suffisant. Consultez nos formules tarifaires pour acheter davantage de crédits.
/api/user-credits/
Récupérez votre solde de crédits actuel et les informations de votre plan.
Réponse
{
"user_id": 123,
"user_credits": 9500,
"plan_id": 5,
"plan_name": "Samurai"
}
🖼️ API Galerie
Gérez vos images source téléversées. Téléversez vos images une seule fois et réutilisez-les pour plusieurs tâches de face swap.
Téléverser des images source
/api/gallery/sources/
Téléversez une ou plusieurs images source dans votre galerie. Utilisez multipart/form-data avec le champ images.
Paramètres de la requête (multipart/form-data)
| Paramètre | Type | Description |
|---|---|---|
images | Fichier(s) | Une ou plusieurs images (JPG/PNG). Répétez le champ pour téléverser plusieurs fichiers. |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# Téléverser plusieurs images
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']}")
Réponse
{
"message": "2 images uploaded successfully",
"images": [
{"id": "uuid-1", "name": "face1.jpg", "url": "/media/sources/..."},
{"id": "uuid-2", "name": "face2.jpg", "url": "/media/sources/..."}
]
}
Lister les images source
/api/gallery/sources/
Listez vos images source téléversées avec pagination.
Paramètres de requête
| Paramètre | Par défaut | Description |
|---|---|---|
page | 1 | Numéro de page |
per_page | 20 | Éléments par page (50 max) |
Réponse
{
"images": [{"id": "uuid", "name": "face.jpg", "url": "..."}],
"has_next": true,
"total": 45
}
Supprimer des images source
/api/gallery/sources/{image_id}/
Supprimez une seule image source par ID.
/api/gallery/sources/bulk-delete/
Supprimez plusieurs images source en une seule fois.
{"ids": ["uuid-1", "uuid-2", "uuid-3"]}
Aperçus (swaps générés)
/api/gallery/previews/
Listez vos images d'aperçu enregistrées issues des opérations de face swap.
⚠️ Gestion des erreurs
Toutes les erreurs de l'API renvoient une structure JSON cohérente avec un message d'erreur. Utilisez les codes de statut HTTP pour déterminer le type d'erreur.
| Code de statut | Signification | Action |
|---|---|---|
| 400 | Requête invalide | Vérifiez les paramètres de la requête |
| 401 | Non autorisé | Vérifiez que la clé API est valide |
| 403 | Interdit | Crédits ou permissions insuffisants |
| 404 | Introuvable | La ressource n'existe pas |
| 500 | Erreur serveur | Contactez le support |
Format de la réponse d'erreur
{
"error": "Insufficient credits: need 500, have 200",
"success": false
}
🚦 Limites de fréquence
Chaque utilisateur peut exécuter une seule tâche simultanée à la fois. Attendez la fin de votre tâche en cours avant d'en soumettre une nouvelle. Si vous soumettez une nouvelle tâche alors qu'une autre est en cours de traitement, elle sera mise en file d'attente.
📚 Exemples de code complets
Exemples fonctionnels complets pour les cas d'usage courants.
Python : Workflow complet de Face Swap
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"):
# Étape 1 : Envoi
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"]
# Étape 2 : Traitement
requests.post(f"{BASE_URL}/process-swap/",
headers={**HEADERS, "Content-Type": "application/json"},
json={"instance": job_id})
# Étape 3 : Attente de la fin du traitement
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)
# Utilisation
output = face_swap("face.jpg", "video.mp4")
print(f"Result: https://isamur.ai{output}")
JavaScript : Workflow complet de Face Swap
const API_KEY = "isk_your_key_here";
const BASE_URL = "https://isamur.ai/api";
async function faceSwap(sourceFile, targetFile, quality = "720p") {
// Étape 1 : Envoi
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;
// Étape 2 : Traitement
await fetch(`${BASE_URL}/process-swap/`, {
method: "POST",
headers: {
"Authorization": `Api-Key ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ instance: jobId })
});
// Étape 3 : Attente de la fin du traitement
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));
}
}
Prêt à commencer ? Créez votre compte et générez une clé API depuis votre page de profil.