Skip to content

Google Generative AI plugin

The genkit-google-genai package provides the GoogleAI plugin for calling Google’s generative models through the Gemini Developer API using an API key.

Supported model families:

  • Language models: Gemini and Gemma models (GoogleAI.gemini(...), GoogleAI.gemma(...))
  • Embedding models: Text and multimodal embeddings (GoogleAI.embedder(...))
  • Image models: Gemini native image generation and editing (GoogleAI.gemini_image(...))
  • Speech models: Gemini text-to-speech (GoogleAI.gemini_tts(...))
Terminal window
uv add genkit-google-genai
from genkit import Genkit
from genkit_google_genai import GoogleAI
ai = Genkit(
plugins=[GoogleAI()],
model=GoogleAI.gemini('gemini-flash-latest'),
)

GoogleAI also accepts network options:

import httpx
from genkit_google_genai import GoogleAI
plugin = GoogleAI(
headers={'X-Client-App': 'checkout'},
timeout=30.0, # Seconds (float)
max_retries=2, # Retries after the initial attempt
http_client_factory=lambda: httpx.AsyncClient(proxy='http://proxy.internal:3128'),
)

Get a Gemini API key from Google AI Studio and configure it in one of three ways:

  1. Environment variable: Set GEMINI_API_KEY.
  2. Plugin initialization: Pass api_key to GoogleAI:
import os
from genkit import Genkit
from genkit_google_genai import GoogleAI
ai = Genkit(
plugins=[GoogleAI(api_key=os.environ['GEMINI_API_KEY'])],
)
  1. Per-request override: Pass the key in context={'secrets': {'api_key': ...}} to route a single request to a different key, for example one per tenant:
response = await ai.generate(
model=GoogleAI.gemini('gemini-flash-latest'),
prompt='Summarize this order receipt.',
context={'secrets': {'api_key': tenant_api_key}},
)

Do not pass api_key inside config; it is rejected with INVALID_ARGUMENT. See Error types.

Each model family validates config against its typed Pydantic schema (GeminiConfig, GeminiImageConfig, GeminiTtsConfig, GemmaConfig, VeoConfig, EmbeddingConfig). Unknown top-level keys are rejected. To send a Gemini API field that the config class does not declare, put it in extra under its REST wire name. The plugin deep-merges extra into the request body, so generation settings go under generationConfig:

from genkit_google_genai import GeminiConfig, GoogleAI
response = await ai.generate(
model=GoogleAI.gemini('gemini-3.8-flash'),
prompt='Draft a release checklist.',
config=GeminiConfig(
temperature=0.2,
extra={'generationConfig': {'mediaResolution': 'MEDIA_RESOLUTION_LOW'}},
),
)

Any model ID the Gemini API serves works, including newer models and -latest aliases. Pass the bare ID to the helper for its family (GoogleAI.gemini(), gemini_image(), gemini_tts(), or gemma()) or use a 'googleai/<model-id>' string. Each helper rejects IDs from other families. The list below is curated metadata, not an allowlist.

  • gemini-3.8-flash — High-intelligence Flash model for reasoning, coding, and agentic tool loops
  • gemini-3.1-pro-preview — Preview Pro model for complex reasoning
  • gemini-3.5-flash-lite — High-throughput, low-latency model
  • gemini-flash-latest, gemini-flash-lite-latest, gemini-pro-latest — Aliases that point to the newest model in each tier
  • gemma-4-31b-it, gemma-4-26b-a4b-it — Gemma 4 open models; use GoogleAI.gemma(...) and GemmaConfig

Image and speech models have their own sections below.

from genkit import Genkit
from genkit_google_genai import GoogleAI
ai = Genkit(
plugins=[GoogleAI()],
model=GoogleAI.gemini('gemini-flash-latest'),
)
response = await ai.generate(
prompt='Explain how B-tree indexes reduce disk reads.',
)
print(response.text)
# => B-tree indexes keep keys sorted in wide, shallow nodes, so a lookup reads only a few pages...

Pass a Pydantic BaseModel to output_schema to enforce JSON schema decoding and parse the response into response.output:

from pydantic import BaseModel, Field
class MenuDish(BaseModel):
name: str = Field(description='Dish name')
allergens: list[str] = Field(description='Common allergens present')
price_cents: int = Field(description='Price in US cents')
response = await ai.generate(
prompt='Create a seasonal tartine dish for a cafe menu.',
output_schema=MenuDish,
)
dish = response.output
if dish is None:
raise RuntimeError(f'Dish generation failed: {response.error}')
print(dish.name, dish.price_cents)
# => Smoked Beet Tartine 1450

Configure thinking directly on GeminiConfig:

from genkit_google_genai import GeminiConfig, GoogleAI
response = await ai.generate(
model=GoogleAI.gemini('gemini-3.8-flash'),
prompt='Find the minimum number of weighings to isolate one counterfeit coin among 12.',
config=GeminiConfig(
thinking_level='HIGH', # 'MINIMAL', 'LOW', 'MEDIUM', or 'HIGH'
include_thoughts=True,
),
)
reasoning = ''.join(p.reasoning or '' for p in response.message.content)
print(reasoning)
print(response.text)

Set google_search=True on GeminiConfig to ground responses with Google Search:

from genkit_google_genai import GeminiConfig
response = await ai.generate(
prompt='What changed in the latest Python minor release?',
config=GeminiConfig(google_search=True),
)
print(response.text)

Pass tool_choice ('auto', 'required', or 'none') to ai.generate(), not GeminiConfig. 'required' forces a tool call on every turn, so pair it with return_tool_requests=True and run the tool yourself:

@ai.tool()
async def lookup_order(order_id: str) -> str:
"""Look up the shipping status of an order."""
return f'Order {order_id}: shipped'
response = await ai.generate(
prompt='Look up order #4821.',
tools=[lookup_order],
tool_choice='required',
return_tool_requests=True,
)
print(response.tool_requests[0].tool_request.name)
# => lookup_order
from genkit_google_genai import GeminiConfig, SafetySetting
response = await ai.generate(
prompt='Review this user comment for policy compliance.',
config=GeminiConfig(
safety_settings=[
SafetySetting(
category='HARM_CATEGORY_HATE_SPEECH',
threshold='BLOCK_MEDIUM_AND_ABOVE',
),
SafetySetting(
category='HARM_CATEGORY_DANGEROUS_CONTENT',
threshold='BLOCK_MEDIUM_AND_ABOVE',
),
],
),
)

Construct multimodal prompt parts with Part.from_text() and Part.from_media():

import base64
from pathlib import Path
from genkit import Part
image_b64 = base64.b64encode(Path('receipt.jpg').read_bytes()).decode('ascii')
response = await ai.generate(
prompt=[
Part.from_text('Extract the line items from this receipt.'),
Part.from_media(url=f'data:image/jpeg;base64,{image_b64}', content_type='image/jpeg'),
],
)

For media URLs, the plugin downloads the file (up to 20 MB) and sends it inline. YouTube URLs and Gemini Files API URIs go to the API by reference:

from genkit import Part
response = await ai.generate(
prompt=[
Part.from_text('Summarize the key steps shown in this clip.'),
Part.from_media(url='https://example.com/demo.mp4', content_type='video/mp4'),
],
)
  • gemini-embedding-001 — Default 3072 dimensions; pass output_dimensionality in config on embed() or embed_many() (for example 768, 1536, or 3072) to truncate vectors.
  • gemini-embedding-2 — Default 3072 dimensions with text, image, and video input support.
from genkit_google_genai import EmbeddingConfig, GoogleAI
embeddings = await ai.embed(
embedder=GoogleAI.embedder('gemini-embedding-001'),
content='Espresso extraction depends on grind size, dose, and water temperature.',
config=EmbeddingConfig(
task_type='RETRIEVAL_DOCUMENT',
output_dimensionality=768,
),
)
print(len(embeddings[0].embedding))
# => 768

GoogleAI.imagen() raises INVALID_ARGUMENT; Imagen models are not supported. Use Gemini native image models via GoogleAI.gemini_image() and GeminiImageConfig:

  • gemini-3.1-flash-image — Fast image generation and editing
  • gemini-3-pro-image — High-detail image generation and composition
  • gemini-2.5-flash-image — General-purpose native image generation
from genkit_google_genai import GeminiImageConfig, GoogleAI
response = await ai.generate(
model=GoogleAI.gemini_image('gemini-3.1-flash-image'),
prompt='A sunlit sourdough bakery counter with loaves on cooling racks.',
config=GeminiImageConfig(
aspect_ratio='16:9',
image_size='2K', # '512', '1K', '2K', or '4K'
),
)
for media in response.media:
print(f'Generated image ({media.content_type}): {media.url[:60]}...')

Veo runs as a background model: start it with ai.generate_operation() and poll with ai.check_operation().

import asyncio
from genkit import Genkit
from genkit_google_genai import GoogleAI, VeoConfig
ai = Genkit(plugins=[GoogleAI()])
# 1. Start the background video generation operation
operation = await ai.generate_operation(
model=GoogleAI.veo('veo-3.1-generate-preview'),
prompt='Aerial shot of coastal cliffs at sunrise with ocean mist.',
config=VeoConfig(
aspect_ratio='16:9',
resolution='720p',
),
)
# 2. Poll until completion
while not operation.done:
await asyncio.sleep(5)
operation = await ai.check_operation(operation)
# 3. operation.output is the completed ModelResponse
if operation.error:
raise RuntimeError(operation.error.message)
for media in operation.output.media:
print(f'Video URL: {media.url[:40]}...')
# => Video URL: https://generativelanguage.googleapis.com/...

On Gemini Enterprise, set output_gcs_uri in VeoConfig to have Veo write to Cloud Storage; media.url is then the gs:// path.

Common VeoConfig fields: aspect_ratio, resolution, duration_seconds, negative_prompt, person_generation, number_of_videos, generate_audio, and seed. Supported values depend on the Veo model.

Gemini TTS models synthesize single-speaker or multi-speaker audio using GoogleAI.gemini_tts() and GeminiTtsConfig.

  • gemini-3.1-flash-tts-preview — Gemini 3.1 Flash TTS (recommended)
  • gemini-2.5-flash-preview-tts — Gemini 2.5 Flash TTS
  • gemini-2.5-pro-preview-tts — Gemini 2.5 Pro TTS
from genkit_google_genai import GeminiTtsConfig, GoogleAI
# Single-speaker synthesis
response = await ai.generate(
model=GoogleAI.gemini_tts('gemini-3.1-flash-tts-preview'),
prompt='Order 42 is ready for pickup at the counter.',
config=GeminiTtsConfig(
voice='Kore',
language_code='en-US',
),
)
audio = response.media[0]
print(audio.content_type)
# => audio/l16; rate=24000; channels=1

For multi-speaker dialogue, pass speakers mapping speaker labels in the prompt to voice names (mutually exclusive with voice):

response = await ai.generate(
model=GoogleAI.gemini_tts('gemini-3.1-flash-tts-preview'),
prompt='Host: Welcome back.\nChef: Today we are roasting fennel.',
config=GeminiTtsConfig(
speakers={'Host': 'Kore', 'Chef': 'Puck'},
),
)

Available Voices: Puck, Charon, Kore, Fenrir, Aoede, Zephyr, Algenib, and more.

Gemini models automatically cache shared prompt prefixes, reporting cache hits on response.usage.cached_content_tokens:

base_context = 'Reference manual: ...' * 500
await ai.generate(
model=GoogleAI.gemini('gemini-flash-latest'),
prompt=f'{base_context}\n\nSummarize section 1.',
)
cached_response = await ai.generate(
model=GoogleAI.gemini('gemini-flash-latest'),
prompt=f'{base_context}\n\nSummarize section 2.',
)
print(cached_response.usage.cached_content_tokens)
# => 2048.0 (None when the prefix was not cached)