IN ENGLISH · API DOCS

OpenAI Batch: half price with the Batch API

Requests that do not need an answer right away go into one JSONL file, which you upload and turn into a batch; OpenAI runs them within 24 hours, and their input and output are billed at 50% of the model's usual price, with the usual markup. The official OpenAI SDK works with the base URL https://1xai.ir/v1 and a 1xAi key. When the batch is created its largest possible cost is held from the wallet, and when it ends only the requests that completed are billed.

Last updated:

[01]OPENAI BATCH

What batch processing is for

Any job with many requests that can wait a few hours: classifying and labelling thousands of texts, summarising and translating in bulk, embedding a corpus, or running an evaluation set. The same work costs 50% of the input and output price, and it does not use up your key's rate limit, since a whole batch is only a few API requests.

  • OpenAI models only, on two routes: /v1/chat/completions and /v1/embeddings.
  • Results are ready within 24 hours at most (completion_window is 24h only). A batch that has not finished by then becomes expired: its completed requests are in the output file and the rest cost nothing.
  • Batches are paid from the wallet only; plan credit and gift credit do not pay for them.
  • A file or a batch is reachable only with keys of the account that made it, and, when a company workspace key made it, only with keys of that workspace. Any other key gets the answer an unknown id gets: 404 with code not_found. The listings show your own files and batches only.
[02]OPENAI BATCH

Routes

Batch routes
RouteWhat it does
POST /v1/filesWhat it does:Uploads an input file: a multipart/form-data form with purpose=batch and file (the JSONL file). The file is checked line by line while it uploads. The answer is OpenAI's file object (id like file-…).
GET /v1/filesWhat it does:Your own batch files (inputs and outputs), newest first. Parameters: purpose (batch or batch_output), limit (default and maximum 10,000), order (desc or asc) and after (a file id).
GET /v1/files/{id}What it does:One of your files; expires_at is when it will be deleted.
GET /v1/files/{id}/contentWhat it does:The content of a batch's output or error file, streamed from OpenAI. A transfer cut in the middle ends with the connection aborted, never as a shorter file.
DELETE /v1/files/{id}What it does:Deletes the file now (retention and deletion).
POST /v1/batchesWhat it does:Creates a batch: input_file_id, endpoint (the url of the file's lines), completion_window set to 24h, and metadata if you want it. The answer is OpenAI's batch object (id like batch_…).
GET /v1/batchesWhat it does:Your own batches, newest first, as OpenAI last reported each. limit up to 100 (default 20) and after (a batch id).
GET /v1/batches/{id}What it does:A batch's state: status, request_counts, output_file_id and error_file_id.
POST /v1/batches/{id}/cancelWhat it does:Cancels the batch (cancelling).
  • Every other path under /v1/files, /v1/uploads and /v1/batches, and an upload with any purpose other than batch, answers 402 with code path_unmetered. OpenAI's organisation-wide listings are never served; the listings above are read from 1xAi's own records.
  • A batch's file (input, output or error) serves batches only: a file_id naming one in a /v1/responses or /v1/chat/completions body answers 404 with code not_found, even for its owner, and nothing is held or billed.
  • expires_after on an upload and output_expires_after on a batch are ignored; 1xAi sets the retention (retention and deletion).
[03]OPENAI BATCH

A complete example: from file to results

Each line of the input file is one request, with a unique custom_id that comes back with its result:

requests.jsonljson
{"custom_id": "review-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: the delivery was fast."}], "max_completion_tokens": 1000}}
{"custom_id": "review-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: the package arrived damaged."}], "max_completion_tokens": 1000}}
The official OpenAI SDKpython
import time
from openai import OpenAI

client = OpenAI(
    base_url="https://1xai.ir/v1",
    api_key="1xai-...",
)

# 1. upload the file
batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")

# 2. create the batch
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)

# 3. wait for it to end
while batch.status not in ("completed", "failed", "expired", "cancelled"):
    time.sleep(60)
    batch = client.batches.retrieve(batch.id)

# 4. download the results
print(batch.status, batch.request_counts)
if batch.output_file_id:
    client.files.content(batch.output_file_id).write_to_file("results.jsonl")
curlcurl
# 1. upload the file
curl https://1xai.ir/v1/files \
  -H "Authorization: Bearer 1xai-..." \
  -F purpose=batch \
  -F file=@requests.jsonl

# 2. create the batch, with the id of the answer above
curl https://1xai.ir/v1/batches \
  -H "Authorization: Bearer 1xai-..." \
  -H "Content-Type: application/json" \
  -d '{"input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

# 3. the batch's status
curl https://1xai.ir/v1/batches/batch_... \
  -H "Authorization: Bearer 1xai-..."

# 4. the results, with the batch's output_file_id
curl https://1xai.ir/v1/files/file-.../content \
  -H "Authorization: Bearer 1xai-..." \
  -o results.jsonl
  • A batch is validating, then in_progress and finalizing, and ends as one of completed, failed, expired, cancelled. Asking every few minutes is enough.
  • The output file (output_file_id) has one line per completed request, with its custom_id and the full answer in response.body. The output's order is not necessarily the input's; match lines by custom_id.
  • Requests that failed or expired are in the error file (error_file_id) and cost nothing.
  • The gateway does not rewrite lines: the changes it makes on the interactive routes (what the gateway changes), such as max_tokens becoming max_completion_tokens or temperature being removed for reasoning models, are not made in a batch. Write each line as OpenAI accepts it; a line OpenAI refuses lands in the error file and costs nothing.
[04]OPENAI BATCH

The input file's rules

  • One JSON object per line; blank lines are ignored.
  • custom_id: a non-empty string of at most 512 characters, unique in the file.
  • method is POST, and url is /v1/chat/completions or /v1/embeddings, the same on every line of a file.
  • body.model: an OpenAI model sold in batch and priced on 1xAi. On chat: the gpt-6, gpt-5, gpt-4.1, gpt-4o, gpt-4-turbo, gpt-4, gpt-3.5-turbo, o1, o3 and o4-mini families. On embeddings: text-embedding-3-* and text-embedding-ada-002. Not accepted: audio, realtime, search, image, transcription and speech models, Codex, -pro, deep-research and computer-use models, and *-chat-latest. One file may mix models.
  • max_tokens or max_completion_tokens: optional; when given, a whole number from one to the model's maximum output (from our model list; 128,000 for a model it does not size). A line without one is held at the model's maximum output; set your own cap to hold less.
  • n: up to 8; the output is held n times.

What a line may not contain

  • "stream": true.
  • Audio: modalities with audio, an audio field, or an input_audio part.
  • A file part (file: a PDF or a file_id).
  • web_search_options and prediction.
  • Any tool other than function and custom.
  • A service_tier other than auto or default.

The whole file is checked while it uploads, and the first bad line refuses the whole file: 400 with code batch_file_invalid, the line number in line (as an editor numbers it, blank lines counted) and the cause in reason. The message follows Accept-Language. Nothing of a refused file is kept anywhere, and it costs nothing.

jsonjson
{
  "error": {
    "message": "Line 3: n must be between 1 and 8.",
    "type": "api_error",
    "code": "batch_file_invalid",
    "line": 3,
    "reason": "n"
  }
}
The values of `reason`
reasonMeaning
invalid_jsonMeaning:The line is not a valid JSON object
custom_idMeaning:custom_id is empty, not a string, or too long
duplicate_custom_idMeaning:custom_id is used twice
methodMeaning:method is not POST
urlMeaning:url is not one of the two routes
mixed_urlMeaning:url differs from the earlier lines
bodyMeaning:body is not a JSON object, or cannot be read
modelMeaning:body.model is missing
model_not_batchMeaning:The model is not offered in batch, or not on this url
model_not_pricedMeaning:The model has no price on 1xAi
streamMeaning:"stream": true
max_tokensMeaning:The output cap is out of range
nMeaning:n is outside one to 8
unsupported_fieldMeaning:A field, part or tool batches do not accept (the list above)
too_many_linesMeaning:More than 50,000 requests
line_too_longMeaning:A line larger than 8 MB
empty_fileMeaning:The file holds no request (line is 0)
[05]OPENAI BATCH

Limits

Batch limits, per account
WhatLimitOver it
One fileLimit:25 MBOver it:413 batch_file_too_large
Requests in one fileLimit:50,000Over it:400 batch_file_invalid (too_many_lines)
One line of an input fileLimit:8 MBOver it:400 batch_file_invalid (line_too_long)
Uploads at onceLimit:2Over it:429 batch_limit
Input files kept at OpenAILimit:100Over it:429 batch_limit
All files kept (input, output and error)Limit:2,048 MBOver it:429 batch_limit
Unsettled batches at onceLimit:10Over it:429 batch_limit
Estimates of the unsettled batches togetherLimit:100,000,000 TomanOver it:429 batch_limit
Requests submitted in the last 24 hoursLimit:200,000Over it:429 batch_limit
  • A 429 with code batch_limit carries limit and current for the batch and request limits; files and stored_bytes for the file limits; and reason set to stored_bytes when one file does not fit in the room left. Delete files you no longer need with DELETE /v1/files/{id}.
  • A file over the limit answers 413 with code batch_file_too_large. A far larger upload may be stopped before it reaches the gateway: a 413 without a JSON body; recognise it by the HTTP status.
  • Our batch queue at OpenAI is shared by every account. When it is full, creating a batch answers 429 with code upstream_capacity and nothing stays held; submit again later, or a smaller batch.
  • The key's rate limit (rate limits) counts the requests to these routes, not the lines of a file.
[06]OPENAI BATCH

Price

formulatext
cost_toman = tokens × vendor_list_price_usd × 0.5 × (1 + markup) × toman_per_usd
  • 0.5 is OpenAI's own batch price: uncached input and output at 50% of the model's usual rate. Cached input tokens are billed at the model's usual cached rate, with no batch discount.
  • The markup is the model's usual markup for your account and does not change for batches (the markup by model); the Toman rate is the day's rate at settlement.
  • Only completed requests are billed; a failed, expired or cancelled request costs nothing.
  • The cost of each model in a batch is rounded up to the whole Toman.
  • A batch is paid from the wallet only: plan credit and gift credit neither pay for it nor count toward its hold (chat plans and gift credit).
  • Each model's rates are on the pricing page.
[07]OPENAI BATCH

The hold when a batch is created

  • On POST /v1/batches the file's largest possible cost is estimated: each line's prompt from its size, each image at the most its model family bills for one image, and each line's output at its cap (or, without one, the model's maximum output) times n; all at the batch price with your account's markup.
  • Each image is held at 48,200 tokens on gpt-4o-mini, 3,800 on *-nano models, 2,700 on other *-mini models and 1,500 on the rest. Only what OpenAI reports is billed.
  • That estimate plus a 10% margin (for the Toman rate moving before the batch ends) is held from the wallet. A hold is not a charge: when the batch ends the real cost is charged and the hold released. If OpenAI refuses the batch, the hold is released at once.
  • When the spendable balance (the balance less other holds) is not enough, the answer is 402 with code insufficient_balance, with the fields estimate_toman, required_toman and available_toman, and nothing is sent. Lower the lines' output cap, or top up.
  • Before the hold, the checks of every API call, for the amount held: an account in debt gets 402 with code insufficient_balance; a key with a spend cap needs room for that amount (402 with code key_capped and the fields cap_toman, spent_toman and required_toman); and a company workspace key needs room under the workspace's and the member's monthly limits (402 with code workspace_limit).
  • If a model of the file lost its price after the upload, creating the batch answers 402 with code model_not_priced.
  • When the key has a model list, every model of the file must be on it; otherwise creating the batch is refused with 403 and code key_model_not_allowed. The upload is not checked against it.
[08]OPENAI BATCH

Settlement and the usage report

  • When OpenAI reports the batch ended (completed, failed, expired, cancelled), 1xAi reads the output file, usually within a few minutes, adds up the usage of the completed requests, charges the wallet and releases the hold. Nothing has to be downloaded for the batch to be settled.
  • The cost appears in the usage report (GET /v1/usage, the CSV export and the dashboard's call log) as one row per model per batch: endpoint is /v1/batches, the model is named as your file wrote it, the tokens are that model's across the batch, and the amount is in cost_toman.
  • The row's request_id is obatch_<batch id>_<model> (such as obatch_batch_abc123_gpt-5-mini), so GET /v1/usage?request_id=… finds one model's row exactly, and a q search for the batch id finds all of its rows (account API).
  • Creating and cancelling a batch also leave a row each in the usage report, at no cost (/v1/batches and /v1/batches/cancel).
  • The answer to POST /v1/batches has no X-1xai-Cost-Toman header, since the cost is known at settlement; it carries X-Request-Id like every answer (response metadata).
  • In the dashboard, batch processing (in Persian) lists the batches you made with personal keys: the status, the requests done and failed, the amount held or the final cost in Toman, and the output's download while it is kept.
[09]OPENAI BATCH

Retention and deletion

  • After a batch is settled, its input, output and error files stay at OpenAI for 1 day and are then deleted. expires_at on the file object says when. Download the output within that time.
  • An input file is kept while its batch is open. An input file no batch uses is deleted 1 day after its upload.
  • Reading a file whose retention is over: 404 with code file_expired.
  • DELETE /v1/files/{id} deletes the file at OpenAI at once; afterwards it answers 404 with code not_found. A batch's output or error file cannot be deleted before the batch's cost is settled: 409 with code batch_not_settled; try again a few minutes later.
  • An account with an open batch cannot be deleted: cancel the batch and wait for its settlement first. When an account is deleted, every file it still has is deleted at OpenAI at once.
[10]OPENAI BATCH

Cancelling a batch

  • POST /v1/batches/{id}/cancel cancels the batch. Its status becomes cancelling and then cancelled, which may take a few minutes.
  • Requests that completed before the cancel are in the output file and are billed; the rest cost nothing. A cancelled batch is settled like any other, and its hold released.
  • OpenAI's own answers (for instance to cancelling a batch that has already ended) are returned as OpenAI sent them.
[11]OPENAI BATCH

Errors

Batch errors
StatusCodeWhen
400Code:batch_file_invalidWhen:A line of the file is wrong (line, reason)
400Code:invalid_requestWhen:An upload that is not multipart/form-data, or has no file or no purpose; a batch body without input_file_id or endpoint; a completion_window other than 24h; an input_file_id that is not a checked input file of yours, or was deleted; an endpoint that is not the file's url
402Code:path_unmeteredWhen:A purpose other than batch, or another path under /v1/files, /v1/uploads or /v1/batches
402Code:insufficient_balanceWhen:The account is in debt, or the wallet cannot fund the hold
402Code:key_cappedWhen:The key's spend cap has no room for the hold
402Code:workspace_limitWhen:The workspace's or the member's monthly limit has no room for the hold
402Code:model_not_pricedWhen:A model of the file lost its price after the upload
403Code:key_model_not_allowedWhen:A model of the file is not on the key's model list
404Code:not_foundWhen:A file or batch that is not yours, does not exist or was deleted by you; or a batch file's file_id in the body of an interactive call
404Code:file_expiredWhen:The file's retention is over and it was deleted
409Code:batch_not_settledWhen:Deleting an output or error file before the batch is settled
413Code:batch_file_too_largeWhen:A file larger than 25 MB
429Code:batch_limitWhen:One of the account's limits (above)
429Code:upstream_capacityWhen:Our batch queue at OpenAI is full
500Code:internalWhen:The file or batch could not be recorded; it was deleted or cancelled, and nothing is charged. Send it again.
502Code:upstream_errorWhen:OpenAI could not be reached
503Code:upstream_unavailableWhen:Batch processing is not available through us right now

Every one of these has the usual format: {"error": {"message", "type": "api_error", "code", …}}. OpenAI's own errors (such as a 400 for a batch OpenAI cannot run) are returned as OpenAI sent them. Every code is in the error reference.

1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.