OpenAI

OpenAI Batch API support for Chat, Responses, Completions, and Embeddings.

OpenAI uses a file-backed Batch API: Batchwork serializes JSONL, uploads it through Files, creates a batch, polls status, then streams the output and error files.

At a glance

Property	Batchwork behavior
Output modalities	Text and embeddings
Text inputs	Messages, tools, images, supported file/audio forms; PDFs with Responses
Endpoints	Chat Completions, Responses, legacy Completions, Embeddings
Submission	JSONL file upload, then `/batches`
Results	Output and error JSONL files
Batch metadata	Forwarded
Webhooks	Native OpenAI batch events plus managed polling
Credential	`OPENAI_API_KEY`
Default base URL	`https://api.openai.com/v1`

Text example

from batchwork import BatchRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch(
        model="openai/gpt-5.5",
        requests=[
            BatchRequest(custom_id="fr", prompt="Capital of France? One word."),
            BatchRequest(custom_id="jp", prompt="Capital of Japan? One word."),
        ],
    )

String OpenAI models default to Chat Completions. Select Responses or legacy Completions explicitly:

from batchwork import BatchProvider, ModelKind, ModelSpec

responses_model = ModelSpec(
    provider=BatchProvider.OPENAI,
    model_id="gpt-5.5",
    kind=ModelKind.RESPONSES,
)

Embeddings

from batchwork import BatchEmbeddingRequest

job = await client.batch_embeddings(
    model="openai/text-embedding-3-small",
    requests=[BatchEmbeddingRequest(custom_id="doc-1", value="Document text")],
)

Use provider_options={"openai": {"dimensions": 256}} to request a supported reduced dimension.

Lifecycle

Each request becomes {custom_id, method: "POST", url, body} in JSONL.
Batchwork uploads the file to /files with purpose batch.
/batches receives the file ID, endpoint, completion_window="24h", and optional metadata.
poll() retrieves /batches/{id}.
results() streams both output_file_id and error_file_id when present.
cancel() calls /batches/{id}/cancel.

Provider-returned IDs are validated before being used in paths.

Request translation

Input	Wire behavior
`stream`	Removed for batch submission
Chat reasoning-model token limit	May become `max_completion_tokens`
Responses token limit	Becomes `max_output_tokens`
Unsupported reasoning sampling/penalties	Removed according to model behavior
System messages	May become developer messages or be omitted through OpenAI options
Service tier	Removed for known unsupported model/tier combinations

OpenAI provider options cover endpoint-specific fields such as reasoning effort/summary, storage, response includes, previous response IDs, tool controls, service tier, log probabilities, caching, user identifiers, and embedding dimensions.