Batch-Verarbeitung | sync. labs

Die Sync Labs Batch-API verarbeitet bis zu 500 lip sync-Generierungen in einer einzigen Anfrage mit einer JSONL-Datei. Das ist ideal für Workflows zur Videoverarbeitung in großen Mengen, zum Beispiel personalisierte Videokampagnen, Content-Lokalisierung oder jedes Szenario mit hohem Generierungsvolumen.

Was ist das Batch-Dateiformat?

Mit der Batch-Verarbeitung kannst du 20 bis 500 Generierungen einreichen, ohne Queueing oder Concurrency selbst zu verwalten, bei einer angestrebten Bearbeitungszeit von 24 Stunden. Batch-Jobs umgehen dein normales Concurrency-Limit für Generierungen, aber die Batch-API ist nur in Scale- und Enterprise-Plänen verfügbar. Aktuell werden in der Batch-Verarbeitung nur Generierungen mit Eingaben bis zu 30 Sekunden unterstützt.

Batch-API ist nur für Scale- und Enterprise-Nutzer verfügbar

Batch-Concurrency-Limits

Batch-Jobs umgehen dein normales Concurrency-Limit pro Generierung, aber ein separates Limit begrenzt, wie viele Batches du gleichzeitig ausführen kannst, abhängig von deinem Plan. Wenn du einen neuen Batch einreichst, während du dieses Limit bereits erreicht hast, gibt die API eine Antwort 429 Too Many Requests zurück.

Der 429-Body ist ein JSON-Objekt, das das erreichte Limit beschreibt:

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

Die Antwort enthält außerdem einen Header Retry-After (in Sekunden) und einen Header X-Sync-Concurrency-Limit. Statt sofort erneut zu versuchen, warte retryAfterSeconds, bevor du erneut einreichst, oder warte, bis einer deiner laufenden Batches abgeschlossen ist.

Wie erstelle ich einen Batch-Job?

Eingabedatei vorbereiten

Erstelle eine JSON Lines-Datei (.jsonl) mit deinen Generierungsanfragen. Jede Zeile sollte eine eindeutige request_id, den endpoint (muss "/v2/generate" sein) und ein payload im Standardformat der Generierungsanfrage enthalten (wie bei der Generierungs-API). Die Datei muss im JSON Lines-Format (.jsonl) vorliegen, mindestens 20 Einträge enthalten, eine maximale Dateigröße von 5 MB haben und bis zu 500 Anfragen pro Batch enthalten.

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

Einen Batch erstellen

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

Optionale Parameter:

webhook_url: Benachrichtigungen erhalten, wenn der Batch abgeschlossen ist
dry_run: Auf true setzen, um deine Eingabedatei ohne Verarbeitung zu validieren

Batch-Status prüfen

Überwache den Fortschritt deines Batches, indem du den Status pollst:

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

Ein Batch kann einen der folgenden Status haben:

PENDING: Batch erstellt, wartet auf den Verarbeitungsstart
PROCESSING: Generierungen werden verarbeitet
COMPLETED: Alle Generierungen sind abgeschlossen (erfolgreich oder mit Fehlern)
FAILED: Batch-Verarbeitung ist vollständig fehlgeschlagen

Batch-Ergebnisse prüfen

Wenn ein Batch abgeschlossen ist, stehen die Ergebnisse als JSON Lines-Datei unter der outputUrl der Antwort von get batch bereit. Ein GET auf diese URL gibt eine Weiterleitung 302 auf eine signierte Ergebnisdatei zurück. Clients, die Weiterleitungen automatisch folgen, können die JSONL-Antwort direkt lesen. Jede Zeile enthält:

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

Das Feld response enthält dieselben Daten wie einzelne Antworten der Generierungs-API.

Ein vollständiges, funktionierendes Beispiel findest du im Batch-Verarbeitungsbeispiel in unserem Beispiel-Repository.

Webhook-Benachrichtigungen

Wenn du eine webhook_url angibst, erhältst du POST-Benachrichtigungen, wenn dein Batch abgeschlossen ist:

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