Documentación de la API de Face Swap de iSamurai

Guía completa para desarrolladores sobre cómo integrar intercambio de rostros con IA, video a cámara lenta y restauración de imágenes en sus aplicaciones.

🚀 Primeros pasos

La API de iSamurai proporciona acceso programático a nuestro conjunto de herramientas de procesamiento de video e imagen con IA. Ya sea que esté creando una plataforma de creación de contenido, integrando tecnología de intercambio de rostros en su aplicación, o añadiendo efectos cinematográficos de cámara lenta, nuestra API RESTful lo hace sencillo.

URL base

https://isamur.ai/api/

Pasos de inicio rápido

  1. Cree una cuenta en iSamurai
  2. Vaya a su página de perfil y genere una clave de API
  3. Incluya la clave de API en los encabezados de sus solicitudes
  4. ¡Empiece a realizar llamadas a la API!
💡

Sistema de créditos: Todas las operaciones de procesamiento consumen créditos. Compruebe su saldo en /api/user-credits/ antes de enviar trabajos. Consulte nuestros planes de precios para conocer los paquetes de créditos.

📦 SDK y herramientas

Acelere su desarrollo con nuestras bibliotecas cliente oficiales y ejemplos de código.

Python

SDK oficial

Wrapper completo de Python con sondeo automático, tipado y manejo de errores.

Ver en GitHub →
Código

Ejemplos de API

Scripts y ejemplos de uso para integración directa con la API.

Ver en GitHub →

🔐 Autenticación

Todos los endpoints de la API requieren autenticación. Incluya sus credenciales en el encabezado Authorization en cada solicitud.

Autenticación con clave de API (recomendado)

Las claves de API son el método de autenticación recomendado para integraciones servidor a servidor. Las claves nunca caducan y ofrecen una forma simple y segura de acceder a todos los endpoints.

curl -H "Authorization: Api-Key isk_your_api_key_here" \
  https://isamur.ai/api/user-credits/

🎭 API de Face Swap

La API de Face Swap le permite intercambiar rostros en videos e imágenes de forma fluida. Utilice el endpoint de vista previa para probar primero con un solo fotograma y, después, procese el video completo.

Vista previa rápida (un solo fotograma)

POST /api/preview-swap-api/

Genere una vista previa de un solo fotograma del intercambio de rostros antes de procesar el video completo. Utiliza imágenes codificadas en base64. Cuesta aproximadamente 1-2 créditos.

Cuerpo de la solicitud (JSON)

ParámetroTipoObligatorioDescripción
source_image_base64stringObligatorioImagen de rostro de origen codificada en base64
target_image_base64stringObligatorioFotograma de destino codificado en base64 (de video o imagen)
instanceUUIDOpcionalID de una instancia de FaceSwap existente
enhancebooleanOpcionalAplicar mejora facial (por defecto: false)
import requests
import base64

API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"

# Convertir imágenes a base64
def to_base64(file_path):
    with open(file_path, "rb") as f:
        return base64.b64encode(f.read()).decode()

# Generar vista previa
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
    }
)

# Guardar imagen de vista previa
preview_base64 = response.json()["image_base64"]
with open("preview.jpg", "wb") as f:
    f.write(base64.b64decode(preview_base64))

Respuesta

{
  "image_base64": "/9j/4AAQSkZJRgABAQAAAQ...",
  "preview_id": "abc123"
}

Procesamiento completo de video (subida y procesamiento combinados)

POST /api/full-process-swap/

Suba los archivos e inicie el procesamiento inmediatamente en una sola solicitud. Este es el endpoint recomendado para flujos de trabajo automatizados. Se descuentan aproximadamente 50 créditos por minuto de video.

Parámetros de la solicitud (multipart/form-data)

ParámetroTipoObligatorioDescripción
source_imageFileObligatorioArchivo de imagen de rostro (JPG/PNG)
target_mediaFileObligatorioArchivo de video (MP4/MOV) o imagen
gqualitystringObligatorio480p, 720p o 1080p
namestringOpcionalNombre del trabajo (máx. 20 caracteres)
descriptionstringOpcionalDescripción (máx. 20 caracteres)
import requests

API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"

# Subir archivos locales e iniciar el procesamiento
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}")

Consultar progreso

GET /api/swap-progress/?id={instance_id}

Consulte este endpoint periódicamente para supervisar el progreso del trabajo hasta que el estado sea Done.

Valores de estado

EstadoDescripción
QueuedEn espera en la cola
ProcessingEn procesamiento
DoneCompletado - resultado disponible
FailedSe produjo un error
CancelledCancelado por el usuario
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)

Detener/Cancelar trabajo

POST /api/stop-job/

Cancele un trabajo en ejecución. Recibirá un reembolso del 50% de los créditos.

{"id": "instance_uuid", "type": "faceswap"}

👥 API de intercambio de rostros múltiple

Intercambie varios rostros en un solo video. Analice el fotograma para detectar todos los rostros, asigne imágenes de origen a cada uno y, después, procese.

Paso 1: Analizar fotograma (detectar rostros)

POST /api/analyse-frame/

Detecte todos los rostros en un fotograma de video. Envíe un fotograma codificado en base64 de su video de destino.

Cuerpo de la solicitud (JSON)

ParámetroTipoDescripción
target_image_base64stringFotograma codificado en base64 del video de destino
import base64

# Capturar un fotograma de tu video (usando 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']}")

Respuesta

{
  "analysis": [
    {"person_id": "P1", "thumbnail": "base64...", "bbox": [x, y, w, h]},
    {"person_id": "P2", "thumbnail": "base64...", "bbox": [x, y, w, h]}
  ]
}

Paso 2: Vista previa del intercambio múltiple (opcional)

POST /api/multi-preview-swap-api/

Obtenga una vista previa del intercambio de rostros múltiple en un solo fotograma antes del procesamiento completo.

Cuerpo de la solicitud (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
}

Respuesta

{"preview_image": "base64_result..."}

Paso 3: Procesamiento completo multi-rostro

POST /api/multiple-face-swap/

Procese el video completo con todas las asignaciones de rostros. Utilice multipart/form-data.

Parámetros de la solicitud (multipart/form-data)

ParámetroTipoDescripción
target_mediaFileArchivo de video (MP4/MOV)
gqualitystring480p, 720p o 1080p
analysis_resultsJSON stringArray con la imagen de origen en base64 para cada rostro

Paso 4: Consultar progreso

GET /api/swap-progress/?id={instance_id}&multi=True

Consulte el progreso periódicamente. Añada multi=True para trabajos de intercambio de rostros múltiple.

⏱️ API de cámara lenta y aumento de FPS

Cree impresionantes videos a cámara lenta mediante interpolación de fotogramas con IA. Nuestra tecnología de cámara lenta genera nuevos fotogramas entre los existentes, lo que le permite ralentizar el metraje hasta 8x manteniendo un movimiento fluido y suave.

Precios en créditos

FactorCosto por segundoCaso de uso
2x Lento2 créditos/segCámara lenta suave
4x Ultra3 créditos/segCámara lenta dramática
8x Super7 créditos/segCámara lenta extrema

Crear proyecto de cámara lenta

POST /api/slowmotion/

Suba un video y configure los ajustes de cámara lenta.

Parámetros de la solicitud (multipart/form-data)

ParámetroTipoOpcionesDescripción
source_videoFile-Video a ralentizar (MP4/MOV)
slowdown_factorint2, 4, 8Cuánto ralentizar
qualitystring480p, 720p, 1080pCalidad de salida
modestringslowmo, fpsslowmo = video más lento, fps = video más fluido
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']}")

Iniciar procesamiento

POST /api/faceswap/slowmotion/process/

Inicie el procesamiento de cámara lenta.

{ "project_id": "uuid" }
GET /api/faceswap/slowmotion/progress/{project_id}/

Consulte el progreso del procesamiento de cámara lenta.

✨ API de restauración y mejora de imágenes

Restaure fotos antiguas y dañadas o mejore la calidad de los rostros con nuestra herramienta de restauración de imágenes impulsada por IA. Perfecta para dar nueva vida a fotografías antiguas o mejorar imágenes de rostros de baja resolución.

POST /api/restore-image/

Procese una imagen con restauración o mejora mediante IA.

Parámetros de la solicitud (multipart/form-data)

ParámetroTipoOpciones
imageFileImagen JPG/PNG
modestringrestore o face_enhance

Respuesta

{
  "url": "/api/media/restored/output.jpg",
  "image_base64": "/9j/4AAQSkZ...",
  "status": "success"
}

💳 API de usuario y créditos

Supervise su saldo de créditos y el estado de su cuenta. Compruebe sus créditos antes de enviar trabajos para asegurarse de tener saldo suficiente. Consulte nuestros planes de precios para comprar más créditos.

GET /api/user-credits/

Obtenga su saldo de créditos actual e información del plan.

Respuesta

{
  "user_id": 123,
  "user_credits": 9500,
  "plan_id": 5,
  "plan_name": "Samurai"
}

⚠️ Manejo de errores

Todos los errores de la API devuelven una estructura JSON coherente con un mensaje de error. Utilice los códigos de estado HTTP para determinar el tipo de error.

Código de estadoSignificadoAcción
400Solicitud incorrectaCompruebe los parámetros de la solicitud
401No autorizadoCompruebe que la clave de API sea válida
403ProhibidoCréditos o permisos insuficientes
404No encontradoEl recurso no existe
500Error del servidorContacte con soporte

Formato de respuesta de error

{
  "error": "Insufficient credits: need 500, have 200",
  "success": false
}

🚦 Límites de tasa

Cada usuario puede ejecutar un solo trabajo concurrente a la vez. Espere a que su trabajo actual finalice antes de enviar uno nuevo. Si envía un nuevo trabajo mientras otro se está procesando, quedará en cola.

📚 Ejemplos de código completos

Ejemplos completos y funcionales para casos de uso habituales.

Python: flujo de trabajo completo 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"):
    # Paso 1: Subir
    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"]

    # Paso 2: Procesar
    requests.post(f"{BASE_URL}/process-swap/",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"instance": job_id})

    # Paso 3: Esperar a que finalice
    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)

# Uso
output = face_swap("face.jpg", "video.mp4")
print(f"Result: https://isamur.ai{output}")

JavaScript: flujo de trabajo completo de Face Swap

const API_KEY = "isk_your_key_here";
const BASE_URL = "https://isamur.ai/api";

async function faceSwap(sourceFile, targetFile, quality = "720p") {
    // Paso 1: Subir
    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;

    // Paso 2: Procesar
    await fetch(`${BASE_URL}/process-swap/`, {
        method: "POST",
        headers: {
            "Authorization": `Api-Key ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({ instance: jobId })
    });

    // Paso 3: Consultar hasta finalizar
    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));
    }
}

¿Listo para empezar? Cree su cuenta y genere una clave de API desde su página de perfil.