Batch API

Create Batch

Create a batch processing job from a JSONL file. Requires the Scale plan. Send the file in multipart field input (or the accepted file alias); it must be 5 MB or smaller and contain 20-500 records by default. Each line must contain request_id, endpoint exactly /v2/generate, and a generation payload.

Authentication

x-api-keystring
API Key authentication via header

Request

This endpoint expects a multipart form containing a file.
inputfileRequired
JSONL file containing batch requests. Send it in multipart field `input` (or `file` alias). Each non-empty line must contain `request_id`, endpoint exactly `/v2/generate`, and `payload` as a CreateGenerationDto object. Minimum 20 records required, maximum 500 records by default, no duplicate request_id values, and maximum file size 5 MB.
webhook_urlstringOptional

Optional webhook URL to receive batch completion notifications. A POST request will be sent when the batch completes or fails, with a Sync-Signature header (t=<unix>,v1=<hmac_sha256>) signed with the organization webhook secret.

dry_runbooleanOptionalDefaults to false

When true, validates the JSONL file and returns { "status": "VALIDATED" } without creating a batch.

Response

This endpoint returns an object.
Batch Responseobject
OR
Validation Responseobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
429
Too Many Requests Error
500
Internal Server Error