Configuration

Models, credentials, providers, endpoints, and batch limits.

Models

String models use provider/model form. The provider is the segment before the first slash, so model IDs may contain additional slashes.

job = await client.batch(
    model="openai/gpt-5.5",
    requests=requests,
)

gemini is an alias for google, and togetherai is an alias for together. String xAI models use the Responses request shape; other string models use the Chat request shape. Use ModelSpec when an endpoint kind must be explicit:

from batchwork import BatchProvider, ModelKind, ModelSpec

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

ModelKind supports CHAT, RESPONSES, and COMPLETION.

Supported providers

Selecting an unsupported modality raises UnsupportedProviderError before a provider request is submitted. The table describes generated output; image, PDF, text-file, and audio inputs for text requests vary separately.

Submission and results

See the provider overview for accepted input media and native versus managed webhook behavior.

Environment variables

When both Google key variables are present, GOOGLE_GENERATIVE_AI_API_KEY takes precedence.

Credential precedence

API keys and base URLs resolve in this order:

1. Explicit per-call api_key or base_url.
2. Per-call credentials.
3. Credentials configured on Batchwork.
4. Provider environment variables.

Headers are merged instead of replaced: client credentials, then per-call credential headers, then explicit per-call headers.

from batchwork import BatchProvider, Batchwork, ProviderCredentials

credentials = {
    BatchProvider.OPENAI: ProviderCredentials(
        api_key="...",
        base_url="https://gateway.example.com/v1",
        headers={"X-Application": "batch-worker"},
    )
}

async with Batchwork(credentials=credentials) as client:
    job = await client.batch(
        model="openai/gpt-5.5",
        requests=requests,
        headers={"X-Request-Group": "nightly"},
    )

Values may also be supplied to one call with credentials=ProviderCredentials(...), api_key=, base_url=, and headers=. Custom endpoints and headers are trusted application configuration; review the security boundaries before routing requests through a gateway.

Limits

BatchLimits defaults to:

from batchwork import BatchLimits

limits = BatchLimits(
    max_requests=10_000,
    max_request_bytes=10 * 1024 * 1024,
    max_upload_bytes=100 * 1024 * 1024,
)

These are client-side safeguards. Providers may enforce lower limits. Notable restrictions:

• Google inline batch uploads are capped at 20 MiB.
• Google image batches generate exactly one image per request (n=1).
• Google file-mode batch results are not supported; use inline results.
• Imagen models are outside Batchwork’s batch image scope.
• OpenAI’s Batch API does not support /v1/images/generations.
• xAI image result URLs are signed and short-lived; consume them promptly.