「Gemini API を呼び出したら、なんか変な出力が返ってきた」
こういう経験は、API を使い始めた直後だけでなく、しばらく運用してから突然起きることもあります。エラーコードが出るわけではないので気づきにくく、「バグなのかAPI側の問題なのかコードの問題なのか」の切り分けに時間を取られがちです。
ここではGemini API の出力が期待と異なるときによくある7つのパターンを整理しました。それぞれに具体的な確認ポイントとコード例を載せているので、問題が起きたときの診断チェックリストとして使ってみてください。
① 出力が空、または途中で切れる
まず確認すべきは finish_reason です。Gemini API のレスポンスにはなぜ生成が止まったかを示す値が含まれており、これを見るだけで原因が分かることが多いです。
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
response = genai.GenerativeModel("gemini-2.5-pro").generate_content("テスト入力")
# finish_reason を確認する
for candidate in response.candidates:
print(f"finish_reason: {candidate.finish_reason}")
print(f"content: {candidate.content.parts[0].text if candidate.content.parts else '(空)'}")よくある finish_reason の値と意味：
STOP— 正常終了（これが正常）MAX_TOKENS—max_output_tokensの上限に達して途中終了SAFETY— セーフティフィルタによるブロック（後述）RECITATION— 著作権コンテンツの可能性で停止OTHER— その他の理由
MAX_TOKENS が返ってきているなら、generation_config に max_output_tokens を追加するか、値を大きくしてください。デフォルトは比較的小さく設定されていることがあります。長い文章を生成したい場合は明示的に指定することをおすすめします。
② 日本語で入力したのに英語で返ってくる
これはよくある問題で、Gemini API はデフォルトで入力言語に合わせて応答しようとしますが、System Instruction の言語設定や、プロンプトの構造によって英語応答に引っ張られることがあります。
解決策として最も確実なのは、System Instruction に明示的に言語を指定することです。
model = genai.GenerativeModel(
model_name="gemini-2.5-pro",
system_instruction="あなたは日本語で回答するアシスタントです。ユーザーからの質問には必ず日本語で答えてください。英語での回答は絶対にしないでください。"
)
response = model.generate_content("What is machine learning?")
print(response.text) # 日本語で返ってくるはず英語のキーワードが多い技術的なプロンプトほど、この問題が起きやすいです。英語で質問しても日本語で答えてほしい場合は、System Instruction での明示指定が現時点では最も安定した方法です。
③ JSON フォーマットが崩れる・スキーマ通りに返ってこない
「JSON 形式で返して」とプロンプトに書いてもうまくいかない場合は、Structured Output（response_mime_type と response_schema）を使うのが確実です。
import typing_extensions as typing
import json
class ArticleSummary(typing.TypedDict):
title: str
summary: str
tags: list[str]
model = genai.GenerativeModel("gemini-2.5-pro")
result = model.generate_content(
"以下の記事を要約してください：[記事本文をここに入れる]",
generation_config=genai.GenerationConfig(
response_mime_type="application/json",
response_schema=ArticleSummary,
),
)
# コードブロックなしの純粋な JSON が返ってくる
data = json.loads(result.text)
print(data["title"])
print(data["tags"]) # list[str] として取得できるプロンプトで「JSON で返して」と指示するだけでは、Gemini が Markdown のコードブロックで囲んで返すことがあり、そのままパースするとエラーになります。response_mime_type="application/json" を指定すれば、コードブロックなしの純粋な JSON が返ってきます。
④ 毎回全く違う出力になる
再現性が必要な処理（分類タスク・構造化データ抽出・テスト）で毎回違う結果が来る場合は、temperature を下げてください。
response = model.generate_content(
"この文章のセンチメントを positive / negative / neutral のいずれかで答えてください。",
generation_config=genai.GenerationConfig(
temperature=0.0, # 決定論的な出力に近づける
),
)
print(response.text)temperature=0.0 にしても完全に同一の出力が保証されるわけではありませんが、実用上は十分安定します。翻訳や要約など創造性が不要なタスクでは 0.0〜0.3 を推奨します。逆に、アイデア出しや創作系タスクには 0.7〜1.0 が向いています。
⑤ Thinking の内容が本文に混入している
Gemini 2.5 以降のモデルでは「Thinking」機能が利用でき、思考プロセスを内部で実行してから応答します。設定によっては、この思考内容が最終出力に見えることがあります。
Thinking は別フィールド（thought）に格納されているので、本文だけ取得したい場合は明示的に分離する必要があります。
response = model.generate_content(
"2の10乗はいくつですか？",
generation_config=genai.GenerationConfig(
thinking_config={"thinking_budget": 1024} # 思考トークン上限を設定
)
)
for part in response.candidates[0].content.parts:
if hasattr(part, "thought") and part.thought:
# 思考プロセスは別途ログに記録
print(f"[思考] {part.text[:80]}...")
else:
# ユーザーに見せる最終回答はこちら
print(f"[回答] {part.text}")Thinking を完全に無効化したい場合（コスト削減・レイテンシ改善）は thinking_budget=0 を指定してください。ただし、複雑な推論タスクでは回答品質が下がる場合があります。用途に合わせて調整するのがおすすめです。
⑥ セーフティフィルタで応答がブロックされる
finish_reason が SAFETY の場合、Gemini のハームカテゴリフィルタに引っかかっています。どのカテゴリが問題なのかを確認するには safety_ratings を参照してください。
response = model.generate_content("対象テキスト")
candidate = response.candidates[0]
if candidate.finish_reason.name == "SAFETY":
print("セーフティブロックされました")
for rating in candidate.safety_ratings:
if rating.probability.name != "NEGLIGIBLE":
print(f" {rating.category.name}: {rating.probability.name}")フィルタを緩めずに解決する方法として、System Instruction でコンテキストを明示する方法があります。たとえば「医療専門家向けシステム」「セキュリティ研究者向けツール」など、用途を具体的に書くと通過しやすくなる場合があります。safety_settings での閾値変更は、APIの利用規約をよく確認した上で慎重に判断してください。
⑦ 以前と比べて品質が下がったように感じる
モデルIDに latest や flash-latest のような動的エイリアスを使っている場合、Google がモデルを更新したタイミングで挙動が変わることがあります。
# リスクがある例：バージョンが固定されないエイリアス
model = genai.GenerativeModel("gemini-2.5-pro-latest")
# 本番推奨：特定バージョンを明示指定
model = genai.GenerativeModel("gemini-2.5-pro-preview-05-06")本番環境では具体的なバージョン文字列を使い、意図しないモデル更新を防ぐのが安全です。利用可能なモデルIDの一覧は Google AI Studio のモデルセレクターか、genai.list_models() で確認できます。
「出力がおかしい」という感覚は、具体的なエラーコードが出るケースより対処が難しいことがあります。まずは finish_reason を確認すること——これだけで大半の原因は絞り込めます。
今日すぐ試せることを1つ挙げるなら、既存コードに finish_reason のログ出力を追加することです。問題が起きたときの状況が残っていると、次回の診断がはるかに速くなります。
Gemini API の応答制御についてさらに詳しく知りたい方は、Gemini API レート制限エラーの原因と対処法やGemini API 構造化出力の本番実装ガイドもあわせてご覧ください。