Google Gemini

Google Gemini inline batch operations in Batchwork for text, embeddings, and generated images with normalized results.

Google Gemini uses inline long-running operations. Text and image requests use :batchGenerateContent; embeddings use :asyncBatchEmbedContent. Batchwork polls the operation and reads inline results.

At a glance

Text example

from batchwork import BatchRequest, Batchwork

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

gemini/model is accepted as an alias for google/model.

Embeddings

from batchwork import BatchEmbeddingRequest

job = await client.batch_embeddings(
    model="google/gemini-embedding-001",
    requests=[
        BatchEmbeddingRequest(
            custom_id="doc-1",
            value="Document text",
            dimensions=256,
            provider_options={
                "google": {"taskType": "RETRIEVAL_DOCUMENT"}
            },
        )
    ],
)

Batchwork maps canonical dimensions to output dimensionality and moves it with task type and title into Google’s embedContentConfig for the batch.

Image generation

from batchwork import BatchImageRequest

job = await client.batch_images(
    model="google/gemini-3-pro-image-preview",
    requests=[
        BatchImageRequest(
            custom_id="forest",
            prompt="A sunlit forest path.",
            aspect_ratio="16:9",
            seed=42,
        )
    ],
)

Google requires exactly one generated image per request. aspect_ratio and seed are serialized; generic size is not.

Lifecycle

1. Each request is wrapped as {metadata: {key: custom_id}, request: ...}.
2. Text/images call models/{model}:batchGenerateContent; embeddings call models/{model}:asyncBatchEmbedContent.
3. The returned batches/{id} operation is polled.
4. Inline responses are correlated through their metadata key.
5. Cancellation uses batches/{id}:cancel.

The effective inline upload maximum is the lower of the configured Batchwork limit and 20 MiB.

Translation and options

Google generation settings are nested under generationConfig. Provider options include response modalities, thinking configuration, media resolution, image configuration, safety settings, cached content, labels, service tier, retrieval configuration, Google Search, and other native tools.

Gemma models receive system text prepended to the first user message rather than systemInstruction. Gemini 3 has distinct mixed-tool and thought-signature behavior.

CLI capability contract

Google uses native APIs; the OpenAI-style --endpoint values do not apply. Exact text request-root provider-option keys are:

audioTimestamp, cachedContent, imageConfig, labels, mediaResolution, responseModalities, retrievalConfig, safetySettings, serviceTier, and thinkingConfig.

Exact embedding keys are content, outputDimensionality, taskType, and title. Canonical dimensions maps to outputDimensionality; specifying both is a collision. Supported taskType values are provider-defined retrieval, semantic-similarity, classification, clustering, question-answering, and fact-verification task types. content is a complex list with one entry per input value.

Exact image keys are googleSearch, imageConfig, mediaResolution, responseModalities, and thinkingConfig. imageConfig.aspectRatio collides with canonical aspect_ratio. imageConfig.imageSize accepts 1K, 2K, or 4K; responseModalities must contain IMAGE and optional TEXT. Canonical image size is unsupported and n is limited to exactly 1.

Unknown keys and basic shape/value errors fail locally. Submission-level batch metadata is unsupported and rejected before provider work. The inline serialized upload limit is 20 MiB, lower than the package’s 200 MiB aggregate ceiling when applicable.

Media and result limits

Only HTTPS Gemini Files URLs under the configured provider origin and supported YouTube URLs pass directly. Other remote media is downloaded and inlined through the configured media resolver.