◈ API / SDK/2026-03-27Intermediate

Building with the Gemini API in Go — Text Generation, Image Analysis, Streaming, and Production Design

Implement the Gemini API in Go with the official Google Gen AI SDK — text generation, image analysis, and streaming, plus the production concerns quickstarts skip: goroutine throttling, timeout design, and model selection, all with complete code.

gemini-api²⁷⁷ go golang sdk³ multimodal⁴⁴ streaming²⁸ production¹⁴⁰

✦ Premium Article

Why Go, and What This Guide Covers

When you run AI backends as an indie developer, raw response speed matters — but so does how many requests a single server can absorb. When I rewrote a small relay service that fans out to the Gemini API from several of my apps in Go, both the resident memory and the cold-start time dropped noticeably. Goroutine-based concurrency, plus the ease of shipping a single self-contained binary: those two things are the quiet reason I reach for Go.

This guide uses the official Google Gen AI Go SDK (google.golang.org/genai) to implement text generation, multimodal image analysis, streaming, and multi-turn chat. From there it goes into the parts most quickstarts skip — concurrency throttling, timeout design, and model selection — the questions you inevitably hit in production.

Go fundamentals are assumed; prior experience with AI APIs is not. If you want the bigger picture first, see our Gemini API Quickstart guide.

Setting Up Your Environment

Prerequisites

To get started with the Gemini API in Go, you'll need three things:

Go 1.23 or later installed on your machine
A Google AI Studio API key (available for free at aistudio.google.com)
An internet connection

Project Initialization and SDK Installation

Create a new Go module and install the official SDK:

# Create a project directory
mkdir gemini-go-app && cd gemini-go-app
 
# Initialize a Go module
go mod init gemini-go-app
 
# Install the Google Gen AI Go SDK
go get google.golang.org/genai

Configuring Your API Key

Set your API key as the GEMINI_API_KEY environment variable. The SDK automatically reads this variable, so you don't need to hardcode the key in your source code.

# Set the environment variable (Linux / macOS)
export GEMINI_API_KEY="YOUR_API_KEY"

Never hardcode API keys in your source code or commit them to version control repositories.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦A goroutine and semaphore pattern for safely throttling concurrent requests

✦Context timeouts and a measured, production-minded failure design

✦Model selection guided by measured latency and cost trade-offs

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Basic Text Generation

Let's start with the simplest use case — sending a text prompt to Gemini and receiving a response.

package main
 
import (
	"context"
	"fmt"
	"log"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
 
	// Create a client (automatically reads the GEMINI_API_KEY env var)
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// Generate content
	result, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash", // Model to use
		genai.Text("List three key strengths of Go programming in brief."),
		nil, // Options (nil for defaults)
	)
	if err != nil {
		log.Fatal(err)
	}
 
	// Print the response
	fmt.Println(result.Text())
}
 
// Expected output:
// 1. **Fast Compilation and Execution**: Go compiles extremely quickly...
// 2. **Built-in Concurrency with Goroutines**: Lightweight goroutines make...
// 3. **Simple Language Design**: Go's minimalist syntax keeps codebases...

Passing nil as the second argument to genai.NewClient creates a client with default settings: the Google AI backend and API key authentication via the GEMINI_API_KEY environment variable.

Customizing Generation Parameters

To control the creativity or length of the output, use genai.GenerateContentConfig.

package main
 
import (
	"context"
	"fmt"
	"log"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// Configure generation parameters
	temperature := float32(0.3)
	maxTokens := int32(500)
 
	config := &genai.GenerateContentConfig{
		Temperature:     &temperature, // Lower for more deterministic output
		MaxOutputTokens: maxTokens,    // Cap on output token count
		SystemInstruction: &genai.Content{
			Parts: []*genai.Part{
				genai.NewPartFromText("You are an expert Go programmer. Give concise, practical answers."),
			},
		},
	}
 
	result, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash",
		genai.Text("When should I use the defer statement in Go?"),
		config,
	)
	if err != nil {
		log.Fatal(err)
	}
 
	fmt.Println(result.Text())
}

A Temperature close to 0 produces more deterministic output, while values closer to 1.0 yield more creative responses. For tasks requiring precision — like API reference generation or code generation — a value between 0.1 and 0.3 works well.

Multimodal Input — Image Analysis

One of Gemini's strongest features is its ability to process text and images together. Here's how to analyze a local image file.

package main
 
import (
	"context"
	"fmt"
	"log"
	"os"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// Read a local image file
	imageBytes, err := os.ReadFile("sample.jpg")
	if err != nil {
		log.Fatal("Failed to read image:", err)
	}
 
	// Build a multimodal request
	parts := []*genai.Part{
		genai.NewPartFromBytes(imageBytes, "image/jpeg"),
		genai.NewPartFromText("Describe what you see in this image in detail."),
	}
 
	result, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash",
		genai.NewContentFromParts(parts, "user"),
		nil,
	)
	if err != nil {
		log.Fatal(err)
	}
 
	fmt.Println(result.Text())
}
 
// Expected output:
// The image shows a cherry blossom tree in full bloom against a clear blue sky.
// The delicate pink petals are...

The SDK supports JPEG, PNG, WebP, GIF, and other common image formats. Make sure to specify the correct MIME type as the second argument to genai.NewPartFromBytes.

Streaming Responses

For longer outputs, you can receive tokens in real time as they're generated instead of waiting for the entire response. This dramatically improves the user experience for chat applications and CLI tools.

package main
 
import (
	"context"
	"fmt"
	"log"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// Stream content generation
	stream := client.Models.GenerateContentStream(ctx,
		"gemini-2.5-flash",
		genai.Text("Walk me through building a simple HTTP server in Go, step by step."),
		nil,
	)
 
	// Print each chunk as it arrives
	for chunk, err := range stream {
		if err != nil {
			log.Fatal(err)
		}
		if chunk.Text() != "" {
			fmt.Print(chunk.Text())
		}
	}
	fmt.Println() // Final newline
}

GenerateContentStream supports Go 1.23's range-over-func (iterator) pattern, so you can consume the stream with a clean for ... range loop. For more advanced streaming patterns, take a look at our Streaming Responses and Multi-Turn Chat Implementation Guide.

Multi-Turn Conversations

For conversational applications like chatbots, you need to maintain context across messages. The SDK's Chat feature handles conversation history automatically.

package main
 
import (
	"context"
	"fmt"
	"log"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// Start a chat session
	config := &genai.GenerateContentConfig{
		SystemInstruction: &genai.Content{
			Parts: []*genai.Part{
				genai.NewPartFromText("You are a friendly Go programming tutor."),
			},
		},
	}
	chat, err := client.Chats.Create(ctx, "gemini-2.5-flash", config, nil)
	if err != nil {
		log.Fatal(err)
	}
 
	// First exchange
	resp1, err := chat.SendMessage(ctx, genai.Text("What is a goroutine in Go?"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("AI:", resp1.Text())
 
	// Second exchange (contextual follow-up)
	resp2, err := chat.SendMessage(ctx, genai.Text("Can you show me a simple example combining that with channels?"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("AI:", resp2.Text())
}

chat.SendMessage maintains the conversation history internally, so in the second exchange, Gemini correctly understands that "that" refers to goroutines from the first answer.

Error Handling Best Practices

In production, you need to handle rate limits and network errors gracefully. Here's an implementation with exponential backoff retry logic.

package main
 
import (
	"context"
	"fmt"
	"log"
	"math"
	"time"
 
	"google.golang.org/genai"
)
 
// retryGenerateContent retries content generation with exponential backoff
func retryGenerateContent(
	ctx context.Context,
	client *genai.Client,
	model string,
	prompt string,
	maxRetries int,
) (*genai.GenerateContentResponse, error) {
	var lastErr error
 
	for i := 0; i < maxRetries; i++ {
		result, err := client.Models.GenerateContent(ctx,
			model,
			genai.Text(prompt),
			nil,
		)
		if err == nil {
			return result, nil
		}
		lastErr = err
 
		// Exponential backoff (1s, 2s, 4s...)
		wait := time.Duration(math.Pow(2, float64(i))) * time.Second
		log.Printf("Retry %d/%d (waiting %v): %v", i+1, maxRetries, wait, err)
		time.Sleep(wait)
	}
 
	return nil, fmt.Errorf("failed after %d retries: %w", maxRetries, lastErr)
}
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	result, err := retryGenerateContent(ctx, client, "gemini-2.5-flash",
		"What are Go error handling best practices?", 3)
	if err != nil {
		log.Fatal("Request ultimately failed:", err)
	}
 
	fmt.Println(result.Text())
}

For a comprehensive look at error handling strategies with the Gemini API, see our Gemini API Error Handling & Retry Patterns Guide.

Throttling Concurrent Requests with Goroutines and a Semaphore

Concurrency is where Go shines, but the Gemini API enforces a requests-per-minute (RPM) ceiling. Spawn goroutines without restraint and you'll hit 429 RESOURCE_EXHAUSTED almost immediately. The fix is a lightweight semaphore built from a buffered channel: cap the number of in-flight calls while processing a batch of prompts.

package main
 
import (
	"context"
	"fmt"
	"log"
	"sync"
 
	"google.golang.org/genai"
)
 
// generateBatch runs generation concurrently with at most `concurrency` goroutines
func generateBatch(
	ctx context.Context,
	client *genai.Client,
	prompts []string,
	concurrency int,
) []string {
	results := make([]string, len(prompts))
	sem := make(chan struct{}, concurrency) // caps in-flight requests
	var wg sync.WaitGroup
 
	for i, prompt := range prompts {
		wg.Add(1)
		go func(idx int, p string) {
			defer wg.Done()
			sem <- struct{}{}        // block until a slot frees up
			defer func() { <-sem }() // release the slot when done
 
			resp, err := client.Models.GenerateContent(ctx,
				"gemini-2.5-flash", genai.Text(p), nil)
			if err != nil {
				results[idx] = fmt.Sprintf("[error] %v", err)
				return
			}
			results[idx] = resp.Text()
		}(i, prompt)
	}
 
	wg.Wait()
	return results
}
 
func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	prompts := []string{
		"Difference between slices and arrays in one sentence",
		"Order of defer execution in one sentence",
		"Meaning of directional channels in one sentence",
	}
	for i, out := range generateBatch(ctx, client, prompts, 2) {
		fmt.Printf("[%d] %s\n", i, out)
	}
}

The key is not to be greedy with concurrency. On the free tier, start around 2–4 and raise it gradually while watching your rate-limit logs. Writing each result to its own results[idx] slot lets you preserve order without introducing a lock over shared state. The work runs concurrently; the write targets stay separate. That single decision pays off every time you have to debug later.

Timeouts and Context Design for Production

context.Background() is convenient while learning, but using it as-is in production leaves you exposed: if the network stalls, the request may never return. The standard practice is to give every call a deadline.

// Give each call its own deadline
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
 
result, err := client.Models.GenerateContent(ctx,
	"gemini-2.5-flash", genai.Text(prompt), nil)
if err != nil {
	// You can branch on whether it timed out
	if errors.Is(err, context.DeadlineExceeded) {
		log.Println("Generation timed out. Reconsider prompt length or model.")
	}
	return err
}

Here are the values worth deciding up front, informed by real measurements.

Type of work	Suggested timeout	Notes
Short classification / summary (Flash)	15–30 s	Usually returns in seconds; leave headroom for congestion
Long-form or code generation	45–90 s	Grows with MaxOutputTokens
Streaming	10 s to first chunk + overall cap	Aborting early on a slow first chunk protects UX

Think of timeouts and retries as a pair. Make a single deadline too short and you simply add retries, which can lengthen the total time — so work backward so that "one deadline x max retries" stays within what a user is willing to wait.

Model Selection and Measured Latency vs. Cost

Which model you name shapes both experience and cost. As of 2026, gemini-flash-latest works as an alias pointing at the newest stable Flash, which makes it easy to track model updates. For production paths where you want fixed behavior, a pinned version name is safer.

Sending the same prompt (roughly 400 input tokens, 300 output) 20 times each against my relay server, the rough tendencies I observed were as follows. Numbers vary with environment and network, so treat them as a way to get your bearings rather than a benchmark.

Use	Perceived latency	Relative cost	Good fit for
Flash tier	Fast (~1-3 s)	Low	Classification, summaries, chat replies, large batches
Pro tier	Slower (~3-8 s)	High	Complex reasoning, long-form design, code generation

The implementation guideline is simple: build with Flash first, then swap in Pro only where quality falls short of the requirement. Reaching for Pro from the start tends to overspend on both latency and cost. Keep the model name in a config file or environment variable, and switching between gemini-2.5-flash and gemini-flash-latest costs no code change — which makes side-by-side comparison in production far easier.

Summary

With the official Go SDK, text generation, multimodal input, streaming, and multi-turn chat come together in remarkably little code. Once you look toward production, three things form the foundation that protects both experience and cost: semaphore-based throttling of concurrent requests, per-call timeouts, and model selection grounded in real measurements.

As a next step, pick one prompt from your own project and run it with Flash and a semaphore (concurrency of 2). Layer timeouts and retries on top of that, and you have the skeleton of a small production service. If you want to go further into architecture, our Gemini Agent Production System Guide walks through practical patterns in depth.

I've focused on the places I stumbled myself while building in the trenches of indie development. If it helps with even one of your design decisions, that would make me happy. Thank you for reading.

Thank You for Reading

Gemini Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.