Google AI plugin

Use Gemini models, Imagen image generation, and text embeddings from the Google AI (Gemini Developer API) and Vertex AI through a single unified plugin.

The @genkit-ai/google-genai package is the unified Google plugin for Genkit. It exports two initializers:

• googleAI — connects to the Gemini Developer API (Google AI Studio). Best for prototyping, quick experiments, and apps that don’t need a Google Cloud project.
• vertexAI — connects to Google Cloud Vertex AI. Best for production workloads, enterprise compliance, and access to Vertex-only features. See the Vertex AI plugin page for the full Vertex story.

This page covers googleAI.

The older @genkit-ai/googleai package is superseded by @genkit-ai/google-genai. Migrate by changing your import and plugin initializer — the model reference syntax is identical.

Installation

TypeScript

npm

npm install @genkit-ai/google-genai

Go

go get github.com/firebase/genkit/go/plugins/googlegenai

Python

pip install genkit-google-genai-plugin

Configuration

API key

Obtain a free API key from Google AI Studio and set it as an environment variable:

export GEMINI_API_KEY=your_api_key
# GOOGLE_API_KEY is also accepted as a fallback

Or pass it directly at plugin init time (useful for testing, not recommended for production):

TypeScript

import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({
  plugins: [
    googleAI(),
    // Or with an explicit key:
    // googleAI({ apiKey: process.env.MY_KEY }),
  ],
});

Go

import (
  "github.com/firebase/genkit/go/genkit"
  "github.com/firebase/genkit/go/plugins/googlegenai"
)

g := genkit.Init(ctx,
  genkit.WithPlugins(&googlegenai.GoogleAI{
    APIKey: "your-api-key", // Optional: defaults to GEMINI_API_KEY or GOOGLE_API_KEY
  }),
)

Python

from genkit import Genkit
from genkit.plugins.google_genai import GoogleAI

ai = Genkit(
    plugins=[GoogleAI()],  # reads GEMINI_API_KEY from environment
    # Or: plugins=[GoogleAI(api_key='your-key')]
)

Plugin options (TypeScript)

The GoogleAIPluginOptions interface exposes these fields:

interface GoogleAIPluginOptions {
  /**
   * API key to authenticate with the Gemini API.
   * Defaults to GEMINI_API_KEY or GOOGLE_API_KEY env vars.
   * Set to `false` to require a per-request apiKey in model config.
   */
  apiKey?: string | false;

  /** Override the default API version (e.g. 'v1'). */
  apiVersion?: string;

  /** Override the default base URL. */
  baseUrl?: string;

  /** Additional headers sent with every request. */
  customHeaders?: Record<string, string>;

  /** Use legacy responseSchema field instead of responseJsonSchema. */
  legacyResponseSchema?: boolean;
}

Available models

The plugin dynamically discovers available models from the API. Pre-registered known models include:

Model name	Best for
gemini-2.5-pro	Complex reasoning, long context
gemini-2.5-flash	Fast, cost-effective general tasks
gemini-2.5-flash-lite	Lowest latency, simple tasks
gemini-2.5-flash-image	Native image output alongside text
gemini-2.5-flash-preview-tts	Text-to-speech
gemini-2.5-pro-preview-tts	High-quality TTS
gemma-3-27b-it	Open-weight text generation
gemma-3-12b-it	Smaller open-weight model
imagen-4.0-generate-001	Photorealistic image generation
imagen-4.0-fast-generate-001	Faster image generation
imagen-4.0-ultra-generate-001	Highest quality image generation
gemini-embedding-001	Text embeddings (768 dims)
gemini-embedding-2-preview	Multimodal embeddings (3072 dims)

You can use any model ID supported by the underlying SDK — new models appear automatically without a plugin update.

Basic text generation

TypeScript

import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({ plugins: [googleAI()] });

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Explain how neural networks learn.',
});

console.log(response.text);

Go

g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

resp, err := genkit.Generate(ctx, g,
  ai.WithModelName("googleai/gemini-2.5-flash"),
  ai.WithPrompt("Explain how neural networks learn."),
)
fmt.Println(resp.Text())

Python

ai = Genkit(plugins=[GoogleAI()])

response = await ai.generate(
    model='googleai/gemini-2.5-flash',
    prompt='Explain how neural networks learn.',
)
print(response.text)

Model configuration

Pass a GeminiConfig object alongside the model reference to tune generation:

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash', {
    temperature: 0.7,
    maxOutputTokens: 1024,
    safetySettings: [
      {
        category: 'HARM_CATEGORY_HATE_SPEECH',
        threshold: 'BLOCK_ONLY_HIGH',
      },
    ],
    // Enable thinking for complex reasoning tasks
    thinkingConfig: {
      thinkingBudget: 2048,
      includeThoughts: false,
    },
  }),
  prompt: 'Walk me through this algorithm step by step.',
});

Available GeminiConfig fields include:

Field	Type	Description
temperature	number (0–2)	Sampling randomness. Default 1.0.
topP	number (0–1)	Nucleus sampling probability. Default 0.95.
maxOutputTokens	number	Token cap on the response.
stopSequences	string[]	Stop generation at these strings.
safetySettings	array	Per-category content filtering thresholds.
thinkingConfig	object	Control the thinking budget for Gemini 2.5+.
codeExecution	boolean	Allow the model to write and run Python code.
googleSearch	boolean | object	Ground responses with live Google Search.
functionCallingConfig	object	Control when tools are invoked (AUTO / ANY / NONE).
responseModalities	('TEXT'|'IMAGE'|'AUDIO')[]	Request specific output types.
contextCache	boolean	Reuse cached input tokens.

Structured output

TypeScript

import { z } from 'genkit';

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.string()),
  steps: z.array(z.string()),
});

const { output } = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Give me a recipe for banana bread.',
  output: { schema: RecipeSchema },
});

console.log(output.name);

Go

type Recipe struct {
  Name        string   `json:"name"`
  Ingredients []string `json:"ingredients"`
  Steps       []string `json:"steps"`
}

recipe, _, err := genkit.GenerateData[Recipe](ctx, g,
  ai.WithModelName("googleai/gemini-2.5-flash"),
  ai.WithPrompt("Give me a recipe for banana bread."),
)
fmt.Println(recipe.Name)

Multimodal input

Gemini 2.5 models accept text, images, audio, video, and PDFs in the same request:

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  messages: [
    {
      role: 'user',
      content: [
        { text: 'What is in this image?' },
        { media: { url: 'https://example.com/photo.jpg', contentType: 'image/jpeg' } },
      ],
    },
  ],
});

For Gemini 2.5+ models, external HTTPS URLs are passed directly to the API. For Gemini 2.0 models, Genkit automatically downloads external media and inlines it (up to 100 MB).

Function calling (tools)

const weatherTool = ai.defineTool(
  {
    name: 'getWeather',
    description: 'Returns the current weather for a city.',
    inputSchema: z.object({ city: z.string() }),
    outputSchema: z.object({ temperature: z.number(), condition: z.string() }),
  },
  async ({ city }) => fetchWeather(city)
);

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'What is the weather like in London?',
  tools: [weatherTool],
});

Embeddings

TypeScript

const embeddings = await ai.embed({
  embedder: googleAI.embedder('gemini-embedding-001'),
  content: 'Machine learning optimises model parameters.',
});
// embeddings[0].embedding → number[]

Go

res, err := genkit.Embed(ctx, g,
  ai.WithEmbedderName("googleai/gemini-embedding-001"),
  ai.WithTextDocs("Machine learning optimises model parameters."),
)
fmt.Println(res.Embeddings[0].Embedding)

Python

result = await ai.embed(
    embedder='googleai/gemini-embedding-001',
    content='Machine learning optimises model parameters.',
)

Embedder config

Option	Description
taskType	Hint about downstream use (RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, SEMANTIC_SIMILARITY, etc.)
outputDimensionality	Truncate to a smaller dimension (1–768, model-dependent).
title	Document title, used with RETRIEVAL_DOCUMENT task type.

Image generation (Imagen)

const response = await ai.generate({
  model: googleAI.model('imagen-4.0-generate-001', {
    numberOfImages: 2,
    aspectRatio: '16:9',
  }),
  prompt: 'A serene Japanese garden at sunrise, watercolour style.',
});

const image = response.media();
// image.url contains a base64 data URI

Google Search grounding

Ground responses with real-time web data:

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash', {
    googleSearch: true,
  }),
  prompt: 'What are the top AI announcements this week?',
});

Related pages

Vertex AI plugin

Enterprise Gemini access with GCP credentials.

Structured output

Type-safe JSON generation with Zod schemas.

Multimodal

Working with images, audio, and video.

Tools

Give models access to functions and external data.