Skip to main content

​
Overview

The Google GenAI provider gives you access to Gemini models with advanced multimodal capabilities, embeddings, and image generation through Imagen.

​
Installation

npm install @core-ai/google-genai

​
createGoogleGenAI()

Create a Google GenAI provider instance. 
import { createGoogleGenAI } from '@core-ai/google-genai';

const google = createGoogleGenAI({
  apiKey: process.env.GOOGLE_GENAI_API_KEY
});

​
Options

​
apiKey
string
Your Google AI API key. Defaults to GOOGLE_GENAI_API_KEY environment variable.
​
apiVersion
string
API version to use (e.g., 'v1', 'v1beta'). Defaults to the latest stable version.
​
baseUrl
string
Custom base URL for API requests.
​
client
GoogleGenAI
Provide your own configured Google GenAI client instance.

​
Returns

GoogleGenAIProvider - Provider instance with methods to create models.

​
Provider Methods

​
chatModel()

Create a chat model instance. 
const model = google.chatModel('gemini-3-pro');
​
modelId
string
required
Model identifier. See Supported Models below.

​
embeddingModel()

Create an embedding model instance. 
const embeddings = google.embeddingModel('text-embedding-004');
​
modelId
string
required
Embedding model identifier.

​
imageModel()

Create an image generation model instance. 
const imageGen = google.imageModel('imagen-3.0');
​
modelId
string
required
Image model identifier.

​
Supported Models

​
Chat Models

Latest generation with thinking level control.
  • gemini-3-pro - Most capable multimodal model
Previous generation with thinking budget control.
  • gemini-2.5-pro - High capability, budget-based thinking
  • gemini-2.5-flash - Fast with optional thinking
  • gemini-2.5-flash-lite - Lightweight with optional thinking

​
Embedding Models

  • text-embedding-004 - Latest text embedding model
  • text-embedding-003 - Previous generation

​
Image Models

  • imagen-3.0 - Latest image generation model
  • imagen-2.0 - Previous generation

​
Capabilities

FeatureSupport
Chat Completion✓
Streaming✓
Function Calling✓
Vision✓
Reasoning Effort✓
Embeddings✓
Image Generation✓

​
Thinking Modes

Gemini models use two different thinking control mechanisms:

​
Thinking Level (Gemini 3)

Used by Gemini 3 models. Simple HIGH/LOW thinking control. 
const result = await generateText({
  model: google.chatModel('gemini-3-pro'),
  prompt: 'Complex problem...',
  reasoning: {
    effort: 'high' // Maps to HIGH thinking level
  }
});
Mapping:
  • 'minimal', 'low', 'medium' → 'LOW'
  • 'high', 'max' → 'HIGH'
Gemini 3 models cannot disable thinking completely.

​
Thinking Budget (Gemini 2.5)

Used by Gemini 2.5 models. Fine-grained token budget control. 
const result = await generateText({
  model: google.chatModel('gemini-2.5-pro'),
  prompt: 'Solve this...',
  reasoning: {
    effort: 'high' // Allocates 32,768 thinking tokens
  }
});
Token budgets:
  • minimal → 1,024 tokens
  • low → 4,096 tokens
  • medium → 16,384 tokens
  • high/max → 32,768 tokens
gemini-2.5-flash and gemini-2.5-flash-lite can disable thinking by omitting the reasoning parameter.

​
Examples

​
Basic Chat

import { createGoogleGenAI } from '@core-ai/google-genai';
import { generateText } from '@core-ai/core-ai';

const google = createGoogleGenAI({
  apiKey: process.env.GOOGLE_GENAI_API_KEY
});

const result = await generateText({
  model: google.chatModel('gemini-3-pro'),
  prompt: 'Explain machine learning'
});

console.log(result.text);

​
Reasoning with Thinking

const result = await generateText({
  model: google.chatModel('gemini-3-pro'),
  prompt: 'Analyze this complex scenario...',
  reasoning: {
    effort: 'high'
  }
});

if (result.reasoning) {
  console.log('Thinking tokens used:', result.reasoning.thinkingTokens);
}

​
Multimodal Input

const result = await generateText({
  model: google.chatModel('gemini-3-pro'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe this image and video' },
        {
          type: 'image',
          image: 'https://example.com/photo.jpg'
        },
        {
          type: 'file',
          mimeType: 'video/mp4',
          data: videoBuffer
        }
      ]
    }
  ]
});

​
Embeddings

import { embed } from '@core-ai/core-ai';

const result = await embed({
  model: google.embeddingModel('text-embedding-004'),
  value: 'Text to embed'
});

console.log(result.embedding); // number[]

​
Image Generation

import { generateImage } from '@core-ai/core-ai';

const result = await generateImage({
  model: google.imageModel('imagen-3.0'),
  prompt: 'A serene mountain landscape at dawn',
  size: '1024x1024',
  n: 1
});

console.log(result.images);

​
Function Calling

import { generateText, tool } from '@core-ai/core-ai';
import { z } from 'zod';

const result = await generateText({
  model: google.chatModel('gemini-3-pro'),
  prompt: 'Calculate the area of a circle with radius 5',
  tools: {
    calculateArea: tool({
      description: 'Calculate circle area',
      parameters: z.object({
        radius: z.number()
      }),
      execute: async ({ radius }) => {
        return { area: Math.PI * radius ** 2 };
      }
    })
  }
});

​
Streaming

import { streamText } from '@core-ai/core-ai';

const stream = await streamText({
  model: google.chatModel('gemini-2.5-flash'),
  prompt: 'Write a story about...'
});

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

​
Custom API Version

const google = createGoogleGenAI({
  apiKey: process.env.GOOGLE_GENAI_API_KEY,
  apiVersion: 'v1beta' // Use beta features
});

​
Without Thinking (Flash models)

// Gemini 2.5 Flash can skip thinking for faster responses
const result = await generateText({
  model: google.chatModel('gemini-2.5-flash'),
  prompt: 'Quick answer needed'
  // No reasoning parameter = no thinking overhead
});

​
Error Handling

import { APIError } from '@core-ai/core-ai';

try {
  const result = await generateText({
    model: google.chatModel('gemini-3-pro'),
    prompt: 'Hello!'
  });
} catch (error) {
  if (error instanceof APIError) {
    console.error('Google AI API error:', error.message);
    console.error('Status:', error.statusCode);
  }
}

​
Best Practices

  • Gemini 3 Pro - Best for complex multimodal tasks
  • Gemini 2.5 Pro - When you need fine-grained thinking budget control
  • Gemini 2.5 Flash - Fast responses with optional thinking
  • Flash Lite - Lightweight tasks, cost-sensitive applications
  • Use HIGH effort for complex reasoning in Gemini 3
  • Use thinking budget for precise control in Gemini 2.5
  • Disable thinking on Flash models for simple queries to save costs
  • Gemini excels at understanding images, videos, and audio
  • Provide clear instructions for multimodal tasks
  • Consider using Flash models for vision-only tasks

​
Model Comparison

ModelThinking ControlCan DisableBest For
Gemini 3 ProLevel (HIGH/LOW)✗Complex multimodal
Gemini 2.5 ProBudget (tokens)✗Controlled reasoning
Gemini 2.5 FlashBudget (tokens)✓Fast + flexible
Gemini 2.5 Flash LiteBudget (tokens)✓Lightweight tasks

OpenAI Provider

GPT models and DALL-E image generation

Anthropic Provider

Claude models with extended thinking

Multi-Modal Guide

Learn how to work with vision and audio