Batch-Verarbeitung

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. Sie ist für große Mengen kurzer Clips gedacht, zum Beispiel personalisierte Videokampagnen oder Content-Lokalisierung, bei denen die Ergebnisse über mehrere Stunden eintreffen können.

Wer kann die Batch-API nutzen?

Die Batch-API erfordert einen Scale-Plan oder höher und eine Freigabe für deine Organisation. Der Zugriff ist standardmäßig deaktiviert, auch bei neuen Scale-Abonnements. Kontaktiere den Support, um Zugriff anzufordern. Bestehende Nutzer benötigen ebenfalls eine Freigabe nach einer Prüfung von Nutzung und Abrechnung.

Ohne Freigabe erhält die Organisation 403 mit errorCode: batch_access_not_enabled, auch bei dry_run. Nach der Freigabe erhalten andere Pläne und kostenlose Konten 402 mit errorCode: plan_feature_unavailable. requiredPlan ist scale, bei Credit-Plänen enterprise.

Wird der Zugriff zum Erstellen entzogen, laufen bereits angenommene Batches weiter. Du kannst ihren Status abfragen und verfügbare Ergebnisse herunterladen.

• Ein Batch enthält standardmäßig 20 bis 500 Einträge oder das eigene Limit deines Kontos.
• Jeder aktive Batch belegt einen Platz deines Batch-Limits, das dem Concurrency-Limit deines Plans entspricht. Seine Einträge zählen nicht zur Concurrency von /v2/generate.
• Die geschätzte Ausgabe jedes Eintrags darf höchstens 30 Sekunden lang sein. Ein längerer Eintrag schlägt in der Ergebnisdatei mit Input files exceed 30s duration, which is not supported in batch mode fehl, der Rest des Batches läuft weiter.
• Jeder Eintrag wird wie die Generierung abgerechnet, die er ausführt.

Bei einer Multipart-Anfrage sende genau eine JSONL-Datei im Feld input (file funktioniert ebenfalls). Andere Dateifelder oder mehrere Dateien führen zu 400. Bei 503 upload_capacity_unavailable wird kein Batch erstellt. Wiederhole dieselbe Anfrage nach der in Retry-After angegebenen Wartezeit oder sende einen JSON-Body mit rows.

Wann Batch sinnvoll ist und wann nicht

Ein Batch ist eine Pipeline mit Warteschlange. Alle Einträge werden heruntergeladen und geprüft, bevor einer von ihnen startet, und Ergebnisse können Stunden dauern, mit einer angestrebten Bearbeitungszeit von bis zu 24 Stunden. Nutze ihn für große Mengen kurzer Clips, die nicht sofort fertig sein müssen.

Für ein paar Generierungen gleichzeitig ist er nicht gedacht. Dafür:

• Sende normale POST /v2/generate-Anfragen parallel, innerhalb deines Concurrency-Limits. Jede startet, sobald sie angenommen wird.
• Oder lass einen Agenten das Tool jobs_create-many des sync. labs MCP-Servers verwenden, das mehrere Jobs auf einmal über die normale API startet.

Batch-Concurrency-Limits

Wenn du bereits so viele Batches ausführst, wie das Concurrency-Limit deines Plans erlaubt, gibt die API 429 Too Many Requests mit errorCode: concurrency_limit_reached zurück:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "errorCode": "concurrency_limit_reached",
  "message": "Batch concurrency limit reached. You have 3 active batches and your plan allows 3. Please wait for existing batches to complete or upgrade your plan for higher limits.",
  "activeBatches": 3,
  "concurrencyLimit": 3,
  "retryAfterSeconds": 20
}

Die Antwort enthält einen Header Retry-After (in Sekunden) und einen Header X-Sync-Concurrency-Limit. Statt sofort erneut zu versuchen, warte retryAfterSeconds oder bis einer deiner aktiven Batches fertig ist.

Wie erstelle ich einen Batch-Job?

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

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 eine POST-Benachrichtigung, wenn dein Batch abgeschlossen ist oder fehlschlägt. Sie ist wie Generierungs-webhooks mit einem Sync-Signature-Header signiert und folgt denselben Wiederholungsregeln: bis zu 6 Versuche über etwa 2 Stunden, mit demselben Sync-Delivery-Id-Header bei jedem Versuch.

Anders als die Antwort von Get Batch verwendet der webhook-Payload Feldnamen in camelCase:

{
  "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 den Header Sync-Delivery-Id oder 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.

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: standardmäßig 20 bis 500 Einträge und 5 MB. Bei der Erweiterung werden jeder Zeile das Vorschau-Audio und die bearbeiteten Segmente hinzugefügt. Das Limit von 5 MB gilt auch für den erweiterten Batch. Ein gesendeter Batch unter 5 MB kann deshalb mit einem Dateigrößenfehler und Status 400 abgelehnt werden. Auch ein Testlauf meldet diesen Fehler. Teile die Zeilen dann in kleinere Batches auf.
• 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."
}

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

Verwandte Ressourcen

• Rate Limits — API rate limit verstehen, um deine Batch-Größen wirksam zu planen
• Webhooks Guide — webhook-Benachrichtigungen für Batch-Abschlussereignisse einrichten
• Fehlerbehandlung — Referenz für Batch-spezifische Fehlercodes und Fehlerbehebung