google

Documentation

Overview

Package google provides a Google Gemini API client implementing gains provider interfaces.

This package wraps the Google GenAI SDK to provide Gemini model access through the gains unified interface.

Supported Features

• Chat completions via [gains.ChatProvider]
• Text embeddings via [gains.EmbeddingProvider]
• Image generation via [gains.ImageProvider] (Imagen models)
• Tool/function calling
• Multimodal inputs (images)
• Structured JSON output with schema validation

Available Models

Chat models:

• Gemini3Pro: Latest flagship model
• Gemini3DeepThink: Enhanced reasoning capabilities
• Gemini25Pro: Previous generation flagship
• Gemini25Flash: Fast and cost-effective (recommended default)
• Gemini25FlashLite: Most cost-effective option

Image models:

• Imagen4: Standard image generation
• Imagen4Fast: Faster generation
• Imagen4Ultra: Highest quality

Embedding models:

• GeminiEmbedding001: 3072 dimensions (recommended)

Basic Usage

Note: Google client requires a context for initialization:

client, err := google.New(ctx, os.Getenv("GOOGLE_API_KEY"))
if err != nil {
    log.Fatal(err)
}

messages := []gains.Message{
    {Role: gains.RoleUser, Content: "What's the weather like on Mars?"},
}

resp, err := client.Chat(ctx, messages)
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Content)

Model Selection

Set a default model at client creation:

client, err := google.New(ctx, apiKey, google.WithModel(google.Gemini3Pro))

Or override per-request:

resp, err := client.Chat(ctx, messages, gains.WithModel(google.Gemini25FlashLite))

Embeddings

Google embeddings support task type hints for better results:

resp, err := client.Embed(ctx, []string{"search query"},
    gains.WithEmbeddingModel(google.GeminiEmbedding001),
    gains.WithEmbeddingTaskType(gains.EmbeddingTaskTypeRetrievalQuery),
)

Image Generation

resp, err := client.GenerateImage(ctx, "A serene Japanese garden",
    gains.WithImageModel(google.Imagen4Ultra),
    gains.WithImageCount(2),
)
if err != nil {
    log.Fatal(err)
}
for _, img := range resp.Images {
    fmt.Println(img.URL)
}

Pricing

Google has tiered pricing based on context length:

pricing := google.Gemini25Pro.Pricing()
fmt.Printf("Standard: $%.2f/M in, $%.2f/M out\n",
    pricing.InputPerMillion, pricing.OutputPerMillion)
fmt.Printf("Long context (>200K): $%.2f/M in, $%.2f/M out\n",
    pricing.InputPerMillionLong, pricing.OutputPerMillionLong)

Index

• type BlockedError
  • func (e *BlockedError) Error() string
• type ChatModel
  • func (m ChatModel) Pricing() ChatModelPricing
  • func (m ChatModel) String() string
• type ChatModelPricing
• type Client
  • func New(ctx context.Context, apiKey string, opts ...ClientOption) (*Client, error)
  • func (c *Client) Chat(ctx context.Context, messages []ai.Message, opts ...ai.Option) (*ai.Response, error)
  • func (c *Client) ChatStream(ctx context.Context, messages []ai.Message, opts ...ai.Option) (<-chan ai.StreamEvent, error)
  • func (c *Client) Embed(ctx context.Context, texts []string, opts ...ai.EmbeddingOption) (*ai.EmbeddingResponse, error)
  • func (c *Client) GenerateImage(ctx context.Context, prompt string, opts ...ai.ImageOption) (*ai.ImageResponse, error)
• type ClientOption
  • func WithModel(model ChatModel) ClientOption
• type EmbeddingModel
  • func (m EmbeddingModel) Pricing() EmbeddingModelPricing
  • func (m EmbeddingModel) String() string
• type EmbeddingModelPricing
• type ImageModel
  • func (m ImageModel) Pricing() ImageModelPricing
  • func (m ImageModel) String() string
• type ImageModelPricing

Types

type BlockedError

type BlockedError struct {
	Reason string
}

BlockedError indicates the request was blocked by content filtering.

func (*BlockedError) Error

func (e *BlockedError) Error() string

type ChatModel

type ChatModel string

ChatModel represents a Google Gemini chat model.

const (
	// Gemini 3.0 (Latest - November 2025)
	Gemini3Pro       ChatModel = "gemini-3.0-pro"
	Gemini3DeepThink ChatModel = "gemini-3.0-deep-think"

	// Gemini 2.5 Series
	Gemini25Pro       ChatModel = "gemini-2.5-pro"
	Gemini25Flash     ChatModel = "gemini-2.5-flash"
	Gemini25FlashLite ChatModel = "gemini-2.5-flash-lite"

	// DefaultChatModel is the recommended default model.
	DefaultChatModel ChatModel = Gemini25Flash
)

func (ChatModel) Pricing

func (m ChatModel) Pricing() ChatModelPricing

Pricing returns the pricing for this model.

func (ChatModel) String

func (m ChatModel) String() string

String returns the model identifier string.

type ChatModelPricing

type ChatModelPricing struct {
	InputPerMillion      float64 // Standard (<=200K tokens)
	OutputPerMillion     float64 // Standard
	InputPerMillionLong  float64 // Long context (>200K tokens)
	OutputPerMillionLong float64 // Long context
}

ChatModelPricing contains pricing per million tokens (USD). Some models have tiered pricing based on context length.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the Google GenAI SDK to implement ai.ChatProvider.

func New

func New(ctx context.Context, apiKey string, opts ...ClientOption) (*Client, error)

New creates a new Google GenAI client with the given API key.

func (*Client) Chat

func (c *Client) Chat(ctx context.Context, messages []ai.Message, opts ...ai.Option) (*ai.Response, error)

Chat sends a conversation and returns a complete response.

func (*Client) ChatStream

func (c *Client) ChatStream(ctx context.Context, messages []ai.Message, opts ...ai.Option) (<-chan ai.StreamEvent, error)

ChatStream sends a conversation and returns a channel of streaming events.

func (*Client) Embed

func (c *Client) Embed(ctx context.Context, texts []string, opts ...ai.EmbeddingOption) (*ai.EmbeddingResponse, error)

Embed generates embeddings for the provided texts using Google's embedding API.

func (*Client) GenerateImage

func (c *Client) GenerateImage(ctx context.Context, prompt string, opts ...ai.ImageOption) (*ai.ImageResponse, error)

GenerateImage generates images from a text prompt using Imagen.

type ClientOption

type ClientOption func(*Client)

ClientOption configures the Google client.

func WithModel

func WithModel(model ChatModel) ClientOption

WithModel sets the default model for requests.

type EmbeddingModel

type EmbeddingModel string

EmbeddingModel represents a Google text embedding model.

const (
	GeminiEmbedding001 EmbeddingModel = "gemini-embedding-001" // 3072 dimensions, recommended

	// DefaultEmbeddingModel is the recommended default embedding model.
	DefaultEmbeddingModel EmbeddingModel = GeminiEmbedding001
)

func (EmbeddingModel) Pricing

func (m EmbeddingModel) Pricing() EmbeddingModelPricing

Pricing returns the pricing for this embedding model.

func (EmbeddingModel) String

func (m EmbeddingModel) String() string

String returns the model identifier string.

type EmbeddingModelPricing

type EmbeddingModelPricing struct {
	PerMillion float64
}

EmbeddingModelPricing contains per million token pricing (USD).

type ImageModel

type ImageModel string

ImageModel represents a Google Imagen model.

const (
	Imagen4      ImageModel = "imagen-4.0-generate-001"
	Imagen4Fast  ImageModel = "imagen-4.0-fast-generate-001"
	Imagen4Ultra ImageModel = "imagen-4.0-ultra-generate-001"

	// DefaultImageModel is the recommended default image model.
	DefaultImageModel ImageModel = Imagen4
)

func (ImageModel) Pricing

func (m ImageModel) Pricing() ImageModelPricing

Pricing returns the pricing for this image model.

func (ImageModel) String

func (m ImageModel) String() string

String returns the model identifier string.

type ImageModelPricing

type ImageModelPricing struct {
	PerImage float64
}

ImageModelPricing contains per-image pricing (USD).