Repository navigation
types: Missing type for batch request input and output objects #1937
Description
Confirm this is a feature request for the Python library and not the underlying OpenAI API.
- This is a feature request for the Python library
Describe the feature or improvement you're requesting
Batch input files are a list of up to 50,000 request input objects, where each one looks like this:
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}]}}https://platform.openai.com/docs/api-reference/batch/request-input
I don't see this anywhere in openai.types. It should be there to make it easier to use batches.
Same for the output object, https://platform.openai.com/docs/api-reference/batch/request-output
Additional context
AFAIK the body element's type is Union[EmbeddingCreateParams, CompletionCreateParams]
Activity
[-]Missing type for batch request input and output objects[/-][+]types: Missing type for batch request input and output objects[/+]re-typing inputs since OAI hasn't written the type in API
shea-parkes commentedon Nov 16, 2025
Yea, this caught me very off guard today. I did do the "thumbs up" thing, but it was surprising enough I went ahead and dropped a comment here as well. Not sure how this got missed...
Similar to the hint above, the
bodyof the response isopenai.types.Completion, but still have to manually define the other parts.NikkiAung commentedon Dec 30, 2025
For
batch_request_input.pywithTypedDictclass, in accordance with Batch API current supporting available endpoints docu, I will be addingcustom_id,method(forcing with exactly the string "POST") usingLiteral,url, andbodywrapping withBatchRequestBodyusing Union with current supporting things like below while adding fallback for any additional typesOn one hand, for
batch_request_output.pywithBaseModelclass, I'm pretty sure there should beid,custom_id,responsewrapping withBatchRequestOutputResponseusing Union with current supporting things, including @shea-parkes mentionedCompletionlike belowand
errorwrapping withBatchRequestOutputErrorwith current supporting things likecode(Literal["batch_expired", "batch_cancelled", "request_timeout"]) andmessagereferring to this documentIf anyone is interested in trying this feature early using this git branch, your feedback would be greatly appreciated, @RobertCraigie, @alugowski, & @shea-parkes.! :))
marcuswood-oai commentedon Sep 15, 2026
Thanks for raising this, and thanks to everyone who contributed proposed types. The missing Batch JSONL record types need to be defined in the shared schema and exposed through SDK generation. openai/openai-openapi#578 tracks that work and links back to your report.
In the meantime, the Batch guide describes the record format and how to match results using
custom_id. That provides a way to work with the files while the envelope types are missing. We’re closing this report to keep the work together in openai/openai-openapi#578; please follow that issue for the schema and SDK updates.