◈ 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²⁸⁴gogolangsdk³ 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

✦Separating retryable errors from hopeless ones, with full-jitter backoff

✦A streaming timeout design that measures the first chunk on its own

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.

Which Errors Deserve a Retry — and Which Never Will

The retry helper above still carries two flaws that bite in production. It retries every error indiscriminately, and every request waits exactly the same amount of time.

When a malformed request is coming back as 400 INVALID_ARGUMENT, throwing it three more times changes nothing. Worse, you wait one second, then two, then four, only to receive the same error — and your diagnosis is delayed by exactly that much. In one of my own batch jobs, a wrong MIME type kept producing 400s that the helper dutifully retried until the log was wallpapered with the same stack trace. Classifying the error would have surfaced it on the very first attempt.

Start by separating errors worth retrying from errors that will never change.

Status	Meaning	Retry?	What to do instead
400 INVALID_ARGUMENT	The request itself is malformed	No	Check Part MIME types and input token length
403 PERMISSION_DENIED	Key lacks permission or is invalid	No	Verify the key and which APIs are enabled
404 NOT_FOUND	Wrong or retired model name	No	Revisit the model name in your config
429 RESOURCE_EXHAUSTED	Rate limit reached	Yes	Lower concurrency and wait longer
500 / 503	Transient server-side trouble	Yes	Back off, then try again

In Go you pull the status code out of genai.APIError. While you're there, mix randomness into the wait — full jitter.

package main
 
import (
	"context"
	"errors"
	"fmt"
	"log"
	"math/rand"
	"time"
 
	"google.golang.org/genai"
)
 
// isRetryable decides whether an error is worth another attempt
func isRetryable(err error) bool {
	var apiErr genai.APIError
	if errors.As(err, &apiErr) {
		switch apiErr.Code {
		case 429, 500, 502, 503, 504:
			return true
		default:
			return false // 400 / 403 / 404 will return the same thing forever
		}
	}
	// A deadline or cancellation from the caller is not worth retrying
	if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
		return false
	}
	return true // an unclassified transport error is worth one gamble
}
 
// backoffWithJitter picks a wait using the full jitter strategy
func backoffWithJitter(attempt int) time.Duration {
	base := time.Duration(1<<attempt) * time.Second // 1s, 2s, 4s...
	if base > 30*time.Second {
		base = 30 * time.Second
	}
	return time.Duration(rand.Int63n(int64(base))) // uniform in [0, base)
}
 
func generateWithPolicy(ctx context.Context, client *genai.Client,
	model, prompt string, maxRetries int) (*genai.GenerateContentResponse, error) {
 
	var lastErr error
	for attempt := 0; attempt < maxRetries; attempt++ {
		resp, err := client.Models.GenerateContent(ctx, model, genai.Text(prompt), nil)
		if err == nil {
			return resp, nil
		}
		lastErr = err
 
		if !isRetryable(err) {
			return nil, fmt.Errorf("retrying will not fix this: %w", err)
		}
 
		wait := backoffWithJitter(attempt)
		log.Printf("Retry %d/%d (waiting %v): %v", attempt+1, maxRetries, wait, err)
 
		select {
		case <-time.After(wait):
		case <-ctx.Done(): // step down immediately if the deadline arrives mid-wait
			return nil, ctx.Err()
		}
	}
	return nil, fmt.Errorf("failed after %d attempts: %w", maxRetries, lastErr)
}

Two things changed from the earlier version.

First, time.Sleep became a select. Sleep never looks at context cancellation, so even with a 30-second deadline in place, a backoff nap will happily stroll past it. If you want the deadline honored, the waiting side has to watch ctx.Done() too.

Second, the randomness. When four concurrent workers take a 429 at the same instant, fixed backoff sends all four back at the same instant, and they get turned away again. In my batch this collision repeated two or three times, inflating the retry count and nothing else. Adding full jitter spread the return times, and with the same input and the same concurrency the second wave of 429s stopped appearing — with a shorter average wait, not a longer one.

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.

Keep One Client per Process

One more thing matters to perceived speed almost as much as deadlines: how long your client lives. My first version called genai.NewClient on every request, and responses felt oddly heavy for weeks before I looked into it. The client holds HTTP connections internally, so rebuilding it each time puts the cost of re-establishing those connections straight into your response time.

type GeminiService struct {
	client *genai.Client
	model  string
}
 
func NewGeminiService(ctx context.Context, model string) (*GeminiService, error) {
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		return nil, err
	}
	return &GeminiService{client: client, model: model}, nil
}
 
// Close is called exactly once, when the process shuts down
func (s *GeminiService) Close() { s.client.Close() }

It is tempting to write defer client.Close() inside each handler, but on a shared client that tears the connections out from under every other in-flight request. Decide once that closing happens only at process shutdown, and stick to it.

Time the First Chunk Separately from the Rest

The table above suggests "10 s to first chunk plus an overall cap" for a reason: an overall timeout alone cannot protect the experience. Cap the whole stream at 90 seconds and a user can still sit for 90 seconds without a single character arriving. From their side that isn't a slow response — it's no response.

The fix is small. Add one watchdog that stands down the moment the first chunk lands.

// streamWithFirstChunkDeadline watches first-chunk latency apart from the overall cap
func streamWithFirstChunkDeadline(
	ctx context.Context,
	client *genai.Client,
	model, prompt string,
	firstChunk, total time.Duration,
	out func(string),
) error {
	ctx, cancel := context.WithTimeout(ctx, total)
	defer cancel()
 
	// Collapse the context if the first chunk never shows up
	watchdog := time.AfterFunc(firstChunk, cancel)
 
	first := true
	for chunk, err := range client.Models.GenerateContentStream(
		ctx, model, genai.Text(prompt), nil) {
		if err != nil {
			if first && ctx.Err() != nil {
				return fmt.Errorf("no first chunk within %v", firstChunk)
			}
			return err
		}
		if first {
			watchdog.Stop() // once tokens flow, only the overall cap applies
			first = false
		}
		if t := chunk.Text(); t != "" {
			out(t)
		}
	}
	return nil
}

The trick is handing cancel itself to time.AfterFunc. If the first chunk misses its window the context collapses and the iterator ends; if it arrives in time, Stop() releases the watchdog and only the overall cap remains. One flag and one timer — no extra goroutine just to supervise.

On the calling side, treat that first-chunk timeout as a signal to switch rather than a failure. In my own CLI tool, anything past eight seconds means giving up on Pro and reissuing against Flash. Being able to set the ceiling on waiting from the experience side rather than the model's side is, to me, the real payoff of measuring the first chunk on its own.

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, four things form the foundation that protects both experience and cost: separating retryable errors from hopeless ones, spreading waits with full jitter, throttling concurrency with a semaphore, and timing the first streamed chunk apart from the rest.

As a next step, pick one prompt from your own project and run it with Flash and a semaphore (concurrency of 2). Layer the isRetryable classification and jittered backoff 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.