Batch mode

Batch mode provides asynchronous translation for large or complex jobs that require processing multiple files or lengthy documents.

Capabilities

• Parallel processing of multiple files
• Asynchronous job submission and result retrieval
• Large-scale document and file collection support
• Single target language per job

Each input file generates its own translated output file that saves to a corresponding output location.

How it works

Batch mode processing runs asynchronously and enables you to translate multiple files in a single API call. This mode is ideal for workflows that involve large document archives.

Limits

These limits apply to file size, character count, and translation volume per job and per day.

Input

The API supports three input modes.

Output

The API supports two output layouts.

Output file format

Each translated input file produces a JSON output file. The filename follows the pattern {original_filename}_{file_id}.json. The contents match the fast mode response structure:

{
    "request_id": "24cfac34-548a-4a55-a58c-b99a9ff66e4a",
    "result": {
        "translations": {
            "es-ES": "Translated text here."
        }
    }
}

Translation options

Use BCP-47 locale codes when you create a batch job.

For the full list, see Supported languages.

Batch jobs

Create a batch job

To create a new batch translation job, use this endpoint:

POST /aiservices/translator/jobs

You can optionally include a reference_id for tracking. To receive webhook notifications when a job finishes, include a notifications object with a webhook_url and a secret for payload verification.

Example request (cURL)

This cURL example submits a batch translation job from S3 and defines the output location, target language, and settings. The response returns a job ID and status so you can track processing.

curl -X POST https://api.zoom.us/v2/aiservices/translator/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "PREFIX",
      "source": "S3",
      "uri": "s3://acme-bucket/input/2026/03/",
      "filters": {
        "include_globs": ["*.txt"],
        "exclude_globs": []
      },
      "auth": {
        "aws": {
          "access_key_id": "AKIA...",
          "secret_access_key": "wJalrX...",
          "session_token": "FwoGZXIvYXdzE..."
        }
      }
    },
    "output": {
      "destination": "S3",
      "uri": "s3://acme-bucket/output/2026/03/",
      "layout": "PREFIX",
      "overwrite": false,
      "auth": {
        "aws": {
          "access_key_id": "AKIA...",
          "secret_access_key": "wJalrX...",
          "session_token": "FwoGZXIvYXdzE..."
        }
      }
    },
    "config": {
      "source_language": "en-US",
      "target_languages": ["fr-FR"]
    },
    "notifications": {
      "webhook_url": "https://example.com/hooks/translator",
      "secret": "hmac-secret"
    },
    "reference_id": "batch-translation-2026-03"
  }'

Response (201)

{
    "job_id": "job_abc123",
    "state": "QUEUED",
    "submitted_at": "2026-03-10T18:34:12Z"
}

Batch job endpoints

Three additional endpoints are available to manage batch jobs.

List responses include a next_cursor field. Pass its value as the next_page_token query parameter to retrieve the next page.

Webhook verification

When a secret is provided in the notifications object, the API signs each webhook request so you can verify it came from Zoom AI Services.

Each webhook request includes two headers.

To verify the signature, compute HMAC-SHA256 of the string v0:{timestamp}:{raw_body} using your secret, then compare it to the value in x-zm-signature.

Use a timing-safe comparison to prevent timing attacks. Reject the request if the signatures do not match or if the timestamp is stale.

const message = `v0:${timestamp}:${rawBody}`;
const expected = `sha256=${crypto.createHmac("sha256", secret).update(message).digest("hex")}`;
const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
);