◈ API / SDK/2026-03-27中級

Gemini API を Go で実装する — 公式 genai SDK のテキスト生成・画像解析・ストリーミングと本番運用の設計

Google 公式 Go SDK（google.golang.org/genai）で Gemini API を実装。テキスト生成・画像解析・ストリーミングに加え、goroutine の並行制御・タイムアウト設計・モデル選定という本番運用の勘所までコード付きで解説します。

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

✦ プレミアム記事

Go を選んだ理由と、この記事で扱うこと

個人開発でAIバックエンドを回していると、レスポンスの速さと同じくらい「一台のサーバーでどれだけリクエストを捌けるか」が効いてきます。私自身、複数のアプリからGemini APIを叩く小さな中継サーバーを Go で書き直したところ、常駐メモリと起動時間の両方が目に見えて軽くなりました。goroutine による並行処理と、単一バイナリで完結する配布のしやすさ。この2点が、Go を選ぶ静かな決め手になっています。

扱うのは、Google 公式の Go SDK（google.golang.org/genai）を使った実装です。テキスト生成からマルチモーダル画像解析、ストリーミング、マルチターン会話まで手を動かし、そのうえで入門記事では省かれがちな並行リクエストのレート制御・タイムアウト設計・モデル選定という、本番で必ずぶつかる論点まで踏み込みます。

Go の基本文法を理解していれば、AI API の利用経験は問いません。全体像を先に押さえたい方は、Gemini API クイックスタートもあわせてご覧ください。

環境準備

前提条件

Gemini API を Go で利用するために必要なものは以下の3つです。

Go 1.23 以上 がインストール済みであること
Google AI Studio の API キー（aistudio.google.com で無料取得可能）
インターネット接続環境

プロジェクトの初期化と SDK インストール

まず新しい Go モジュールを作成し、公式 SDK をインストールします。

# プロジェクトディレクトリの作成
mkdir gemini-go-app && cd gemini-go-app
 
# Go モジュールの初期化
go mod init gemini-go-app
 
# Google Gen AI Go SDK のインストール
go get google.golang.org/genai

API キーの設定

API キーは環境変数 GEMINI_API_KEY として設定します。SDK がこの環境変数を自動的に読み取るため、コード内にキーを直接記述する必要はありません。

# 環境変数の設定（Linux / macOS）
export GEMINI_API_KEY="YOUR_API_KEY"

セキュリティのため、API キーをソースコードにハードコードしたり、Git リポジトリにコミットしたりしないよう注意してください。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦goroutine とセマフォで並行リクエストを安全に捌く実装パターン

✦context タイムアウトと実測レイテンシにもとづく本番向けの失敗設計

✦モデル別レイテンシ・コストの実測にもとづく選定の指針

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

テキスト生成の基本

最もシンプルな使い方として、Gemini にテキストプロンプトを送信してレスポンスを取得する例を見てみましょう。

package main
 
import (
	"context"
	"fmt"
	"log"
 
	"google.golang.org/genai"
)
 
func main() {
	ctx := context.Background()
 
	// クライアントの作成（GEMINI_API_KEY 環境変数を自動読み取り）
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
 
	// テキスト生成リクエスト
	result, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash", // 使用するモデル
		genai.Text("Goプログラミングの特徴を3つ簡潔に教えてください"),
		nil, // オプション設定（nilでデフォルト）
	)
	if err != nil {
		log.Fatal(err)
	}
 
	// レスポンスの出力
	fmt.Println(result.Text())
}
 
// 期待される出力例:
// 1. **高速なコンパイルと実行**: Goはコンパイル速度が非常に速く...
// 2. **ゴルーチンによる並行処理**: 軽量スレッドであるゴルーチンにより...
// 3. **シンプルな言語設計**: 余分な機能を排除したミニマルな文法で...

genai.NewClient に nil を渡すと、デフォルト設定（Google AI バックエンド + GEMINI_API_KEY 環境変数からのキー読み取り）でクライアントが作成されます。

生成パラメータのカスタマイズ

出力の創造性や長さを制御するには、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()
 
	// 生成パラメータの設定
	temperature := float32(0.3)
	maxTokens := int32(500)
 
	config := &genai.GenerateContentConfig{
		Temperature:     &temperature, // 低めで安定した出力
		MaxOutputTokens: maxTokens,    // 出力トークン数の上限
		SystemInstruction: &genai.Content{
			Parts: []*genai.Part{
				genai.NewPartFromText("あなたはGoプログラミングの専門家です。簡潔で実践的な回答をしてください。"),
			},
		},
	}
 
	result, err := client.Models.GenerateContent(ctx,
		"gemini-2.5-flash",
		genai.Text("Go の defer 文の使いどころを教えてください"),
		config,
	)
	if err != nil {
		log.Fatal(err)
	}
 
	fmt.Println(result.Text())
}

Temperature を 0 に近づけるほど決定論的な出力になり、1.0 に近づけるほど創造的な出力になります。API リファレンスやコード生成のような正確性が求められるタスクでは、0.1〜0.3 程度の低い値が適しています。

マルチモーダル入力 — 画像解析

Gemini の強力な特徴の一つが、テキストと画像を組み合わせたマルチモーダル入力です。ローカルの画像ファイルを読み込んで解析する例を示します。

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()
 
	// 画像ファイルの読み込み
	imageBytes, err := os.ReadFile("sample.jpg")
	if err != nil {
		log.Fatal("画像の読み込みに失敗:", err)
	}
 
	// マルチモーダルリクエストの構築
	parts := []*genai.Part{
		genai.NewPartFromBytes(imageBytes, "image/jpeg"),
		genai.NewPartFromText("この画像に写っているものを詳しく説明してください。"),
	}
 
	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())
}
 
// 期待される出力例:
// この画像には、青い空を背景に咲く桜の木が写っています。
// 淡いピンク色の花びらが満開で...

JPEG、PNG、WebP、GIF など主要な画像フォーマットに対応しています。genai.NewPartFromBytes の第2引数には適切な MIME タイプを指定してください。

ストリーミング応答

長い応答を生成する場合、すべての出力を待つのではなく、トークンが生成されるたびにリアルタイムで受け取ることができます。チャットアプリやCLIツールのユーザー体験を大幅に向上させるテクニックです。

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 := client.Models.GenerateContentStream(ctx,
		"gemini-2.5-flash",
		genai.Text("Goで簡単なHTTPサーバーを構築する手順をステップバイステップで説明してください"),
		nil,
	)
 
	// チャンクごとにリアルタイム出力
	for chunk, err := range stream {
		if err != nil {
			log.Fatal(err)
		}
		if chunk.Text() != "" {
			fmt.Print(chunk.Text())
		}
	}
	fmt.Println() // 最終行の改行
}

GenerateContentStream は Go 1.23 の range-over-func（イテレータ）パターンに対応しており、for ... range で簡潔に書くことができます。ストリーミングの詳しい実装パターンについては、ストリーミング応答とマルチターン会話の実装ガイドも参考になります。

マルチターン会話の実装

チャットボットのような対話型アプリケーションでは、会話の文脈を維持する必要があります。SDK の Chat 機能を使うと、会話履歴を自動的に管理できます。

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()
 
	// チャットセッションの開始
	config := &genai.GenerateContentConfig{
		SystemInstruction: &genai.Content{
			Parts: []*genai.Part{
				genai.NewPartFromText("あなたはフレンドリーなGoプログラミングの先生です。"),
			},
		},
	}
	chat, err := client.Chats.Create(ctx, "gemini-2.5-flash", config, nil)
	if err != nil {
		log.Fatal(err)
	}
 
	// 1往復目
	resp1, err := chat.SendMessage(ctx, genai.Text("Go の goroutine とは何ですか？"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("AI:", resp1.Text())
 
	// 2往復目（前の会話を踏まえた質問）
	resp2, err := chat.SendMessage(ctx, genai.Text("では、それとチャネルを組み合わせた簡単な例を見せてください"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("AI:", resp2.Text())
}

chat.SendMessage は内部的に過去の会話履歴を保持しており、2往復目の質問では「それ」が goroutine を指していることを Gemini が正しく理解します。

エラーハンドリングのベストプラクティス

本番環境では、レート制限やネットワークエラーに適切に対処する必要があります。以下は指数バックオフによるリトライを実装した例です。

package main
 
import (
	"context"
	"fmt"
	"log"
	"math"
	"time"
 
	"google.golang.org/genai"
)
 
// retryGenerateContent は指数バックオフ付きリトライでコンテンツを生成する
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
 
		// 指数バックオフ（1s, 2s, 4s...）
		wait := time.Duration(math.Pow(2, float64(i))) * time.Second
		log.Printf("リトライ %d/%d（%v後に再実行）: %v", i+1, maxRetries, wait, err)
		time.Sleep(wait)
	}
 
	return nil, fmt.Errorf("%d回のリトライ後も失敗: %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",
		"Go のエラーハンドリングのベストプラクティスを教えてください", 3)
	if err != nil {
		log.Fatal("最終的にリクエスト失敗:", err)
	}
 
	fmt.Println(result.Text())
}

Gemini API のエラーハンドリングについてさらに詳しく知りたい方は、Gemini API のエラーハンドリングとリトライ設計で網羅的に解説しています。

goroutine で並行リクエストを捌く — セマフォによるレート制御

Go の魅力は並行処理にありますが、Gemini API には毎分あたりのリクエスト数（RPM）の上限があります。何も考えずに goroutine を大量に起動すると、すぐに 429 RESOURCE_EXHAUSTED に阻まれます。ここで効くのが、バッファ付きチャネルを使った軽量なセマフォです。同時実行数を明示的に絞りながら、複数プロンプトをまとめて処理します。

package main
 
import (
	"context"
	"fmt"
	"log"
	"sync"
 
	"google.golang.org/genai"
)
 
// generateBatch は最大 concurrency 本の goroutine で並行生成する
func generateBatch(
	ctx context.Context,
	client *genai.Client,
	prompts []string,
	concurrency int,
) []string {
	results := make([]string, len(prompts))
	sem := make(chan struct{}, concurrency) // 同時実行数を絞るセマフォ
	var wg sync.WaitGroup
 
	for i, prompt := range prompts {
		wg.Add(1)
		go func(idx int, p string) {
			defer wg.Done()
			sem <- struct{}{}        // 空きが出るまでブロック
			defer func() { <-sem }() // 完了したら枠を返す
 
			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{
		"Go のスライスと配列の違いを一文で",
		"defer の実行順序を一文で",
		"チャネルの向き指定の意味を一文で",
	}
	for i, out := range generateBatch(ctx, client, prompts, 2) {
		fmt.Printf("[%d] %s\n", i, out)
	}
}

ポイントは concurrency を欲張らないことです。私自身、個人開発のバッチで欲張って 10 本走らせ、すぐにレート制限で足を掬われました。無料枠では 2〜4 程度から始め、レート制限のログを見ながら少しずつ上げるのが安全です。結果を results[idx] のように添字で書き込むことで、goroutine 間の共有状態にロックを持ち込まずに順序を保てます。処理そのものは並行、書き込み先は分離。この割り切りが、後々のデバッグのしやすさに直結します。

本番運用のためのタイムアウトとコンテキスト設計

context.Background() は入門では便利ですが、本番でそのまま使うと、ネットワークが詰まったときにリクエストが返らないリスクを抱えます。呼び出しごとに締め切りを設けるのが定石です。

// 呼び出し単位で締め切りを設ける
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 {
	// タイムアウトかどうかで分岐できる
	if errors.Is(err, context.DeadlineExceeded) {
		log.Println("生成がタイムアウトしました。プロンプト長やモデルを見直してください")
	}
	return err
}

運用で決めておきたい値を、実測を踏まえて整理すると次のようになります。

処理の種類	推奨タイムアウト	補足
短い分類・要約（Flash）	15〜30 秒	大半は数秒で返るが、混雑時の余裕を見る
長文生成・コード生成	45〜90 秒	MaxOutputTokens に比例して伸びる
ストリーミング	初回チャンク 10 秒＋全体上限	初回が遅ければ即中断が体験を守る

タイムアウトとリトライは組で考えます。1回の締め切りを短くしすぎるとリトライ回数が増えて総時間はかえって伸びるため、「1回の締め切り × 最大リトライ回数」が、ユーザーの待てる上限に収まるよう逆算するのが実践的です。

モデル選択とレイテンシ・コストの実測

「どのモデルを指定するか」は、体験とコストを同時に左右します。2026年時点では gemini-flash-latest が最新の安定 Flash を指すエイリアスとして使え、モデル更新に追従しやすくなっています。一方で、挙動を固定したい本番系ではバージョン固定名を使うのが安全です。

私が中継サーバーで同一プロンプト（約400トークン入力・300トークン出力）を各20回投げて測った、体感に近い傾向は次の通りです。数値は環境やネットワークで変動するため、選定の当たりをつける目安として捉えてください。

用途	体感レイテンシ	相対コスト	向いている場面
Flash 系	速い（1〜3 秒台）	低	分類・要約・チャット応答・大量バッチ
Pro 系	やや遅い（3〜8 秒台）	高	複雑な推論・長文設計・コード生成

実装上の指針はシンプルです。まず Flash で組み、品質が要件に届かない箇所だけ Pro に差し替える。最初から Pro を選ぶと、レイテンシもコストも過剰になりがちです。モデル名は設定ファイルや環境変数に逃がしておくと、gemini-2.5-flash と gemini-flash-latest の切り替えがコード変更なしで済み、運用中の比較検証がぐっと楽になります。

まとめ

公式 Go SDK を使えば、テキスト生成からマルチモーダル、ストリーミング、マルチターン会話までは驚くほど短いコードで書けます。そのうえで本番を見据えるなら、並行リクエストのセマフォ制御・呼び出し単位のタイムアウト・実測にもとづくモデル選定という3点が、体験とコストを守る土台になります。

次の一歩として、手元のプロンプトを1つ選び、まず Flash とセマフォ（同時実行 2）で動かしてみてください。そこにタイムアウトとリトライを重ねていけば、そのまま小さな本番サービスの骨格になります。より高度なアーキテクチャに踏み込みたい方は、Gemini エージェントシステム本番構築ガイドもあわせてご覧ください。

個人開発の現場で私自身がつまずいた箇所を中心にまとめました。実装の設計判断に少しでも役立てば嬉しいです。お読みいただきありがとうございました。