Usage Fields & Output Explained

​

Overall Response Structure

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

​

On successful generation

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

​

When blocked by 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
}]

• Three finishReason values were observed in testing: IMAGE_SAFETY (the output image violates policy), PROHIBITED_CONTENT (a prohibited-use policy was triggered, with an explanatory finishMessage), and NO_IMAGE (no image generated, usually returned within seconds).
• The refusal explanation lives in the finishMessage field — it does not appear as a text part inside parts.
• Your parsing code must handle parts being null, otherwise blocked responses will crash it.

​

usageMetadata Field Meanings

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

​

Three Behaviors That Look Like Anomalies

​

Behavior 1: candidatesTokenCount ≠ sum of candidatesTokensDetails — normal and inevitable

​

Behavior 2: totalTokenCount ≠ prompt + candidates + thoughts — only on responses with no image output

• On successful generation, the equation holds strictly (49/49): total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount.
• On safety-blocked responses (no image output), the equation never holds (6/6), with a fixed pattern:

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

​

Behavior 3: output tokens occasionally hit 6000+ — caused by multiple image parts from the thinking process

​

Thinking Levels & the Two API Paradigms

​

How thinkingLevel affects tokens

• high only increases thinking tokens and latency — image tokens stay unchanged (still 1120 per image).
• Passing thinkingLevel to gemini-3-pro-image does not error, but has no measurable effect — thinking tokens stay in the default range.
• includeThoughts: true changed neither the response structure nor billing in testing; Google states explicitly that thinking tokens are billed by default whether or not you view the thinking process.
• Google also notes that “minimal thinking does not mean the model does no thinking at all” — under minimal the usage simply stops listing a separate thoughtsTokenCount field.

​

How image-model thinking tokens differ from text models

• Text thinking models: the thinking output is text; thoughtsTokenCount can reach thousands and is billed at the output-token price. Officially, pricing is based on the full internal thoughts the model generates, even though the API only returns thought summaries (source: the pricing section of ai.google.dev/gemini-api/docs/thinking).
• Image thinking models: thinking produces two kinds of output — a small amount of text thinking counted in thoughtsTokenCount (measured: up to 400 on Pro, ~800 on Flash at high), and interim draft images, which come back as ordinary image parts billed at 1120/2000 tokens each into candidatesTokenCount. So for image models the “cost of thinking” mostly shows up in the number of image parts, not in the thoughtsTokenCount field (see Behavior 3 above).

​

The two API paradigms

​

Parsing & Reconciliation Best Practices

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. Reconcile billing with totalTokenCount (it is accurate even for refusals); do not validate by summing the three fields yourself or by summing details.
2. Iterate over parts — never assume a single image; any per-image business logic should go by the actual number of inlineData parts.
3. Handle blocked responses with parts = null + HTTP 200, branching on finishReason.
4. Simple edits take ~22–25s; complex tasks (multi-image responses) take 35–142s, longer with more images. Set client timeouts to ≥ 5 minutes (including any proxy layer).

​

Related Docs