For thousands of catalogue images, use an asynchronous batch workflow: submit requests in a JSONL file, track the batch by its ID, and reconcile each result with a stable custom_id. The Batch API does not stream per-image progress; plan to inspect output and error files when they become available, download them before OpenAI’s 30-day automatic deletion, and set your own retention rules for originals and derivatives.
How the batch workflow works
OpenAI’s Batch API is for work that does not need an immediate response. You prepare a JSONL input file with one request per line, upload it with the batch purpose, create a batch for the endpoint, check its status, and retrieve its output and error files. The API supports image-generation and image-edit endpoints, including /v1/images/generations and /v1/images/edits.
As an Amazon Associate I earn from qualifying purchases.
- Prepare requests. Make one JSON object per line. Give each request a unique
custom_idthat identifies the catalogue item and image version, and provide a valid request body for the chosen endpoint. - Upload the JSONL file. Use the official Node.js
openaiSDK and a readable file stream, withpurpose: "batch". - Create and record the batch. Submit the uploaded file ID, target endpoint, and required
completion_window: "24h". Persist the returned batch ID alongside your own job metadata and input manifest. - Check status separately from the request that created the batch. Poll or otherwise query the batch status from a background worker; do not keep a catalogue-facing HTTP request open while the images are processed.
- Retrieve and reconcile results. Once results are available, download both output and error files, parse their JSONL records, and update catalogue rows by
custom_id.
A JSONL request line has this general shape; the body must match the endpoint and the image task you are actually submitting:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall{"custom_id":"sku-4821-image-v3","method":"POST","url":"/v1/images/generations","body":{"...":"endpoint-specific request fields"}}The batch guide describes a 24-hour completion window, not a promise that every job finishes at a particular time. Design for asynchronous completion and handle jobs that reach a terminal state without completing every request.
#1 Best Overall
What progress can you show?
There are two different kinds of progress to track. The batch status is the service’s job-level signal. Your application can add per-image states, but the API does not provide a streamed percentage for each image: Batch requests return results through files, not streamed responses.
Batch-level status
Record the status returned for each batch. The documented statuses are validating, failed, in_progress, finalizing, completed, expired, cancelling, and cancelled. Treat these as distinct states in your job store rather than reducing them to a single “running” or “done” flag. In particular, expired and cancelled do not mean that every request failed: some requests may have completed and have results to collect.
Rank #2
Per-image status in your application
Create a row for every request before submission, keyed by its custom_id. A simple state model is queued, succeeded, and failed. After downloading and parsing the result files, mark IDs found in the output as succeeded and IDs found in the error file as failed; retain the returned record or error details for investigation and retry decisions.
While the batch is executing, those rows can accurately show that items are queued or awaiting results, but they cannot provide a live completion percentage based on streamed image responses. If you display a percentage, define exactly what it measures—for example, the share of requests whose outcomes your application has reconciled—and do not present it as an API-reported progress counter.
Rank #3
Keep results matched to the right catalogue images
Do not rely on JSONL line number or output order. Results are not guaranteed to appear in input order, so array-position updates can attach an image to the wrong product. Use a deterministic custom_id based on the catalogue item and image version, and use that ID to join each output or error record to the manifest and catalogue record.
- Make each ID unique within the submitted work and stable enough to support diagnosis and safe retry decisions.
- Store the original request metadata with the ID, such as the item identifier and the intended image version.
- When retrying only failed work, create a clear relationship between the retry and the original attempt. Do not blindly overwrite an approved catalogue image with a late or duplicate result.
Plan batch sizes and scheduling around the documented limits
OpenAI’s Batch API guide (2026) states a maximum of 50,000 requests per batch and a maximum uploaded input-file size of 200 MB. It also states a limit of 2,000 batch creations per hour and a 24-hour completion window. These are service limits, not a catalogue throughput benchmark.
Rank #4
| Constraint | Documented value | What to plan for |
|---|---|---|
| Requests per batch | 50,000 maximum | Split larger catalogues into multiple batches. |
| Uploaded JSONL input file | 200 MB maximum | Check each file’s byte size before upload; the limit is for the JSONL file, not the total size of remote images fetched by requests. |
| Batch creation rate | 2,000 batches per hour maximum | Throttle batch creation separately from preparing request files. |
| Completion window | 24 hours | Build around asynchronous status checks and later file retrieval rather than an immediate response. |
| Batch pricing | 50% lower than synchronous APIs, as stated in the 2026 guide | Confirm the applicable endpoint and pricing before budgeting; this is the guide’s stated discount, not a per-catalogue cost estimate. |
Chunk work below both the request-count and file-size ceilings, leaving room for JSONL overhead and metadata. Where an endpoint permits remote image URLs, referencing an image URL can keep the request body smaller; it does not change the 200 MB limit on the uploaded JSONL file. The guide does not establish how quickly a particular catalogue will finish, so avoid promising a fixed images-per-hour rate.
Handle expiry, cancellation, and failed work
An expired batch cancels unfinished requests. Responses completed before expiry remain available in the output file; expired requests are written to the error file with a batch_expired message. If you cancel manually, work completed before cancellation is returned, and completed work remains chargeable. Preserve both result and error records so you can distinguish successful work from items that need review or retry.
- On
completed: retrieve output and error files, reconcile every ID, and record any missing or unexpected IDs for investigation. - On
expired: collect completed results and the error file, then prepare a new batch only for work that still needs processing. - On
cancelled: collect work completed before cancellation and determine which remaining items should be resubmitted. - On
failed: preserve the batch and error details, inspect the cause, and correct the input or operational issue before retrying.
Use the batch ID and per-image IDs to make retries auditable. A retry should update the intended image version only after its result passes your own validation and publishing rules.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Set a retention policy for originals, derivatives, and batch files
OpenAI’s Batch API guide states that the output file is automatically deleted 30 days after the batch completes. Download output and error files to storage you control as soon as the batch reaches a terminal state. The FAQ also says zero-data-retention settings do not apply to Batch API artifacts: input files, outputs, errors, and intermediate artifacts follow configured retention policies.
The API documentation sets the output-file deletion point; it does not prescribe how long a business should keep catalogue originals, approved derivatives, manifests, retries, or logs. Choose those periods based on recovery value, reproducibility, privacy or contractual sensitivity, and storage and retrieval cost.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Asset | Retention approach | Decision to make |
|---|---|---|
| Original product images | Keep while needed for reprocessing, audit, or contractual obligations; remove when those needs end. | Can the image be recovered from the supplier, and would you need it to regenerate or verify a derivative? |
| Approved derivatives | Keep for the catalogue’s publishing period and any applicable records obligations. | How long must the published image remain available, and can it be reproduced to the required standard? |
| Input manifests and request metadata | Keep long enough to explain which item, version, and request produced a result. | What evidence is needed to trace a published image or safely retry an item? |
| Output and error files | Download before the documented 30-day automatic deletion, then apply your controlled-storage policy. | Which results and error details are necessary for reconciliation, support, audit, or recovery? |
| Retry copies and operational logs | Retain only as long as needed to diagnose attempts and meet policy obligations; protect them according to their contents. | Do they contain sensitive prompts, image references, or other data that merits tighter access or shorter retention? |
Make deletion operational, not aspirational: assign an owner, define lifecycle rules for each storage location, and verify that input files, downloaded results, retries, and logs are all covered. A blanket retention period is not established by the Batch API documentation, so set one that fits your legal, privacy, and recovery requirements.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
