OpenAI

OpenAI Batch API support in Batchwork for text, embeddings, and generated images with normalized jobs and results.

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

Text example

from batchwork import BatchRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch(
        model="openai/gpt-5.6-sol",
        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.6-sol",
    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", dimensions=256)
    ],
)

Use canonical dimensions to request a supported reduced width. The OpenAI-specific user field remains available through provider_options.

Image generation

from batchwork import BatchImageRequest

job = await client.batch_images(
    model="openai/gpt-image-2",
    requests=[
        BatchImageRequest(
            custom_id="bike",
            prompt="A red bicycle leaning against a brick wall.",
            n=2,
            size="1536x1024",
            provider_options={
                "openai": {"outputFormat": "webp", "quality": "high"}
            },
        )
    ],
)

Each item targets /v1/images/generations. n and model-supported size values are accepted. Provider options are validated by model family: DALL-E 3 supports quality, style, and user; DALL-E 2 supports user; GPT Image models support background, moderation, outputFormat, outputCompression, quality, and user. Generated image bytes are normalized into result.images[].data; usage is normalized when the provider returns it. Image editing is not exposed by batch_images().

Lifecycle

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

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

Request translation

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.

CLI capability contract

Provider-option keys are exact and endpoint-specific.

Shared Chat/Responses keys are forceReasoning, logprobs, promptCacheKey, promptCacheRetention, safetyIdentifier, serviceTier, systemMessageMode, and user.

chat-completions additionally supports logitBias, maxCompletionTokens, metadata, parallelToolCalls, prediction, reasoningEffort, store, and textVerbosity.

responses additionally supports allowedTools, contextManagement, conversation, include, instructions, maxToolCalls, metadata, parallelToolCalls, previousResponseId, reasoningEffort, reasoningSummary, store, textVerbosity, and truncation.

completions supports exactly echo, logitBias, logprobs, suffix, and user.

Embedding options are dimensions and user. Canonical dimensions collides with the provider option of the same name.

Image keys across implemented model families are background, moderation, outputCompression, outputFormat, quality, style, and user. DALL-E 2 accepts only user; DALL-E 3 accepts quality, style, and user; GPT Image accepts background, moderation, outputCompression, outputFormat, quality, and user.

Unknown keys fail locally. Canonical max_output_tokens collides with maxCompletionTokens; Responses canonical system collides with instructions; canonical tool_choice collides with allowedTools; canonical image aspect ratio and seed are unsupported. Reasoning-mode sampling/penalty conflicts fail rather than being silently removed. Batch metadata is supported and forwarded. Image count is at most 1 for DALL-E 3 and 10 otherwise; model-family size and option enums are validated before upload.

Media and output

Image URLs can pass directly to supported OpenAI text models. PDF URLs pass directly only for Responses; other media forms are resolved before serialization. Generated-image requests use batch_images() instead of batch().

Results and errors

Batchwork normalizes Chat, Completion, and Responses text, embedding vectors, generated images, usage, and item errors. Tool calls, finish reasons, citations, reasoning, and other provider fields remain in result.response.

OpenAI is the only provider with BatchPoller.handle_openai_webhook(). It verifies signed batch.* events, retrieves authoritative state, and enters the same completion path used by managed polling.

Official references

• OpenAI Batch API
• OpenAI image generation
• OpenAI webhooks
• OpenAI pricing

See Jobs, Results, and Polling and webhooks.