Procesamiento por lotes

El Sync Labs API de lotes procesa hasta 500 lip sync generaciones en una sola solicitud, enviada como un archivo JSONL o como un arreglo JSON de filas. Está pensada para grandes tandas de clips cortos, como campañas de videos personalizados o localización de contenido, en las que los resultados pueden llegar a lo largo de varias horas.

¿Quién puede usar la API de lotes?

La API de lotes requiere un plan Scale o superior y aprobación para su organización. El acceso está desactivado de forma predeterminada, incluso con una nueva suscripción a Scale. Contacte con soporte para solicitar acceso. Los usuarios existentes también necesitan aprobación tras una revisión de uso y facturación.

Sin aprobación, la organización recibe 403 con errorCode: batch_access_not_enabled, incluso con dry_run. Con aprobación, los demás planes y las cuentas gratuitas reciben 402 con errorCode: plan_feature_unavailable. requiredPlan es scale, o enterprise en los planes de créditos.

Si se retira el acceso para crear lotes, los lotes aceptados siguen procesándose. Puede consultar su estado y descargar los resultados disponibles.

• Un batch admite de 20 a 500 registros de forma predeterminada, o el límite propio de su cuenta.
• Cada batch activo ocupa un hueco de su límite de batches, que es el límite de concurrencia de su plan. Sus registros no cuentan para la concurrencia de /v2/generate.
• La salida estimada de cada registro puede durar como máximo 30 segundos. Un registro más largo falla en el archivo de resultados con Input files exceed 30s duration, which is not supported in batch mode, mientras el resto del batch se ejecuta.
• Cada registro se factura como la generación que ejecuta.

En una solicitud multipart, envíe exactamente un archivo JSONL en el campo input (file también funciona). Otros campos de archivo o varios archivos devuelven 400. Un error 503 upload_capacity_unavailable no crea ningún batch. Repita la misma solicitud tras el tiempo indicado en Retry-After o envíe un cuerpo JSON con rows.

Cuándo usar batch y cuándo no

Un batch es una canalización con cola. Todos los registros se descargan y se comprueban antes de que empiece ninguno, y los resultados pueden tardar horas, con un plazo objetivo de hasta 24 horas. Úselo para grandes tandas de clips cortos que no necesitan terminar de inmediato.

No es la forma de enviar unas pocas generaciones a la vez. Para eso:

• Envíe solicitudes normales a POST /v2/generate en paralelo, dentro de su límite de concurrencia. Cada una empieza en cuanto se admite.
• O deje que un agente use la herramienta jobs_create-many del servidor MCP de sync. labs, que inicia varios trabajos a la vez a través de la API normal.

Batch límites de concurrencia

Cuando ya ejecuta tantos batches como el límite de concurrencia de su plan, la API devuelve 429 Too Many Requests con errorCode: concurrency_limit_reached:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "errorCode": "concurrency_limit_reached",
  "message": "Batch concurrency limit reached. You have 3 active batches and your plan allows 3. Please wait for existing batches to complete or upgrade your plan for higher limits.",
  "activeBatches": 3,
  "concurrencyLimit": 3,
  "retryAfterSeconds": 20
}

La respuesta incluye un encabezado Retry-After (en segundos) y un encabezado X-Sync-Concurrency-Limit. En lugar de reintentar de inmediato, espere retryAfterSeconds o hasta que termine uno de sus batches activos.

¿Cómo creo un trabajo por lotes?

{"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"}]}}

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

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

{"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"}

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 una notificación POST cuando tu batch se complete o falle. Va firmada con un header Sync-Signature como los webhooks de generación y sigue la misma política de reintentos: hasta 6 intentos durante unas 2 horas, con el mismo header Sync-Delivery-Id en cada intento.

A diferencia de la respuesta de Get Batch, el payload del webhook usa nombres de campo en camelCase:

{
  "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"
}

El webhook de finalización puede entregarse más de una vez para el mismo batch. Use el header Sync-Delivery-Id o el id del batch para ignorar las notificaciones que ya haya procesado.

Filas de edición de diálogo (acceso anticipado)

Una fila de batch puede renderizar una vista previa de edición de diálogo completada en lugar de combinar un video con un audio nuevo. Utilícelo para convertir un video grabado en muchas variantes, por ejemplo una por cada nombre de destinatario. Mensajes de video personalizados incluye un script completo.

El payload de cada fila contiene:

• model, por ejemplo sync-3.
• input con exactamente un video: el mismo video de origen a partir del cual se creó la vista previa.
• dialogueEdit: {"id": "..."}: el ID de una vista previa completada de POST /v2/dialogue-edits en su organización.

No agregue entradas de audio o texto, segments ni dubParams; la vista previa proporciona el audio.

{
  "rows": [
    {
      "request_id": "line-2",
      "endpoint": "/v2/generate",
      "payload": {
        "model": "sync-3",
        "input": [{"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}],
        "dialogueEdit": {"id": "7644754c-bdfc-4d51-a78f-e0cb0cbbd40f"}
      }
    }
  ],
  "dry_run": true
}

Los mismos objetos de fila funcionan como líneas en la carga de un archivo JSONL.

Al enviarse, cada fila de edición de diálogo se expande exactamente en la solicitud que POST /v2/generate construye para esa vista previa, y se cobra igual que esa generación. El payload del archivo de resultados muestra la solicitud expandida (el video, el audio de la vista previa y los segmentos editados), no la fila que usted envió. Envíe primero el batch con dry_run: true: ejecuta todas las comprobaciones siguientes, incluida la expansión, sin renderizar nada.

• Todas las filas de edición de diálogo de un batch deben usar vistas previas creadas a partir del mismo video de origen. Para varios videos, envíe un batch por video.
• Se aplican los límites habituales de batch: de 20 a 500 registros de forma predeterminada y 5 MB. La expansión añade el audio de la vista previa y los segmentos editados a cada fila. El límite de 5 MB también se aplica al batch expandido. Un batch que ocupe menos de 5 MB al enviarlo puede rechazarse con un error de tamaño de archivo y estado 400. Una ejecución de prueba también detecta este error. Si ocurre, divida las filas en batches más pequeños.
• La mayoría de las vistas previas se renderizan como segmentos editados del video. Una vista previa que solo puede renderizarse como lip sync del video completo se acepta en un batch solo cuando ese renderizado dura 30 segundos o menos; renderice las más largas con POST /v2/generate.

Rechazos de edición de diálogo

Si alguna fila de edición de diálogo no se puede renderizar, se rechaza toda la solicitud y no se crea ningún batch. La respuesta incluye el errorCode que POST /v2/generate devolvería para esa vista previa, además del lineNumber de la primera fila con error:

{
  "statusCode": 422,
  "errorCode": "dialogue_edit_not_found",
  "lineNumber": 3,
  "message": "Record at line 3: The dialogue edit was not found in this organization."
}

Solo se informa la primera fila con error. Corríjala y repita la ejecución de prueba (dry_run) hasta que devuelva {"status": "VALIDATED"}.

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