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
- Cree una cuenta en iSamurai
- Vaya a su página de perfil y genere una clave de API
- Incluya la clave de API en los encabezados de sus solicitudes
- ¡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.
SDK oficial
Wrapper completo de Python con sondeo automático, tipado y manejo de errores.
Ver en GitHub →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)
/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ámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
source_image_base64 | string | Obligatorio | Imagen de rostro de origen codificada en base64 |
target_image_base64 | string | Obligatorio | Fotograma de destino codificado en base64 (de video o imagen) |
instance | UUID | Opcional | ID de una instancia de FaceSwap existente |
enhance | boolean | Opcional | Aplicar 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)
/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ámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
source_image | File | Obligatorio | Archivo de imagen de rostro (JPG/PNG) |
target_media | File | Obligatorio | Archivo de video (MP4/MOV) o imagen |
gquality | string | Obligatorio | 480p, 720p o 1080p |
name | string | Opcional | Nombre del trabajo (máx. 20 caracteres) |
description | string | Opcional | Descripció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
/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
| Estado | Descripción |
|---|---|
Queued | En espera en la cola |
Processing | En procesamiento |
Done | Completado - resultado disponible |
Failed | Se produjo un error |
Cancelled | Cancelado 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
/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)
/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ámetro | Tipo | Descripción |
|---|---|---|
target_image_base64 | string | Fotograma 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)
/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
/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ámetro | Tipo | Descripción |
|---|---|---|
target_media | File | Archivo de video (MP4/MOV) |
gquality | string | 480p, 720p o 1080p |
analysis_results | JSON string | Array con la imagen de origen en base64 para cada rostro |
Paso 4: Consultar progreso
/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
| Factor | Costo por segundo | Caso de uso |
|---|---|---|
| 2x Lento | 2 créditos/seg | Cámara lenta suave |
| 4x Ultra | 3 créditos/seg | Cámara lenta dramática |
| 8x Super | 7 créditos/seg | Cámara lenta extrema |
Crear proyecto de cámara lenta
/api/slowmotion/
Suba un video y configure los ajustes de cámara lenta.
Parámetros de la solicitud (multipart/form-data)
| Parámetro | Tipo | Opciones | Descripción |
|---|---|---|---|
source_video | File | - | Video a ralentizar (MP4/MOV) |
slowdown_factor | int | 2, 4, 8 | Cuánto ralentizar |
quality | string | 480p, 720p, 1080p | Calidad de salida |
mode | string | slowmo, fps | slowmo = 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
/api/faceswap/slowmotion/process/
Inicie el procesamiento de cámara lenta.
{ "project_id": "uuid" }
/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.
/api/restore-image/
Procese una imagen con restauración o mejora mediante IA.
Parámetros de la solicitud (multipart/form-data)
| Parámetro | Tipo | Opciones |
|---|---|---|
image | File | Imagen JPG/PNG |
mode | string | restore 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.
/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"
}
🖼️ API de galería
Administre sus imágenes de origen subidas. Suba las imágenes una vez y reutilícelas en varios trabajos de intercambio de rostros.
Subir imágenes de origen
/api/gallery/sources/
Suba una o más imágenes de origen a su galería. Utilice multipart/form-data con el campo images.
Parámetros de la solicitud (multipart/form-data)
| Parámetro | Tipo | Descripción |
|---|---|---|
images | File(s) | Uno o más archivos de imagen (JPG/PNG). Repita el campo para subir varios archivos. |
import requests
API_KEY = "isk_your_api_key_here"
BASE_URL = "https://isamur.ai/api"
# Subir varias imágenes
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']}")
Respuesta
{
"message": "2 images uploaded successfully",
"images": [
{"id": "uuid-1", "name": "face1.jpg", "url": "/media/sources/..."},
{"id": "uuid-2", "name": "face2.jpg", "url": "/media/sources/..."}
]
}
Listar imágenes de origen
/api/gallery/sources/
Liste sus imágenes de origen subidas con paginación.
Parámetros de consulta
| Parámetro | Por defecto | Descripción |
|---|---|---|
page | 1 | Número de página |
per_page | 20 | Elementos por página (máx. 50) |
Respuesta
{
"images": [{"id": "uuid", "name": "face.jpg", "url": "..."}],
"has_next": true,
"total": 45
}
Eliminar imágenes de origen
/api/gallery/sources/{image_id}/
Elimine una única imagen de origen por su ID.
/api/gallery/sources/bulk-delete/
Elimine varias imágenes de origen a la vez.
{"ids": ["uuid-1", "uuid-2", "uuid-3"]}
Vistas previas (intercambios generados)
/api/gallery/previews/
Liste las imágenes de vista previa guardadas de sus operaciones de intercambio de rostros.
⚠️ 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 estado | Significado | Acción |
|---|---|---|
| 400 | Solicitud incorrecta | Compruebe los parámetros de la solicitud |
| 401 | No autorizado | Compruebe que la clave de API sea válida |
| 403 | Prohibido | Créditos o permisos insuficientes |
| 404 | No encontrado | El recurso no existe |
| 500 | Error del servidor | Contacte 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.