Google AI Provider (Gemini Developer API)

The Google AI provider gives you quick access to Google’s generative AI models through the Gemini Developer API. This provider is ideal for prototyping and smaller projects that don’t require the full infrastructure of Google Cloud.

This provider is part of the unified @genkit-ai/google-genai package, which also includes Vertex AI. For enterprise features, see Vertex AI.

Installation

npm install @genkit-ai/google-genai

Setup

Get an API Key

Visit Google AI Studio
Create or select a project
Generate an API key
Set it as an environment variable:

export GEMINI_API_KEY=your-api-key
# or
export GOOGLE_API_KEY=your-api-key

Configure the Plugin

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

const ai = genkit({
  plugins: [
    googleAI(),
    // Or with explicit API key:
    // googleAI({ apiKey: 'your-api-key' }),
  ],
});

Available Models

Text Generation (Gemini)

The Gemini 2.5 series offers the latest and most powerful models:

gemini-2.5-flash - Balanced speed and performance, best default choice
gemini-2.5-pro - Most powerful, for complex reasoning tasks
gemini-2.5-flash-lite - Fastest, for simple prompts

All Gemini models support:

Multi-turn conversations
Multimodal input (text, images, audio, video)
Function calling (tools)
System instructions
JSON output mode

Image Generation (Imagen)

imagen-3.0-generate-002 - High-quality image generation
imagen-3.0-fast-generate-001 - Faster image generation

Video Generation (Veo)

veo-002 - Generate videos from text prompts

Embeddings

gemini-embedding-001 - 768-dimensional text embeddings
text-embedding-004 - Latest embedding model

Usage Examples

Basic Text Generation

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 photosynthesis works in simple terms.',
});

console.log(response.text());

Multimodal Input

Gemini models can process images, audio, and video:

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: [
    { text: 'What is in this image? Describe it in detail.' },
    { media: { url: 'https://example.com/image.jpg' } },
  ],
});

console.log(response.text());

Streaming Responses

const { response, stream } = await ai.generateStream({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Write a short story about a robot.',
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text());
}

Function Calling

import { z } from 'genkit';

const getWeather = ai.defineTool(
  {
    name: 'getWeather',
    description: 'Get the current weather for a location',
    inputSchema: z.object({
      location: z.string().describe('City name'),
    }),
    outputSchema: z.string(),
  },
  async ({ location }) => {
    // Fetch weather data
    return `It's sunny and 72°F in ${location}`;
  }
);

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'What\'s the weather like in San Francisco?',
  tools: [getWeather],
});

console.log(response.text());

JSON Output Mode

import { z } from 'genkit';

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'List three colors',
  output: {
    schema: z.object({
      colors: z.array(z.string()),
    }),
  },
});

console.log(response.output());
// { colors: ['red', 'blue', 'green'] }

Image Generation with Imagen

const response = await ai.generate({
  model: googleAI.model('imagen-3.0-generate-002'),
  prompt: 'A serene mountain landscape at sunset with a lake reflection',
});

const image = response.media();
if (image) {
  console.log('Generated image:', image.url);
}

Text Embeddings

const embeddings = await ai.embed({
  embedder: googleAI.embedder('gemini-embedding-001'),
  content: 'Genkit is a framework for building AI applications',
});

console.log(embeddings); // 768-dimensional vector

Using in a Flow

import { z } from 'genkit';

export const summarizeFlow = ai.defineFlow(
  {
    name: 'summarize',
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (text) => {
    const response = await ai.generate({
      model: googleAI.model('gemini-2.5-flash'),
      prompt: `Summarize this text in 2-3 sentences:\n\n${text}`,
    });
    return response.text();
  }
);

Configuration Options

Model Configuration

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Tell me a joke',
  config: {
    temperature: 1.0,        // Creativity (0.0 - 2.0)
    topK: 40,                 // Token sampling
    topP: 0.95,               // Nucleus sampling
    maxOutputTokens: 1024,    // Max response length
    stopSequences: ['END'],   // Stop generation triggers
  },
});

Safety Settings

Control content filtering:

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Write a story',
  config: {
    safetySettings: [
      {
        category: 'HARM_CATEGORY_HATE_SPEECH',
        threshold: 'BLOCK_MEDIUM_AND_ABOVE',
      },
      {
        category: 'HARM_CATEGORY_DANGEROUS_CONTENT',
        threshold: 'BLOCK_ONLY_HIGH',
      },
    ],
  },
});

System Instructions

const response = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  system: 'You are a helpful math tutor. Explain concepts clearly and provide examples.',
  prompt: 'How do I solve quadratic equations?',
});

Model Selection Guide

When to Use Each Model

gemini-2.5-flash (recommended default):

General-purpose tasks
Chat applications
Content generation
Code assistance
Balanced cost and performance

gemini-2.5-pro:

Complex reasoning tasks
Research and analysis
Technical explanations
When accuracy is critical

gemini-2.5-flash-lite:

Simple queries
High-volume applications
When speed is critical
Cost-sensitive use cases

Google AI vs Vertex AI

Feature	Google AI	Vertex AI
Setup	Simple API key	GCP project + IAM
Best for	Prototyping, small apps	Production, enterprise
Authentication	API key	ADC or API key
Pricing	Pay-per-use	Committed use discounts
Model access	Gemini, Imagen	Gemini, Imagen, Lyria, Model Garden
Features	Basic	Advanced (fine-tuning, governance, Vector Search)

Choose Google AI when:

Building prototypes or small projects
Want quick setup with minimal configuration
Don’t need advanced GCP integrations

Choose Vertex AI when:

Building production applications
Need IAM-based access control
Want to use Model Garden (Anthropic, Meta, etc.)
Need Vector Search for RAG
Require enterprise features

Using Both Providers

You can configure both Google AI and Vertex AI in the same application:

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

const ai = genkit({
  plugins: [
    googleAI(),      // For development and prototyping
    vertexAI(),      // For production features
  ],
});

// Use Google AI for quick tasks
const devResponse = await ai.generate({
  model: googleAI.model('gemini-2.5-flash'),
  prompt: 'Quick test',
});

// Use Vertex AI for production
const prodResponse = await ai.generate({
  model: vertexAI.model('gemini-2.5-pro'),
  prompt: 'Production query',
});

Troubleshooting

API Key Not Found

Error: Please pass in the API key or set the GEMINI_API_KEY environment variable

Solution: Set the GEMINI_API_KEY or GOOGLE_API_KEY environment variable, or pass it explicitly:

googleAI({ apiKey: 'your-api-key' })

Rate Limiting

If you hit rate limits, the API will return a 429 error. Implement exponential backoff:

import { retry } from 'genkit/retry';

const response = await retry(
  () => ai.generate({
    model: googleAI.model('gemini-2.5-flash'),
    prompt: 'Hello',
  }),
  { maxRetries: 3, backoff: 'exponential' }
);

Content Blocked by Safety Filters

If your content is blocked, adjust safety settings or rephrase your prompt:

config: {
  safetySettings: [
    {
      category: 'HARM_CATEGORY_DANGEROUS_CONTENT',
      threshold: 'BLOCK_ONLY_HIGH',
    },
  ],
}

Best Practices

Use environment variables for API keys, never hardcode them
Set appropriate safety settings for your use case
Use gemini-2.5-flash as your default model
Implement error handling for API failures
Cache embeddings to avoid redundant API calls
Use streaming for better user experience with long responses

Next Steps

Vertex AI Provider - Enterprise features and Model Garden
Prompt Engineering - Write better prompts
Flows - Build AI workflows
RAG - Retrieval-augmented generation

Overview

Getting Started

Core Concepts

Guides

Model Providers

Deployment

Developer Tools

​Installation

​Setup

​Get an API Key

​Configure the Plugin

​Available Models

​Text Generation (Gemini)

​Image Generation (Imagen)

​Video Generation (Veo)

​Embeddings

​Usage Examples

​Basic Text Generation

​Multimodal Input

​Streaming Responses

​Function Calling

​JSON Output Mode

​Image Generation with Imagen

​Text Embeddings

​Using in a Flow

​Configuration Options

​Model Configuration

​Safety Settings

​System Instructions

​Model Selection Guide

​When to Use Each Model

​Google AI vs Vertex AI

​Using Both Providers

​Troubleshooting

​API Key Not Found

​Rate Limiting

​Content Blocked by Safety Filters

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Installation

Setup

Get an API Key

Configure the Plugin

Available Models

Text Generation (Gemini)

Image Generation (Imagen)

Video Generation (Veo)

Embeddings

Usage Examples

Basic Text Generation

Multimodal Input

Streaming Responses

Function Calling

JSON Output Mode

Image Generation with Imagen

Text Embeddings

Using in a Flow

Configuration Options

Model Configuration

Safety Settings

System Instructions

Model Selection Guide

When to Use Each Model

Google AI vs Vertex AI

Using Both Providers

Troubleshooting

API Key Not Found

Rate Limiting

Content Blocked by Safety Filters

Best Practices

Next Steps