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

​

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

• В тестировании было обнаружено три значения 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 — только в ответах без вывода изображений

• При успешной генерации уравнение строго выполняется (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+ — из-за нескольких image parts из процесса thinking

​

Уровни thinking и две API-парадигмы

​

Как thinkingLevel влияет на tokens

• high only increases thinking tokens and latency — image tokens stay unchanged (по-прежнему 1120 на одно изображение).
• Передача thinkingLevel в gemini-3-pro-image не вызывает ошибки, но не даёт измеримого эффекта — thinking tokens остаются в диапазоне по умолчанию.
• includeThoughts: true не изменило ни структуру ответа, ни тарификацию в ходе тестирования; Google прямо указывает, что thinking tokens тарифицируются по умолчанию, независимо от того, просматриваете ли вы процесс thinking.
• Google также отмечает, что «minimal thinking» не означает, что модель совсем не думает; при minimal usage просто перестаёт выводить отдельное поле thoughtsTokenCount.

​

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

• Text thinking models: выход thinking — текст; thoughtsTokenCount может достигать тысяч и тарифицируется по цене output-token. Официально тарификация основана на полных внутренних мыслях, которые генерирует модель, хотя API возвращает только краткие сводки мыслей (источник: раздел о тарификации в 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 in candidatesTokenCount. So for image models the «cost of thinking» mostly shows up in the number of image parts, not in the thoughtsTokenCount field (см. поведение 3 выше).

​

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

​

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