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(...))
Installation
Section titled “Installation”uv add genkit-google-genaiConfiguration
Section titled “Configuration”from genkit import Genkitfrom genkit_google_genai import GoogleAI
ai = Genkit( plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'),)GoogleAI also accepts network options:
import httpxfrom 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'),)Authentication
Section titled “Authentication”Get a Gemini API key from Google AI Studio and configure it in one of three ways:
- Environment variable: Set
GEMINI_API_KEY. - Plugin initialization: Pass
api_keytoGoogleAI:
import os
from genkit import Genkitfrom genkit_google_genai import GoogleAI
ai = Genkit( plugins=[GoogleAI(api_key=os.environ['GEMINI_API_KEY'])],)- 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.
Strict config validation and extra
Section titled “Strict config validation and extra”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'}}, ),)Language models
Section titled “Language models”Available models
Section titled “Available models”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 loopsgemini-3.1-pro-preview— Preview Pro model for complex reasoninggemini-3.5-flash-lite— High-throughput, low-latency modelgemini-flash-latest,gemini-flash-lite-latest,gemini-pro-latest— Aliases that point to the newest model in each tiergemma-4-31b-it,gemma-4-26b-a4b-it— Gemma 4 open models; useGoogleAI.gemma(...)andGemmaConfig
Image and speech models have their own sections below.
Basic usage
Section titled “Basic usage”from genkit import Genkitfrom 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...Structured output
Section titled “Structured output”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.outputif dish is None: raise RuntimeError(f'Dish generation failed: {response.error}')print(dish.name, dish.price_cents)# => Smoked Beet Tartine 1450Thinking and reasoning
Section titled “Thinking and reasoning”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)Google Search grounding
Section titled “Google Search grounding”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)Tool choice
Section titled “Tool choice”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_orderSafety settings
Section titled “Safety settings”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', ), ], ),)Multimodal input
Section titled “Multimodal input”Construct multimodal prompt parts with Part.from_text() and Part.from_media():
import base64from pathlib import Pathfrom 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'), ],)Embedding models
Section titled “Embedding models”Available models
Section titled “Available models”gemini-embedding-001— Default 3072 dimensions; passoutput_dimensionalityinconfigonembed()orembed_many()(for example768,1536, or3072) 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))# => 768Image models
Section titled “Image models”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 editinggemini-3-pro-image— High-detail image generation and compositiongemini-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]}...')Video models (Veo)
Section titled “Video models (Veo)”Veo runs as a background model: start it with ai.generate_operation() and poll with ai.check_operation().
import asyncio
from genkit import Genkitfrom genkit_google_genai import GoogleAI, VeoConfig
ai = Genkit(plugins=[GoogleAI()])
# 1. Start the background video generation operationoperation = 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 completionwhile not operation.done: await asyncio.sleep(5) operation = await ai.check_operation(operation)
# 3. operation.output is the completed ModelResponseif 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.
Speech models (TTS)
Section titled “Speech models (TTS)”Gemini TTS models synthesize single-speaker or multi-speaker audio using GoogleAI.gemini_tts() and GeminiTtsConfig.
Available models
Section titled “Available models”gemini-3.1-flash-tts-preview— Gemini 3.1 Flash TTS (recommended)gemini-2.5-flash-preview-tts— Gemini 2.5 Flash TTSgemini-2.5-pro-preview-tts— Gemini 2.5 Pro TTS
from genkit_google_genai import GeminiTtsConfig, GoogleAI
# Single-speaker synthesisresponse = 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=1For 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.
Context caching
Section titled “Context caching”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)Next steps
Section titled “Next steps”- Learn about generating content
- Explore creating flows
- For IAM-authenticated Google Cloud workloads, see the Gemini Enterprise plugin