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. 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 el plan Scale o superior. A partir de ahora, solo se admiten generaciones con entradas de hasta 30 segundos en el procesamiento batch.

API de lotes requiere el plan Scale o superior, incluido 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?

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

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

En lugar de subir un archivo, puede enviar application/json con los registros en rows. Cada fila es el mismo objeto que una línea JSONL, y ambas formas se validan de la misma manera: de 20 a 500 filas de forma predeterminada, 5 MB o menos cuando se escriben como JSONL, y valores de request_id únicos. Cuando se rechaza un registro, el error indica su línea. Los rechazos de edición de diálogo la devuelven en un campo lineNumber; otros errores de registro, como JSON no válido o la falta de request_id, la indican solo en message (por ejemplo Record at line 4: payload is required). Las líneas cuentan registros no vacíos, no líneas físicas, por lo que se omiten las líneas en blanco de un archivo JSONL; con un cuerpo JSON, la línea N es rows[N-1]. Los ejemplos anteriores muestran dos registros por brevedad; un batch necesita al menos 20.

Parámetros opcionales:

webhook_url: reciba notificaciones cuando se complete batch
dry_run: configúrelo en true para validar su entrada sin procesar. Una entrada válida devuelve {"status": "VALIDATED"} y no crea ningún batch.

La creación de un batch no está cubierta por las solicitudes idempotentes. Si se agota el tiempo de espera de una solicitud de creación, liste sus batchs con GET /v2/batch antes de volver a enviarla, para no ejecutar las mismas filas dos veces.

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:

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

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. Los nombres de los campos en el archivo de resultados están en snake_case, por lo que el video de una fila completada está en response.output_url y su ID de generación en response.id. Relacione cada línea con su entrada mediante request_id.

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

El webhook de finalización puede entregarse más de una vez para el mismo batch. Use 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.

Las filas de edición de diálogo están en acceso anticipado y se habilitan por organización. Contáctenos para activarlas. Hasta entonces, las filas que incluyen dialogueEdit se rechazan al enviarse.

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 filas y 5 MB.
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."
}

`errorCode`	Estado	Causa	Solución
`dialogue_edit_not_found`	422	El ID es desconocido o pertenece a otra organización.	Use una vista previa creada por su organización.
`dialogue_edit_not_completed`	422	La vista previa todavía está en `PENDING` o `PROCESSING`, o está en `FAILED`.	Mientras esté pendiente o en proceso, sondee `GET /v2/dialogue-edits/{id}` hasta que se complete y luego envíe el batch. Una vista previa `FAILED` es definitiva: cree una nueva.
`dialogue_edit_source_mismatch`	422	El video de la fila no es el video a partir del cual se creó la vista previa.	Envíe el video de origen original de la vista previa.
`dialogue_edit_retime_required`	422	A la vista previa le falta el reajuste de tiempos que necesita para renderizarse (`segmentLipsyncEnabled` o `sectionExpansionEnabled` tiene el valor false en ella).	Cree una nueva vista previa. Si sigue indicando false, contáctenos.
`dialogue_edit_removal_too_large`	422	La edición elimina más habla de la que el metraje circundante puede absorber.	Restaure algunas palabras y cree una nueva vista previa.
`dialogue_edit_audio_conflict`	422	La fila también tiene una entrada de audio o texto, `segments` o `dubParams`.	Envíe solo la entrada de video y `dialogueEdit`.
`dialogue_edit_unsupported`	422	La API no puede renderizar esta vista previa, incluido un renderizado del video completo de más de 30 segundos.	Cree una nueva vista previa del video completo con una clave de API, o renderice esta con `POST /v2/generate`.
`dialogue_edit_batch_mixed_sources`	422	Las vistas previas del batch provienen de distintos videos de origen.	Envíe un batch por video de origen.
`generation_input_validation_failed`	400	`dialogueEdit` no es un objeto con un `id` UUID, o `input` no contiene exactamente un video.	Corrija la estructura de la fila.

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