Batch

The Batch API runs a file of requests asynchronously, for work that doesn’t need an immediate answer: classifying a catalog or generating descriptions. You upload a JSONL file with one request per line, create a batch, and download a results file when it completes, within 24 hours. It follows OpenAI’s Batch API.

The Batch API is enabled per organization, and each model must support it. Until it is enabled, creating a batch returns 403 with code batch_api_not_enabled. Contact us to request access.

Prepare the input file

Each line of the file is one request, with a custom_id you choose to match results to requests, the method, the endpoint url, and the request body. Every line must target the same endpoint and the same model. Supported endpoints are /v1/chat/completions and /v1/completions.

batch_input.jsonl

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "lfm3-1.7b", "messages": [{"role": "user", "content": "Describe a red ceramic mug in one sentence."}], "temperature": 0.1, "top_k": 50, "repetition_penalty": 1.1}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "lfm3-1.7b", "messages": [{"role": "user", "content": "Describe a walnut desk in one sentence."}], "temperature": 0.1, "top_k": 50, "repetition_penalty": 1.1}}

Input files may be up to 200 MB.

Upload the file

Request bodies are capped at 4.5 MB, so files are uploaded straight to storage through a presigned URL:

Call POST /v1/files with the file’s purpose, filename, and size in bytes. No file bytes are sent in this call. It returns a file id and a short-lived upload_url.
PUT the file to the upload_url. The URL is already signed, so this call carries no API key.

# Request a presigned upload URL
curl -X POST https://api.liquid.ai/v1/files \
  -H "Authorization: Bearer $LIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"batch","filename":"batch_input.jsonl","bytes":137587646}'
# => { "id": "file_abc", "upload_url": "https://...", "upload_expires_at": 1750000000 }

# Upload the file to the upload_url from the response
curl -X PUT "$UPLOAD_URL" --upload-file batch_input.jsonl

Create the batch

Call POST /openai/v1/batches with the uploaded file’s id:

curl -X POST https://api.liquid.ai/openai/v1/batches \
  -H "Authorization: Bearer $LIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_file_id":"file_abc","endpoint":"/v1/chat/completions","completion_window":"24h"}'

As in OpenAI’s API, problems in the file’s contents don’t fail this request. The batch is created and lands in status failed with an errors list, for example when lines use different models (model_mismatch) or a model you can’t call.

Check the status

Poll GET /openai/v1/batches/{id} until the batch finishes. request_counts shows the total, completed, and failed requests so far.A batch that fails validation ends as failed. Cancel a running batch with POST /openai/v1/batches/{id}/cancel. A batch still running after its 24-hour window ends as expired. Expired and cancelled batches still return the results of the requests that finished.

Download the results

A completed batch has an output_file_id, and an error_file_id if any requests failed. Download each with GET /openai/v1/files/{id}/content. Each line of the output is one result, with the custom_id of its request, so match results to requests by custom_id.

curl https://api.liquid.ai/openai/v1/files/$OUTPUT_FILE_ID/content \
  -H "Authorization: Bearer $LIQUID_API_KEY" > batch_output.jsonl

You can also follow batches and download their files on the Batches page of Liquid Console.

Get started

Capabilities

Platform

Prepare the input file

Upload the file

Create the batch

Check the status

Download the results