Passer à la navigation
Guides API

Traitement batch

Traiter efficacement plusieurs générations lipsync

L’API Batch de Sync Labs traite jusqu’à 500 générations de lip sync dans une seule requête à l’aide d’un fichier JSONL. 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 les plans Scale et Enterprise. À ce jour, seules les générations avec des entrées allant jusqu’à 30 secondes sont prises en charge en traitement batch.

API de lots est disponible uniquement pour les utilisateurs Scale et Enterprise

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 ?

1

Préparer votre fichier d'entrée

Créez un fichier JSON Lines (.jsonl) avec vos requêtes de génération. Chaque ligne doit contenir un request_id unique, l’endpoint (doit être "/v2/generate"), et un payload avec le format standard de requête de génération (identique à celui de la API de génération). Le fichier doit être au format JSON Lines (.jsonl) avec un minimum de 20 enregistrements, une taille maximale de 5MB, et jusqu’à 500 requêtes par 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

Créer 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}")

Paramètres optionnels :

  • webhook_url: Recevoir des notifications quand le batch est terminé
  • dry_run: Définir true pour valider votre fichier d’entrée sans lancer le traitement
3

Vérifier le statut du batch

Suivez la progression de votre batch en interrogeant son statut :

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

Un batch peut avoir l’un des statuts suivants :

  1. PENDING: Batch créé, en attente de démarrage du traitement
  2. PROCESSING: Les générations sont en cours de traitement
  3. COMPLETED: Toutes les générations sont terminées (avec succès ou échec)
  4. FAILED: Le traitement batch a totalement échoué
4

Vérifier les résultats du batch

Quand un batch se termine, les résultats sont disponibles sous forme de fichier JSON Lines à l’adresse outputUrl de la réponse get batch. Un GET vers cette URL renvoie une redirection 302 vers un fichier de résultats signé, les clients qui suivent automatiquement les redirections peuvent lire directement la réponse JSONL. Chaque ligne contient :

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

Le champ response contient les mêmes données que les réponses individuelles de la API de génération.

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 :

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

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