Configuration

Configure models, credentials, providers, endpoints, and batch limits for the Batchwork client, CLI, and polling server.

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.6-sol",
    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.6-sol",
    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. All seven providers accept image inputs for supported text models; see the input-media matrix.

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.

CLI profiles and local continuity

The command-line tool keeps non-secret user profiles in a schema-v1 TOML file and route-complete job identity in a private metadata-only SQLite registry. Inspect both effective paths with:

batchwork --json config path
batchwork --json config validate
batchwork --json config show
batchwork --json registry check

CLI profile selection is root --profile, BATCHWORK_PROFILE, configured default, then none. Credentials and secret headers remain environment-only. Registered jobs retain immutable routing data so ambient configuration cannot silently move an existing job to another account or gateway.

See CLI configuration and registry for the exact TOML schema, OS paths, precedence, endpoint trust boundary, privacy, cleanup, migration, backup, and direct-reference recovery.

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.6-sol",
        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. Base URLs must use HTTPS and cannot contain userinfo, a query, or a fragment. HTTP is allowed only when the host is exactly localhost or a literal loopback IP such as 127.0.0.1 or ::1; a hostname that resolves to loopback does not qualify. This restriction is intentional hardening of the trusted-configuration boundary. 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 image batches support generation through /v1/images/generations; image editing is outside batch_images().
• xAI image result URLs are signed and short-lived; consume them promptly.