Traitement batch

L’API Batch de Sync Labs traite jusqu’à 500 générations de lip sync dans une seule requête, envoyées sous forme de fichier JSONL ou de tableau JSON de lignes. C’est idéal pour les workflows de traitement vidéo en masse, comme les campagnes vidéo personnalisées, la localisation de contenu, ou tout scénario qui exige une génération de lip sync à grand volume.

Quel est le format de fichier batch ?

Le traitement batch vous permet d’envoyer 20 à 500 générations sans gérer vous-même la file d’attente ni la concurrence, avec un délai cible de 24 heures. Les jobs batch contournent votre limite de concurrence normale par génération, mais l’API Batch n’est disponible que sur le plan Scale ou supérieur. À ce jour, seules les générations avec des entrées allant jusqu’à 30 secondes sont prises en charge en traitement batch.

Limites de concurrence batch

Les jobs batch contournent votre limite de concurrence normale par génération, mais une limite séparée plafonne le nombre de batchs que vous pouvez exécuter en même temps, selon votre plan. Si vous envoyez un nouveau batch alors que vous êtes déjà à cette limite, l’API renvoie une réponse 429 Too Many Requests.

Le corps de la 429 est un objet JSON qui décrit la limite atteinte :

{
  "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 réponse inclut aussi un en-tête Retry-After (en secondes) et un en-tête X-Sync-Concurrency-Limit. Plutôt que de réessayer immédiatement, attendez retryAfterSeconds avant de renvoyer, ou attendez qu’un de vos batchs en cours se termine.

Comment créer un job batch ?

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

Pour un exemple complet et fonctionnel, consultez l’exemple de traitement batch dans notre dépôt d’exemples.

Notifications webhook

Lorsque vous fournissez un webhook_url, vous recevrez des notifications POST à la fin du batch :

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

Le webhook de fin de batch peut être livré plusieurs fois pour un même batch. Utilisez l’id du batch pour ignorer les notifications que vous avez déjà traitées.

Lignes d’édition de dialogue (accès anticipé)

Une ligne de batch peut produire le rendu d’un aperçu d’édition de dialogue terminé, au lieu d’associer une vidéo à un nouvel audio. Utilisez-la pour transformer une vidéo enregistrée en de nombreuses variantes, par exemple une par nom de destinataire. Le tutoriel Messages vidéo personnalisés propose un script complet.

Le payload de chaque ligne contient :

• model, par exemple sync-3.
• input avec exactement une vidéo : la même vidéo source que celle à partir de laquelle l’aperçu a été créé.
• dialogueEdit: {"id": "..."} : l’ID d’un aperçu terminé issu de POST /v2/dialogue-edits dans votre organisation.

N’ajoutez pas d’entrées audio ou texte, ni segments, ni dubParams ; l’aperçu fournit l’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
}

Les mêmes objets de ligne fonctionnent aussi comme lignes d’un fichier JSONL téléversé.

À l’envoi, chaque ligne d’édition de dialogue est développée exactement en la requête que POST /v2/generate construit pour cet aperçu, et elle est facturée comme cette génération. Le payload du fichier de résultats montre la requête développée (la vidéo, l’audio de l’aperçu et les segments modifiés), et non la ligne que vous avez envoyée. Envoyez d’abord le batch avec dry_run: true : il exécute toutes les vérifications ci-dessous, y compris le développement, sans effectuer aucun rendu.

• Toutes les lignes d’édition de dialogue d’un même batch doivent utiliser des aperçus créés à partir de la même vidéo source. Pour plusieurs vidéos, envoyez un batch par vidéo.
• Les limites habituelles des batchs s’appliquent : 20 à 500 lignes et 5 MB.
• La plupart des aperçus sont rendus sous forme de segments modifiés de la vidéo. Un aperçu qui ne peut être rendu qu’en lip sync sur la vidéo entière n’est accepté dans un batch que si ce rendu dure 30 secondes ou moins ; générez les plus longs avec POST /v2/generate.

Refus des lignes d’édition de dialogue

Si une ligne d’édition de dialogue ne peut pas être rendue, toute la requête est refusée et aucun batch n’est créé. La réponse contient l’errorCode que POST /v2/generate renverrait pour cet aperçu, ainsi que le lineNumber de la première ligne en échec :

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

Seule la première ligne en échec est signalée. Corrigez-la et relancez le dry run jusqu’à ce qu’il renvoie {"status": "VALIDATED"}.

Ressources associées

• Rate Limits — comprendre le rate limiting API pour planifier efficacement vos tailles de batch
• Webhooks Guide — configurer les notifications webhook pour les événements de fin de batch
• gestion des erreurs — référence des codes d’erreur spécifiques au batch et dépannage