xAI

xAI text and image batches in Batchwork with file upload, paginated result retrieval, and the unified typed client.

xAI combines a file-backed submission with a paginated results API. String models use the Responses request shape; image models use /v1/images/generations.

At a glance

Text example

from batchwork import BatchRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch(
        model="xai/grok-4",
        requests=[BatchRequest(custom_id="summary", prompt="Summarize this report.")],
    )

String xAI models automatically use Responses serialization.

Image generation

from batchwork import BatchImageRequest

job = await client.batch_images(
    model="xai/grok-imagine-image",
    requests=[
        BatchImageRequest(
            custom_id="city",
            prompt="A quiet futuristic city at dawn.",
            n=2,
            aspect_ratio="16:9",
        )
    ],
)

Generic n and aspect_ratio are supported. Generic size and seed are not serialized. xAI provider options include output format, sync mode, resolution, quality, user, and provider-level aspect ratio.

Lifecycle

1. JSONL lines contain custom_id, method: "POST", endpoint, and body.
2. Batchwork uploads the file through /files without a purpose.
3. /batches receives the file ID and fixed name batchwork.
4. poll() retrieves /batches/{id}.
5. results() requests up to 100 records per page and follows pagination_token, with a 10,000-page safety ceiling.
6. cancel() calls /batches/{id}:cancel.

Batch status is normalized from xAI request counts: pending work is in progress; all-canceled work is canceled; otherwise a batch with no pending requests is completed, even if some items errored.

Responses translation

xAI options include log probabilities, reasoning effort/summary, storage, includes, previous response ID, tools, and tool choice. Setting store=False automatically includes encrypted reasoning content. Function schemas have additionalProperties: false removed recursively where xAI requires it.

Text inputs can include images plus supported file URLs and provider file IDs. Inline images are supported; inline generic file data is not serialized as an xAI input file.

CLI capability contract

Only responses is a valid explicit text --endpoint. Exact text request-root option keys are include, logprobs, previousResponseId, reasoningEffort, reasoningSummary, store, and topLogprobs. include is an array, store is boolean, logprobs is boolean or a non-negative integer, and topLogprobs is an integer from 0 through 8. Canonical frequency/presence penalties, stop sequences, and top_k are unsupported.

Exact image option keys are aspect_ratio, output_format, quality, resolution, sync_mode, and user. Provider aspect_ratio collides with canonical aspect_ratio. Generic image seed and size are unsupported. Unknown keys and invalid values fail local preflight. Submission-level batch metadata is unsupported and rejected before file upload. Package hard bounds are 50,000 requests, 20 MiB per request, and 200 MiB aggregate, subject to lower xAI/model limits.

Results

Text results normalize output text and usage. Image normalization accepts data, a url, or both. The serializer requests base64-oriented image output, but provider-returned URLs may be signed and short-lived; consume them promptly.

Errors may arrive through top-level error_message or nested error data. Successful results retain the selected completion object in result.response; errored results retain the raw result item.

Result pagination rejects continuation-token cycles and duplicate result IDs. It processes at most 10,000 pages, then raises a non-retryable provider protocol error before requesting page 10,001. Errors report safely consumed page and record counts without exposing continuation tokens.

xAI does not support embeddings through Batchwork.

Official references

• xAI Batches API
• xAI Responses API
• xAI image generation
• xAI pricing

See Image generation, Results, and Provider overview.