API Guides

Batch API

The Batch API allows you to submit multiple lipsync generation requests in a single batch operation, making it efficient to process large volumes of content. This is ideal for scenarios where you need to generate many videos at once, such as personalized video campaigns, content localization, or bulk processing workflows.

Overview

The Batch API processes multiple generation requests asynchronously and provides:

  • Bulk Processing: Submit up to 1000 generation requests in a single batch
  • Efficient Resource Usage: Batch requests bypass individual generation concurrency limits
  • Progress Tracking: Monitor batch progress with detailed metrics
  • Webhook Notifications: Receive notifications when batches complete
  • Result Downloads: Download batch results as a structured file

Plan Requirements

The Batch API is available for Growth plan subscribers and above. If you’re on a lower-tier plan, you’ll receive a 402 error when attempting to use batch endpoints.

Input Format

Batch requests use JSON Lines (.jsonl) format, where each line contains a separate generation request:

1{"request_id": "video_001", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://example.com/video1.mp4"}, {"type": "audio", "url": "https://example.com/audio1.wav"}]}}
2{"request_id": "video_002", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://example.com/video2.mp4"}, {"type": "audio", "url": "https://example.com/audio2.wav"}]}}

Required Fields

Each line in your .jsonl file must contain:

  • request_id: A unique identifier for this specific request
  • endpoint: Must be "/v2/generate" (only supported endpoint currently)
  • payload: The generation request payload (same format as the Generate API endpoint)

File Constraints

  • Maximum file size: 5MB
  • Maximum requests per batch: 1000
  • File format: JSON Lines (.jsonl)

Dry Run Validation

Before processing a large batch, you can validate your input file format by setting the dry_run parameter to true.

Batch Status and Lifecycle

Batches progress through several status states:

  1. PENDING: Batch created, waiting to start processing
  2. PROCESSING: Generations are being processed
  3. COMPLETED: All generations finished (successfully or with failures)
  4. FAILED: Batch processing failed entirely

Monitoring Batch Progress

You can monitor the progress of your batch by using the Get Batch endpoint.

Webhook Notifications

When you provide a webhook_url, you’ll receive POST notifications when your batch completes or fails:

1{
2  "id": "batch_abc123",
3  "createdAt": "2024-01-15T10:30:00Z",
4  "status": "COMPLETED",
5  "webhookUrl": "https://your-webhook-url.com/batch-webhook",
6  "metrics": {
7    "totalGenerations": 5,
8    "successCount": 4,
9    "failedCount": 1,
10    "pendingCount": 0
11  },
12  "options": {},
13  "outputUrl": "https://output.sync.so/batch_abc123_results.jsonl"
14}

Batch Results

When a batch completes, results are available as a JSON Lines file at the outputUrl. Each line contains the result for one request in the following format:

1{"request_id": "", "endpoint": "/v2/generate", "payload": {}, "status": "COMPLETED", "error": null, "response": {}, "updated_at":""}

The schema for response field is the same as the response for the Generate API endpoint.