Usage フィールドと出力の解説

​

全体のレスポンス構造

{
  "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
}]

​

safety policies によりブロックされた場合

"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 tokens がときどき 6000+ に達する — thinking プロセス由来の複数画像パートが原因

​

Thinking レベルと 2 つの API パラダイム

​

thinkingLevel が tokens に与える影響

• high は thinking tokens とレイテンシを増やすだけで、画像 tokens は変わりません（画像 1 枚あたり 1120 のままです）。
• thinkingLevel を gemini-3-pro-image に渡してもエラーにはなりませんが、測定できる効果はありません — thinking tokens はデフォルト範囲のままです。
• includeThoughts: true はレスポンス構造も課金もテストでは変えませんでした。Google はまた、thinking プロセスを表示するかどうかにかかわらず、thinking tokens はデフォルトで課金されると明言しています。
• Google はまた、「minimal thinking は、モデルがまったく thinking しないという意味ではない」と述べています — minimal では usage から個別の thoughtsTokenCount field の表示がなくなるだけです。

​

画像モデルの thinking tokens はテキストモデルとどう異なるか

• Text thinking models: thinking の出力は text です。thoughtsTokenCount は数千に達することがあり、output-token 価格で課金されます。公式には、API が返すのは thought の要約だけでも、課金はモデルが生成する full internal thoughts に基づいています（出典: ai.google.dev/gemini-api/docs/thinking の課金セクション）。
• Image thinking models: thinking は 2 種類の出力を生成します — thoughtsTokenCount にカウントされる少量の text thinking（測定では、Pro で最大 400、Flash で約 800、high 時点）、および interim draft images です。後者は通常の image パーツとして返され、candidatesTokenCount に 1 枚あたり 1120/2000 tokens で課金されます。したがって image モデルでは、「thinking のコスト」は主に image パーツの数として現れ、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

images = [p["inlineData"]["data"] for p in parts if "inlineData" in p]
if images:
    final_image = images[-1]                  # last one is the final version
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分以上に設定してください（プロキシ層がある場合も含みます）。

​

関連ドキュメント