Batch-Verarbeitung | sync. labs

Die Sync Labs Batch-API verarbeitet bis zu 500 lip sync-Generierungen in einer einzigen Anfrage, gesendet als JSONL-Datei oder als JSON-Array von Zeilen. 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 im Scale-Plan oder höher verfügbar. Aktuell werden in der Batch-Verarbeitung nur Generierungen mit Eingaben bis zu 30 Sekunden unterstützt.

Batch-API erfordert den Scale-Plan oder höher, einschließlich Enterprise

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

Statt eine Datei hochzuladen, kannst du application/json mit den Einträgen in rows senden. Jedes Element von rows ist dasselbe Objekt wie eine Zeile der JSONL-Datei, und beide Formen werden gleich validiert: standardmäßig 20 bis 500 Zeilen, höchstens 5 MB im JSONL-Format und eindeutige request_id-Werte. Wenn ein Eintrag abgelehnt wird, nennt der Fehler dessen Zeile. Ablehnungen bei Dialogbearbeitungen geben sie im Feld lineNumber zurück; andere Fehler zu einem Eintrag, etwa ungültiges JSON oder eine fehlende request_id, nennen sie nur in message (zum Beispiel Record at line 4: payload is required). Gezählt werden nicht leere Einträge, nicht physische Zeilen, Leerzeilen in einer JSONL-Datei werden also übersprungen; bei einem JSON-Body entspricht Zeile N rows[N-1]. Die Beispiele oben zeigen der Kürze halber zwei Einträge; ein Batch braucht mindestens 20.

Optionale Parameter:

webhook_url: Benachrichtigungen erhalten, wenn der Batch abgeschlossen ist
dry_run: Auf true setzen, um deine Eingabe ohne Verarbeitung zu validieren. Eine gültige Eingabe gibt {"status": "VALIDATED"} zurück und erstellt keinen Batch.

Die Batch-Erstellung ist nicht durch idempotente Anfragen abgedeckt. Wenn bei einer Erstellungsanfrage ein Timeout auftritt, liste deine Batches mit GET /v2/batch auf, bevor du erneut einreichst, damit du dieselben Zeilen nicht zweimal ausführst.

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. Feldnamen in der Ergebnisdatei sind in snake_case, das Video einer abgeschlossenen Zeile liegt also unter response.output_url und ihre Generierungs-ID unter response.id. Ordne jede Zeile anhand der request_id deiner Eingabe zu.

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

Der webhook für den Batch-Abschluss kann für denselben Batch mehr als einmal zugestellt werden. Verwende die id des Batches, um Benachrichtigungen zu ignorieren, die du bereits verarbeitet hast.

Dialogbearbeitungs-Zeilen (früher Zugriff)

Eine Batch-Zeile kann eine abgeschlossene Vorschau einer Dialogbearbeitung rendern, statt ein Video mit neuem Audio zu kombinieren. So machst du aus einem aufgenommenen Video viele Varianten, zum Beispiel eine pro Empfängername. Personalisierte Videobotschaften enthält ein vollständiges Skript.

Dialogbearbeitungs-Zeilen befinden sich im frühen Zugriff und werden pro Organisation aktiviert. Kontaktiere uns, um sie freischalten zu lassen. Bis dahin werden Zeilen mit dialogueEdit beim Einreichen abgelehnt.

Das payload jeder Zeile enthält:

model, zum Beispiel sync-3.
input mit genau einem Video: demselben Quellvideo, aus dem die Vorschau erstellt wurde.
dialogueEdit: {"id": "..."}: die ID einer abgeschlossenen Vorschau aus POST /v2/dialogue-edits in deiner Organisation.

Füge keine Audio- oder Texteingaben, segments oder dubParams hinzu; die Vorschau liefert das 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
}

Dieselben Zeilenobjekte funktionieren auch als Zeilen in einer hochgeladenen JSONL-Datei.

Beim Einreichen wird jede Dialogbearbeitungs-Zeile genau zu der Anfrage erweitert, die POST /v2/generate für diese Vorschau erstellt, und sie wird genauso abgerechnet wie diese Generierung. Das payload in der Ergebnisdatei zeigt die erweiterte Anfrage (das Video, das Vorschau-Audio und die bearbeiteten Segmente), nicht die Zeile, die du gesendet hast. Sende den Batch zuerst mit dry_run: true: Damit laufen alle unten aufgeführten Prüfungen, einschließlich der Erweiterung, ohne dass etwas gerendert wird.

Alle Dialogbearbeitungs-Zeilen in einem Batch müssen Vorschauen verwenden, die aus demselben Quellvideo erstellt wurden. Für mehrere Videos reichst du einen Batch pro Video ein.
Es gelten die üblichen Batch-Limits: 20 bis 500 Zeilen und 5 MB.
Die meisten Vorschauen werden als bearbeitete Segmente des Videos gerendert. Eine Vorschau, die sich nur als lip sync über das gesamte Video rendern lässt, wird in einem Batch nur akzeptiert, wenn dieses Rendering 30 Sekunden oder kürzer ist; längere renderst du mit POST /v2/generate.

Ablehnungen bei Dialogbearbeitungen

Wenn eine Dialogbearbeitungs-Zeile nicht gerendert werden kann, wird die gesamte Anfrage abgelehnt und kein Batch erstellt. Die Antwort enthält den errorCode, den POST /v2/generate für diese Vorschau zurückgeben würde, sowie die lineNumber der ersten fehlerhaften Zeile:

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

`errorCode`	Status	Ursache	Lösung
`dialogue_edit_not_found`	422	Die ID ist unbekannt oder gehört zu einer anderen Organisation.	Verwende eine Vorschau, die deine Organisation erstellt hat.
`dialogue_edit_not_completed`	422	Die Vorschau ist noch `PENDING` oder `PROCESSING`, oder sie ist `FAILED`.	Solange sie aussteht oder verarbeitet wird, polle `GET /v2/dialogue-edits/{id}`, bis sie abgeschlossen ist, und reiche dann ein. Eine `FAILED`-Vorschau ist endgültig: Erstelle eine neue.
`dialogue_edit_source_mismatch`	422	Das Video der Zeile ist nicht das Video, aus dem die Vorschau erstellt wurde.	Sende das ursprüngliche Quellvideo der Vorschau.
`dialogue_edit_retime_required`	422	Der Vorschau fehlt das Retiming, das sie zum Rendern braucht (`segmentLipsyncEnabled` oder `sectionExpansionEnabled` ist bei ihr false).	Erstelle eine neue Vorschau. Wenn sie weiterhin false meldet, kontaktiere uns.
`dialogue_edit_removal_too_large`	422	Die Bearbeitung entfernt mehr Sprache, als das umgebende Filmmaterial auffangen kann.	Stelle einige Wörter wieder her und erstelle eine neue Vorschau.
`dialogue_edit_audio_conflict`	422	Die Zeile enthält zusätzlich eine Audio- oder Texteingabe, `segments` oder `dubParams`.	Sende nur die Videoeingabe und `dialogueEdit`.
`dialogue_edit_unsupported`	422	Die API kann diese Vorschau nicht rendern; dazu zählt auch ein Rendering des gesamten Videos, das länger als 30 Sekunden ist.	Erstelle mit einem API-Schlüssel eine neue Vorschau für das gesamte Video oder rendere diese mit `POST /v2/generate`.
`dialogue_edit_batch_mixed_sources`	422	Die Vorschauen im Batch stammen aus unterschiedlichen Quellvideos.	Reiche einen Batch pro Quellvideo ein.
`generation_input_validation_failed`	400	`dialogueEdit` ist kein Objekt mit einer UUID als `id`, oder `input` enthält nicht genau ein Video.	Korrigiere die Struktur der Zeile.

Es wird nur die erste fehlerhafte Zeile gemeldet. Korrigiere sie und wiederhole den Testlauf, bis er {"status": "VALIDATED"} zurückgibt.