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

  1. Créez un compte sur iSamurai
  2. Rendez-vous sur votre page de profil et générez une clé API
  3. Incluez la clé API dans les en-têtes de vos requêtes
  4. 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.

Python

SDK officiel

Wrapper Python complet avec polling automatique, typage et gestion des erreurs.

Voir sur GitHub →
Code

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)

POST /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ètreTypeRequisDescription
source_image_base64stringRequisImage source du visage, encodée en base64
target_image_base64stringRequisImage cible encodée en base64 (issue d'une vidéo ou d'une image)
instanceUUIDOptionnelID d'une instance FaceSwap existante
enhancebooleanOptionnelAppliquer 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)

POST /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ètreTypeRequisDescription
source_imageFichierRequisFichier image du visage (JPG/PNG)
target_mediaFichierRequisFichier vidéo (MP4/MOV) ou image
gqualitystringRequis480p, 720p, ou 1080p
namestringOptionnelNom de la tâche (20 caractères max)
descriptionstringOptionnelDescription (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

GET /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

StatutDescription
QueuedEn attente dans la file
ProcessingEn cours de traitement
DoneTerminé - le résultat est disponible
FailedUne erreur est survenue
CancelledAnnulé 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

POST /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)

POST /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ètreTypeDescription
target_image_base64stringImage 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)

POST /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

POST /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ètreTypeDescription
target_mediaFichierFichier vidéo (MP4/MOV)
gqualitystring480p, 720p, ou 1080p
analysis_resultsChaîne JSONTableau avec l'image source en base64 pour chaque visage

Étape 4 : Vérifier la progression

GET /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

FacteurCoût par secondeCas d'usage
Ralenti 2x2 crédits/secRalenti fluide
Ultra 4x3 crédits/secRalenti dramatique
Super 8x7 crédits/secRalenti extrême

Créer un projet de ralenti

POST /api/slowmotion/

Envoyez une vidéo et configurez les paramètres de ralenti.

Paramètres de la requête (multipart/form-data)

ParamètreTypeOptionsDescription
source_videoFichier-Vidéo à ralentir (MP4/MOV)
slowdown_factorint2, 4, 8Facteur de ralenti
qualitystring480p, 720p, 1080pQualité de sortie
modestringslowmo, fpsslowmo = 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

POST /api/faceswap/slowmotion/process/

Démarrez le traitement du ralenti.

{ "project_id": "uuid" }
GET /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.

POST /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ètreTypeOptions
imageFichierImage JPG/PNG
modestringrestore 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.

GET /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"
}

⚠️ 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 statutSignificationAction
400Requête invalideVérifiez les paramètres de la requête
401Non autoriséVérifiez que la clé API est valide
403InterditCrédits ou permissions insuffisants
404IntrouvableLa ressource n'existe pas
500Erreur serveurContactez 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.