Introducción¶
Esta guía ofrece un recorrido técnico para integrar la API de iSamurai en tus aplicaciones Python.
El SDK de Python de iSamurai encapsula nuestra API REST, gestionando tareas complejas como la subida de archivos, el sondeo de resultados y el manejo de errores. Con este SDK, puedes procesar videos usando nuestras GPU en la nube sin gestionar tu propia infraestructura.
Este tutorial cubre:
1. Instalación y configuración
2. Face Swap (de una cara y multicara)
3. Generación de Cámara Lenta
4. Buenas prácticas para producción
1. Instalación y configuración¶
Requisitos¶
- Python 3.8 o superior.
- Una clave de API de iSamurai (disponible en tu Perfil de desarrollador).
Instalar el SDK¶
Instala el paquete oficial directamente desde GitHub usando pip:
pip install git+https://github.com/isamurai-ai/iSamurai-SDK.git
Autenticación¶
Inicializa el cliente con tu clave de API. Recomendamos usar variables de entorno por seguridad.
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 función principal de la API es sustituir una cara en un video o imagen de destino por una cara de origen.
Face Swap básico de una sola cara¶
Este ejemplo muestra el flujo de trabajo estándar: subir archivos, enviar un trabajo y esperar el resultado.
# 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}")
Avanzado: Face Swap multicara¶
Si tu video de destino contiene varias personas, es posible que quieras intercambiar caras específicas y dejar las demás sin cambios.
Paso 1: Analizar el video¶
Primero, detecta las caras en el video de destino para obtener sus ID.
# 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']}")
Paso 2: Crear un mapeo¶
Asocia el person_id detectado con la imagen de origen que desees.
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")
})
Paso 3: Procesar¶
Envía el mapeo al endpoint de intercambio multicara.
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. Crear Cámara Lenta con IA¶
Puedes usar la API para generar cámara lenta de alta tasa de fotogramas a partir de metraje estándar. Esto utiliza interpolación de fotogramas con IA para crear un movimiento fluido.
# 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
Combinar funciones¶
Un flujo de trabajo habitual consiste en encadenar estas operaciones:
1. Intercambiar cara: procesa un video para cambiar la identidad.
2. Aplicar Cámara Lenta: toma la URL de salida del paso 1 y envíala a la API de Cámara Lenta.
4. Buenas prácticas¶
Usar la Galería¶
Si usas la misma imagen de origen con frecuencia (por ejemplo, la foto de perfil de un usuario), no la subas en cada solicitud. Súbela una vez a la Galería para ahorrar ancho de banda.
# Upload once
client.upload_to_gallery(["profile.jpg"])
# (Future SDK updates will allow referencing these IDs directly)
Sondeo eficiente¶
El asistente wait_for_job es útil para scripts, pero para aplicaciones web en producción deberías usar Webhooks. Esto permite que tu servidor reciba una notificación en cuanto un trabajo termina, en lugar de mantener una conexión abierta.
Consulta la Documentación de la API para la configuración de webhooks.
Gestión de errores¶
Envuelve siempre tus llamadas a la API en bloques try/except. Los errores comunes incluyen:
* 402 Payment Required: créditos insuficientes.
* 400 Bad Request: formatos de archivo o parámetros no válidos.
5. Preguntas frecuentes (FAQ)¶
P: ¿Puedo usar la API para aplicaciones comerciales?
R: Sí. Conservas todos los derechos comerciales sobre el contenido generado con la API de iSamurai. Puedes crear productos SaaS, aplicaciones móviles o herramientas internas usando nuestra infraestructura.
P: ¿Cuáles son los límites de velocidad?
R: De forma predeterminada, las cuentas están limitadas a un trabajo simultáneo a la vez. Si envías un segundo trabajo mientras el primero se está ejecutando, quedará en cola. Para límites de concurrencia más altos, contacta con soporte para un plan Enterprise.
P: ¿Son privados mis datos?
R: Sí. Las imágenes de origen y los videos de destino se usan únicamente para procesar el trabajo solicitado. No usamos los datos de los usuarios para entrenar nuestros modelos.
P: ¿Cuánto cuesta?
R: Los costes varían según la operación (Face Swap, Cámara Lenta, etc.) y la resolución. Encontrarás más detalles en nuestra página de precios.
Resumen¶
El SDK de iSamurai simplifica añadir funciones de video con IA a tus proyectos Python.
Tutoriales y funciones relacionadas¶
- Consulta el editor visual: Face Swap Studio PRO UI
- Lee nuestra documentación completa para desarrolladores: Documentación de la API
