Saltar a la navegación
Guías de API

Procesamiento por lotes

Procese múltiples generaciones de sincronización labial de manera eficiente

El Sync Labs API de lotes procesa hasta 500 lip sync generaciones en una sola solicitud utilizando un archivo JSONL. Esto es ideal para flujos de trabajo de procesamiento de videos masivos, como campañas de videos personalizados, localización de contenido o cualquier escenario que requiera generación de lip sync de gran volumen.

¿Cuál es el formato del archivo por lotes?

El procesamiento Batch le permite enviar de 20 a 500 generaciones sin tener que manejar las colas o la simultaneidad usted mismo, con un tiempo de respuesta objetivo de 24 horas. Los trabajos Batch superan el límite de simultaneidad de generación normal, pero API de lotes solo está disponible en los planes Scale y Enterprise. A partir de ahora, solo se admiten generaciones con entradas de hasta 30 segundos en el procesamiento batch.

API de lotes está disponible solo para usuarios de Scale y Enterprise

Batch límites de concurrencia

Los trabajos Batch superan su límite normal de simultaneidad por generación, pero un separate limit limita la cantidad de batchs que puede ejecutar a la vez, según su plan. Si envía un nuevo batch mientras ya está en ese límite, API devuelve una respuesta 429 Too Many Requests.

El cuerpo 429 es un objeto JSON que describe el límite alcanzado:

{
  "statusCode": 429,
  "errorCode": "concurrency_limit_reached",
  "message": "Batch concurrency limit reached. Please wait for an existing batch to complete or upgrade your plan.",
  "activeBatches": 3,
  "concurrencyLimit": 3,
  "retryAfterSeconds": 20
}

La respuesta también incluye un encabezado Retry-After (en segundos) y un encabezado X-Sync-Concurrency-Limit. En lugar de volver a intentarlo inmediatamente, espere retryAfterSeconds antes de volver a enviarlo, o espere a que se complete uno de sus batchs en vuelo.

¿Cómo creo un trabajo por lotes?

1

Prepare su archivo de entrada

Cree un archivo JSON Lines (.jsonl) con sus solicitudes de generación. Cada línea debe contener un request_id único, el endpoint (debe ser "/v2/generate") y un payload con el formato de solicitud de generación estándar (igual que Generar API). El archivo debe estar en formato JSON Líneas (.jsonl) con un mínimo de 20 registros, un tamaño de archivo máximo de 5 MB y hasta 500 solicitudes por batch.

input.jsonl
{"request_id": "request-1", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}, {"type": "audio", "url": "https://assets.sync.so/docs/example-audio.wav"}]}}
{"request_id": "request-2", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}, {"type": "audio", "url": "https://assets.sync.so/docs/example-audio.wav"}]}}
2

Crea un Batch

from sync import Sync
sync = Sync()
batch = sync.batch.create(
    input=open("input.jsonl", "rb")
)
print(f"Batch created with ID: {batch.id}")

Parámetros opcionales:

  • webhook_url: reciba notificaciones cuando se complete batch
  • dry_run: configúrelo en true para validar su archivo de entrada sin procesar
3

Verifique el estado de Batch

Supervise su progreso batch sondeando el estado:

batch = sync.batch.get(batch_id)
print(f"Status: {batch.status}")
print(f"Progress: {batch.metrics}")

Un batch puede tener uno de los siguientes estados:

  1. PENDING: Batch creado, esperando comenzar a procesar
  2. PROCESSING: Se están procesando generaciones
  3. COMPLETED: Todas las generaciones terminadas (con éxito o con fracasos)
  4. FAILED: Batch el procesamiento falló por completo
4

Verifique los resultados de Batch

Cuando se completa un batch, los resultados están disponibles como un archivo de líneas JSON en el outputUrl de la respuesta de obtención batch. Un GET a ese URL devuelve una redirección 302 a un archivo de resultados firmado; Los clientes que siguen redireccionamientos automáticamente pueden leer la respuesta JSONL directamente. Cada línea contiene:

output.jsonl
{"request_id": "request-1", "endpoint": "/v2/generate", "payload": {...}, "status": "COMPLETED", "error": null, "response": {...}, "updated_at": "2024-01-15T10:35:00Z"}
{"request_id": "request-2", "endpoint": "/v2/generate", "payload": {...}, "status": "FAILED", "error": {"code": "INVALID_INPUT", "message": "..."}, "response": null, "updated_at": "2024-01-15T10:35:00Z"}

El campo response contiene los mismos datos que las respuestas individuales Generar API.

Para obtener un ejemplo funcional completo, consulte el batch ejemplo de procesamiento en nuestro repositorio de ejemplos.

Webhook Notificaciones

Cuando proporcionas un webhook_url, recibirás notificaciones POST cuando tu batch se complete:

webhook_payload.json
{
  "id": "batch_abc123",
  "createdAt": "2024-01-15T10:30:00Z",
  "status": "COMPLETED",
  "webhookUrl": "https://your-webhook-url.com/batch-webhook",
  "metrics": {
    "totalGenerations": 5,
    "successCount": 4,
    "failedCount": 1,
    "pendingCount": 0
  },
  "options": {},
  "outputUrl": "https://api.sync.so/v2/batches/batch_abc123/result"
}

Recursos relacionados

  • Rate Limits — comprenda API rate limit para planificar sus tamaños de batch de manera efectiva
  • Webhooks Guide — configura webhook notificaciones para batch eventos de finalización
  • Manejo de errores — referencia para códigos de error y solución de problemas específicos de batch