> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt > Use this file to discover all available pages before exploring further. # Usage フィールドと出力の解説 > gemini-3-pro-image のレスポンス JSON 構造と usageMetadata フィールドを理解し、異常のように見えるもののモデルに固有の 3 つのカウント挙動を把握します このページは、APIYI 経由で `gemini-3-pro-image` (Nano Banana Pro) を呼び出す開発者向けです。レスポンス JSON の出力構造と、各 `usageMetadata` フィールドが実際に何を意味するのかを説明し、**異常に見えるものの、モデルに本来備わっている**いくつかのカウント動作も明確にします。すべての結論は、本番ゲートウェイに対するテスト（テキストから画像への 48 件 + 画像編集の 18 件のリクエスト）と、Google の公式ドキュメント（`ai.google.dev/gemini-api/docs/image-generation`）との突き合わせに基づいており、推測ではありません。 ## 全体のレスポンス構造 APIYI の Nano Banana シリーズは Google のネイティブ形式を使用します。レスポンスには常に 4 つのトップレベルフィールドがあります。 ```json theme={null} { "candidates": [ ... ], // generation results (image/text parts) "usageMetadata": { ... }, // token usage "modelVersion": "gemini-3-pro-image", "responseId": "..." } ``` ### 生成に成功した場合 ```json theme={null} "candidates": [{ "content": { "role": "model", "parts": [ { "inlineData": { "mimeType": "image/jpeg", "data": "" } } ] }, "finishReason": "STOP", "index": 0 }] ``` **parts には複数の画像が含まれる場合があります。** 「4-view character sheet」のような複雑なタスク型プロンプト（複数制約のタスク）では、モデルは 1 回のレスポンスで複数の画像 part を返すことがあります（テストでは 2〜10 個確認されました）。これらはモデルの「thinking process」による途中ドラフトと最終版です。Google の docs では「Thinking 内の最後の画像が、最終的にレンダリングされる画像でもある」とされていますので、**最後のものだけを使ってください**。純粋な text-to-image や、アクセサリの追加 / 背景の変更 / スタイル変更のような簡単な編集では、通常 1 つだけ返されます。いずれの場合も、1 枚だけ必要なときは常に parts を順にたどって最後の `inlineData` を使ってください。詳細は [Dev Guide · Why Do Responses Occasionally Contain Multiple Images](/ja/api-capabilities/nano-banana-dev-guide#why-do-responses-occasionally-contain-multiple-images) をご覧ください。 ### safety policies によりブロックされた場合 HTTP ステータスコードは **依然として 200** です。違いは candidate の中にあります。 ```json theme={null} "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` である場合に対応しなければなりません。そうしないと、ブロックされたレスポンスでクラッシュします。 障害診断、コンテンツモデレーションポリシー、ユーザーフレンドリーなメッセージング戦略については、[Gemini Image Error Handling Guide](/ja/api-capabilities/gemini-image-error-handling) をご覧ください。 ## usageMetadata フィールドの意味 成功した生成には、常に 6 つのフィールドが含まれます: ```json theme={null} "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 } ] } ``` | フィールド | 意味 | 信頼性 | | ------------------------- | ------------------------ | ------------------------------------------------------------ | | `promptTokenCount` | 入力側合計 | ✅ 常に `promptTokensDetails` の合計と一致します | | `candidatesTokenCount` | 出力側合計 | ✅ 課金値です。**ただし、明細の合計より大きくなります — 下の動作 1 を参照してください** | | `thoughtsTokenCount` | 思考 tokens、テストでは通常 50〜350 | ✅ | | `totalTokenCount` | 総合計 | ✅ 成功した生成では常に直前の 3 つの合計と一致します。**拒否時は例外です — 下の動作 2 を参照してください** | | `promptTokensDetails` | モダリティ別入力内訳 | ✅ 完全な内訳 | | `candidatesTokensDetails` | モダリティ別出力内訳 | ⚠️ **画像部分のみを対象とし、完全な内訳ではありません** | **画像 tokens はアスペクト比ではなく、解像度ティアによって決まります**: 1K と 2K の両方のティアで **画像 1 枚あたり 1120 tokens**、4K では **1 枚あたり 2000 tokens** です。アスペクト比が変えるのはピクセル寸法だけで、token 数は変わりません。1 回のレスポンスで N 枚の画像が返る場合、明細はちょうど N × 画像 1 枚あたりの値になります。 下の表は、Google の公式 Pro 画像のアスペクト比と画像サイズの参照表です（出典: `ai.google.dev/gemini-api/docs/image-generation`）。`gemini-3-pro-image` の計測結果とも完全に一致しています: | アスペクト比 | 1K サイズ | 1K tokens | 2K サイズ | 2K tokens | 4K サイズ | 4K tokens | | ------ | --------- | --------- | --------- | --------- | --------- | --------- | | 1:1 | 1024x1024 | 1120 | 2048x2048 | 1120 | 4096x4096 | 2000 | | 2:3 | 848x1264 | 1120 | 1696x2528 | 1120 | 3392x5056 | 2000 | | 3:2 | 1264x848 | 1120 | 2528x1696 | 1120 | 5056x3392 | 2000 | | 3:4 | 896x1200 | 1120 | 1792x2400 | 1120 | 3584x4800 | 2000 | | 4:3 | 1200x896 | 1120 | 2400x1792 | 1120 | 4800x3584 | 2000 | | 4:5 | 928x1152 | 1120 | 1856x2304 | 1120 | 3712x4608 | 2000 | | 5:4 | 1152x928 | 1120 | 2304x1856 | 1120 | 4608x3712 | 2000 | | 9:16 | 768x1376 | 1120 | 1536x2752 | 1120 | 3072x5504 | 2000 | | 16:9 | 1376x768 | 1120 | 2752x1536 | 1120 | 5504x3072 | 2000 | | 21:9 | 1584x672 | 1120 | 3168x1344 | 1120 | 6336x2688 | 2000 | Google の公式表では、列見出し `1K tokens` は「1K 解像度ティアの token 数」を意味します。実際の画像 1 枚あたりの token 数はセルの値であり、1K/2K では 1 枚あたり 1120、4K では 2000 です。（そのページの中国語ローカライズでは、この見出しが「1,000 tokens」と表示されるため、画像 1 枚あたりの数と誤解しやすいです。）また、512px ティア（画像 1 枚あたり 747 tokens）は Flash 画像モデルでのみ存在し、`gemini-3-pro-image` は 1K/2K/4K のみをサポートします。Nano Banana 2 Lite（`gemini-3.1-flash-lite-image`）は特殊ケースで、**1K** ティアのみで 512px はありません。 ## 異常に見える 3 つの挙動 ### 挙動1: candidatesTokenCount ≠ candidatesTokensDetails の合計 — 正常かつ避けられない挙動 テストでは、サンプルの **100%**（49/49 の成功した生成）で `candidatesTokenCount` が詳細の合計を **88〜630 tokens** 上回っていました（プロンプトが複雑で、返却された画像が多いほど差は大きくなります）。 理由: `candidatesTokensDetails` は **画像ペイロードそのもの** だけを数えます（画像 1 枚あたり固定で 1120/2000）、一方で `candidatesTokenCount` には画像生成プロセスと並行して生成される内部 token も含まれますが、それに対応するモダリティ項目はありません。これは Gemini のネイティブなカウント方式であり、APIYI はそのまま透過しています。 **要するに、検証のために details を `candidatesTokenCount` の完全な内訳として扱わないでください。照合と課金には、必ず `candidatesTokenCount` / `totalTokenCount` を使ってください。details は画像分の割合を見積もる用途にしか役立ちません。** ### 挙動2: totalTokenCount ≠ prompt + candidates + thoughts — 画像出力のないレスポンスでのみ発生 * 生成が成功した場合、この式は **厳密に成り立ちます**（49/49）: `total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount`。 * 安全ブロックされたレスポンス（画像出力なし）では、この式は **一度も成り立ちません**（6/6）。固定パターンは次のとおりです: ```text theme={null} candidatesTokenCount == thoughtsTokenCount // thinking tokens are written into both fields totalTokenCount == promptTokenCount + thoughtsTokenCount // total counts them once — this is correct ``` 拒否レスポンスでは、`candidatesTokenCount` は `thoughtsTokenCount` を反映するため、3 つのフィールドを合計すると thinking token を二重計上してしまいます。これも upstream 固有の挙動です。**`totalTokenCount` 自体は正確です。直接そのまま使ってください。** ログ内のレスポンスの約 10% が「合計が合わない」場合は、該当レスポンスに空の `parts` があるか確認してください。ほぼ確実に安全ブロックされたサンプルです。 ### 挙動3: output tokens がときどき 6000+ に達する — thinking プロセス由来の複数画像パートが原因 Google の公式ドキュメントでは、Gemini 3 の画像モデルは thinking モデルだとされています。「Thinking」はデフォルトで有効で、API では無効化できません。モデルは構図とロジックを検証するために途中画像を生成し、「Thinking 内の最後の画像が最終的にレンダリングされる画像でもある」とされています（出典: `ai.google.dev/gemini-api/docs/image-generation` の Thinking Process セクション）。 私たちのテストでは、これらの途中 thinking 下書きはネイティブの `generateContent` レスポンス内で **通常の画像パート** として返ってきました。各パートには `thoughtSignature` フィールドはありますが、`thought: true` フラグはなく、**各パートは `candidatesTokensDetails` で 1120 tokens としてカウントされます**。Google のドキュメントでは thinking による途中画像は最大 2 枚とされていますが、複雑なタスク型プロンプトでは 1 回のレスポンスで最大 **10 個の画像パート** を確認しました。使用量は画像数に対して厳密に線形に増加します: | 返却された画像数 | candidatesTokensDetails | candidatesTokenCount | totalTokenCount | | --------------------- | ----------------------- | -------------------- | --------------- | | 1 (text-to-image, 1K) | 1120 | \~1210–1275 | \~1350–1450 | | 2 | 2240 | \~2500 | \~3300 | | 3 | 3360 | \~3800 | \~4600 | | 4 | 4480 | \~5000 | \~5900 | | 5 | 5600 | \~6200 | \~7000 | | 10 | 11200 | \~12700 | \~13500 | `thoughtsTokenCount` フィールドは **テキスト thinking** だけを数え、テストでは 400 を超えたことはありませんでした。高い output tokens の原因はこのフィールドではなく、画像パートの数です。6000+、あるいは 5 桁の output tokens を見かけたら、そのレスポンス内のパート数を確認してください。ほぼ確実にマルチ画像レスポンスで、課金は正常です（引き続き `totalTokenCount` で照合してください）。 ## Thinking レベルと 2 つの API パラダイム ### thinkingLevel が tokens に与える影響 thinking レベルの制御は、**Gemini 3.1 Flash Image / Flash Lite Image**（`generationConfig.thinkingConfig.thinkingLevel`、デフォルト `minimal`、または `high`）でのみサポートされています。`gemini-3-pro-image` では thinking は常にオンで、調整できません。測定結果（同じ prompt、1K text-to-image、APIYI ゲートウェイ経由）: | Model / setting | thoughtsTokenCount | Image tokens | totalTokenCount | Latency | | ------------------------------------------ | ------------------------------- | ------------ | --------------- | -------- | | gemini-3.1-flash-image · minimal (default) | field absent | 1120 | \~1534–1554 | \~12–13s | | gemini-3.1-flash-image · high | 700–792 | 1120 | \~2243–2375 | \~18–23s | | gemini-3-pro-image · high passed in | 181–214 (same as default range) | 1120 | \~1427–1471 | \~23s | * **`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 の表示がなくなるだけです。 Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`) は Nano Banana 2 と同じ 3.1 Flash ファミリーに属しており、`thinkingLevel` 制御も同じ仕組みでサポートします。まだ個別に測定されておらず、表にも含めていません。料金の詳細は [Nano Banana Series Pricing](/ja/api-capabilities/nano-banana-pricing) を参照してください。 ### 画像モデルの 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 パラダイム Google の画像モデル docs は現在 2 種類あります。従来の **generateContent API**（ステートレス）と、新たに推奨される **Interactions API**（エージェントと tools 向け）です。APIYI ゲートウェイは **Google ネイティブの generateContent 形式 — このページの内容はすべてこれを基にしています** を使用しています。thinking に関する違いは次のとおりです: | | generateContent (このページ) | Interactions API | | --------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | Thinking-level parameter | `generationConfig.thinkingConfig.thinkingLevel` | `generation_config.thinking_level` | | Thought content in response | `includeThoughts` スイッチ（テストでは画像モデルに可視的な効果はありませんでした。interim drafts は常に通常の image パーツとして返されます） | `steps`（`type: "thought"`）として明示的に返され、includeThoughts スイッチはありません | | Usage field names | `thoughtsTokenCount` / `candidatesTokenCount` / `totalTokenCount` | `total_thought_tokens` / `total_output_tokens` | 2 つのパラダイムの完全な比較（エンドポイント、状態管理、データ保持、APIYI ゲートウェイ互換性テスト）については、[Interactions API vs generateContent](/ja/api-capabilities/gemini/interactions-api) を参照してください。 ## パースと照合のベストプラクティス ```python theme={null} 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分以上に設定してください（プロキシ層がある場合も含みます）。 ## 関連ドキュメント 統合方法、入力画像要件、課金の基本、タイムアウト設定、複数画像の解説 生成失敗を診断するための3つの重要指標、コンテンツモデレーション方針、親しみやすい prompt 戦略 入力に起因しない失敗については、失敗したリクエスト数に応じてクレジットが返還されます 解像度とモデルティアごとの画像1枚あたりの料金