Google Gemini

Gemini inline batch operations for text, embeddings, and generated images.

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",
            provider_options={
                "google": {"outputDimensionality": 256, "taskType": "RETRIEVAL_DOCUMENT"}
            },
        )
    ],
)

Batchwork moves output dimensionality, 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.

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.

Results normalize first-candidate text, embedding values, inline image data, usage, and structured errors. Google provider timestamps are not normalized into snapshots. Imagen :predict models are outside Batchwork’s batch image scope.

Official references

• Gemini Batch API
• Gemini embeddings
• Gemini image generation
• Gemini Files API

See Embeddings, Image generation, and Security.