使用フィールドと出力の解説

​

レスポンス全体の構造

{
  "candidates":    [ ... ],          // generation results (image/text parts)
  "usageMetadata": { ... },          // token usage
  "modelVersion":  "gemini-3-pro-image",
  "responseId":    "..."
}

​

生成が成功した場合

"candidates": [{
  "content": {
    "role": "model",
    "parts": [
      { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
    ]
  },
  "finishReason": "STOP",
  "index": 0
}]

​

parts にはテキストセグメントも含まれる場合があります

​

安全ポリシーによりブロックされた場合

"candidates": [{
  "content": { "parts": null },        // ⚠️ parts is null, not an empty array
  "finishReason": "IMAGE_SAFETY",      // or NO_IMAGE / PROHIBITED_CONTENT
  "finishMessage": "Unable to show the generated image. ...",  // only present in some cases
  "index": 0
}]

• テストでは 3 つの finishReason 値が確認されました: IMAGE_SAFETY（出力画像がポリシーに違反している）、PROHIBITED_CONTENT（禁止用途ポリシーがトリガーされ、説明用の finishMessage が返される）、および NO_IMAGE（画像は生成されず、通常は数秒以内に返される）。
• 拒否の説明は finishMessage フィールドにあります — parts 内のテキスト part としては表示されません。
• パース処理では、parts が null である場合に対応する必要があります。そうしないと、ブロックされたレスポンスでクラッシュします。

​

usageMetadata フィールドの意味

"usageMetadata": {
  "promptTokenCount": 615,          // total input tokens (text + input images)
  "candidatesTokenCount": 2478,     // total output tokens (images + internal generation tokens)
  "thoughtsTokenCount": 208,        // thinking (reasoning) tokens
  "totalTokenCount": 3301,          // total billed amount for this request
  "promptTokensDetails":     [ { "modality": "TEXT",  "tokenCount": 99 },
                               { "modality": "IMAGE", "tokenCount": 516 } ],
  "candidatesTokensDetails": [ { "modality": "IMAGE", "tokenCount": 2240 } ]
}

​

異常に見える 3 つの挙動

​

挙動 1: candidatesTokenCount ≠ candidatesTokensDetails の合計 — 正常かつ不可避

​

挙動 2: totalTokenCount ≠ prompt + candidates + thoughts — 画像出力のないレスポンスでのみ発生

• 成功した生成では、この式は 厳密に成り立ちます（49/49）: total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount。
• 安全ブロックされたレスポンス（画像出力なし）では、この式は 決して成り立ちません（6/6）。固定パターンは次のとおりです:

candidatesTokenCount == thoughtsTokenCount     // thinking tokens are written into both fields
totalTokenCount == promptTokenCount + thoughtsTokenCount   // total counts them once — this is correct

​

挙動 3: output token がときどき 6000+ に達する — thinking プロセスの複数 image part が原因

​

Thinking Levels と 2つの API パラダイム

​

thinkingLevel が token に与える影響

• high は thinking token と Latency だけを増やし、image token は変わりません（image 1枚あたり引き続き 1120 です）。
• thinkingLevel を gemini-3-pro-image に渡してもエラーにはなりませんが、測定可能な効果はありません。thinking token はデフォルト範囲のままです。
• includeThoughts: true はテストでは response 構造も billing も変えませんでした。Google は、thinking process を表示するかどうかに関係なく、thinking token はデフォルトで課金対象になると明示しています。
• Google はまた、「minimal thinking は model がまったく thinking しないことを意味するわけではない」と述べています。minimal では、usage から separate な thoughtsTokenCount field が表示されなくなるだけです。

​

画像モデルの thinking token とテキストモデルの違い

• テキスト thinking モデル: thinking output は text で、thoughtsTokenCount は数千に達することがあり、output-token 価格で課金されます。公式には、pricing は model が生成する full internal thoughts に基づいており、API が返すのは thought の要約だけです（出典: ai.google.dev/gemini-api/docs/thinking の pricing セクション）。
• 画像 thinking モデル: thinking は 2 種類の output を生成します。1つは thoughtsTokenCount にカウントされる少量の text thinking（計測結果: Pro では最大 400、Flash では high で約 800）で、もう1つは interim draft images です。これらは通常の image part として返され、candidatesTokenCount に 1枚あたり 1120/2000 token で課金されます。したがって image model では、「thinking のコスト」は主に image part の数として現れ、thoughtsTokenCount field にはあまり現れません（上の Behavior 3 を参照）。

​

2つの API パラダイム

​

パースと照合のベストプラクティス

data = resp.json()
cand = (data.get("candidates") or [{}])[0]
parts = (cand.get("content") or {}).get("parts") or []   # handles parts=null

# Select by field shape — never by parts[0] / parts[1]; a text segment may come first
images = [p["inlineData"] for p in parts if "inlineData" in p]
if images:
    final_image = images[-1]["data"]          # last one is the final version
    mime = images[-1]["mimeType"]             # trust the response; don't hardcode image/png
else:
    reason = cand.get("finishReason")         # IMAGE_SAFETY / NO_IMAGE / PROHIBITED_CONTENT
    message = cand.get("finishMessage", "")   # may be empty

1. 課金をtotalTokenCountと照合してください（拒否の場合でも正確です）；3つのフィールドを自分で合計したり、詳細を合計したりして検証しないでください。
2. パーツを反復処理してください — 単一の画像だと決めつけないでください。画像ごとのビジネスロジックは、実際のinlineData パーツ数に基づいて行ってください。
3. parts = null + HTTP 200 でブロックされたレスポンスを処理し、finishReason に応じて分岐してください。
4. 簡単な編集には約22〜25秒かかります。複雑なタスク（複数画像のレスポンス）には35〜142秒かかり、画像が増えるほどさらに長くなります。クライアントのタイムアウトは、プロキシ層を含めて5分以上に設定してください。

​

関連ドキュメント