Пояснение полей 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
}]

​

Когда заблокировано политиками безопасности

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

• Было замечено три значения finishReason: IMAGE_SAFETY (выходное изображение нарушает политику), PROHIBITED_CONTENT (сработала политика запрещённого использования, с пояснительным finishMessage), и NO_IMAGE (изображение не сгенерировано, обычно возвращается в течение нескольких секунд).
• Пояснение об отказе находится в поле finishMessage — оно не появляется как текстовая часть внутри parts.
• Ваш код разбора должен обрабатывать то, что 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 } ]
}

​

Три поведения, похожие на аномалии

​

Поведение 1: candidatesTokenCount ≠ сумма candidatesTokensDetails — нормально и неизбежно

​

Поведение 2: totalTokenCount ≠ prompt + candidates + thoughts — только в ответах без image output

• При успешной генерации уравнение строго выполняется (49/49): total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount.
• В ответах, заблокированных системой безопасности (без image output), уравнение никогда не выполняется (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 и две API-парадигмы

​

Как thinkingLevel влияет на 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.

​

Чем thinking tokens image-моделей отличаются от текстовых моделей

• Текстовые thinking-модели: вывод thinking — это текст; 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-модели: 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).

​

Две 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 (это корректно даже при отказах); не проверяйте это, суммируя три поля вручную или суммируя детали.
2. Итерируйте по частям — никогда не предполагайте одно изображение; любая бизнес-логика на уровне изображения должна опираться на фактическое число частей inlineData.
3. Обрабатывайте заблокированные ответы с parts = null + HTTP 200, ветвясь по finishReason.
4. Простые правки занимают ~22–25 с; сложные задачи (ответы с несколькими изображениями) занимают 35–142 с, дольше при большем числе изображений. Установите тайм-ауты клиента на ≥ 5 минут (включая любой proxy-слой).

​

Связанные документы