> ## 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 и вывода > Поймите структуру response JSON и поля usageMetadata модели gemini-3-pro-image, включая три поведения подсчета, которые выглядят как аномалии, но являются неотъемлемой частью модели Эта страница предназначена для разработчиков, вызывающих `gemini-3-pro-image` (Nano Banana Pro) через APIYI. Она объясняет структуру выходного JSON-ответа и то, что на самом деле означает каждое поле `usageMetadata`, а также проясняет несколько особенностей подсчета, которые **выглядят как аномалии, но являются неотъемлемой частью модели**. Все выводы получены в ходе тестирования на production-шлюзе (48 запросов text-to-image + 18 запросов image-edit) и сверены с официальной документацией Google (`ai.google.dev/gemini-api/docs/image-generation`), а не основаны на предположениях. ## Общая структура ответа Серия APIYI Nano Banana использует нативный формат Google. В ответе всегда есть четыре поля верхнего уровня: ```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 }] ``` **части могут содержать более одного изображения.** При сложных запросах в стиле задач с несколькими ограничениями, например «4-view character sheet», модель может вернуть несколько частей изображения в одном ответе (в тестировании наблюдалось 2–10) — это промежуточные черновики из процесса «thinking» модели плюс финальная версия. В документации Google сказано, что «последнее изображение внутри Thinking — это также финальное отрендеренное изображение», поэтому **просто берите последнее**. Генерация изображений только по тексту и простые правки (добавить аксессуары / изменить фон / изменить стиль) обычно возвращают только 1. В любом случае всегда проходите по parts и берите последний `inlineData`, когда вам нужно только одно изображение. См. [Руководство для разработчиков · Почему ответы иногда содержат несколько изображений](/ru/api-capabilities/nano-banana-dev-guide#why-do-responses-occasionally-contain-multiple-images) для подробностей. ### Когда заблокировано политиками безопасности Код состояния 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 }] ``` * Было замечено три значения `finishReason`: `IMAGE_SAFETY` (выходное изображение нарушает политику), `PROHIBITED_CONTENT` (сработала политика запрещённого использования, с пояснительным `finishMessage`), и `NO_IMAGE` (изображение не сгенерировано, обычно возвращается в течение нескольких секунд). * Пояснение об отказе находится в поле `finishMessage` — оно не появляется как текстовая часть внутри `parts`. * Ваш код разбора должен обрабатывать то, что `parts` равно `null`, иначе заблокированные ответы вызовут сбой. Для диагностики сбоев, политик модерации контента и стратегий понятных пользователю сообщений см. [Руководство по обработке ошибок Gemini Image](/ru/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` | Общий итог | ✅ Всегда равно сумме предыдущих трех при успешной генерации; **исключение — отказы, см. Поведение 2 ниже** | | `promptTokensDetails` | Разбивка входа по модальности | ✅ Полная разбивка | | `candidatesTokensDetails` | Разбивка выхода по модальности | ⚠️ **Охватывает только часть изображения — не полная разбивка** | **Количество token для изображений определяется уровнем разрешения, а не соотношением сторон**: **1120 token на изображение** как на уровне 1K, так и на уровне 2K, **2000 на изображение** на уровне 4K. Соотношение сторон влияет только на размеры пикселей, но никогда — на количество token. Когда в одном ответе возвращается N изображений, детали в точности равны N × значению на одно изображение. Таблица ниже — это официальный справочник Google по соотношению сторон и размерам изображений для Pro Image (источник: `ai.google.dev/gemini-api/docs/image-generation`), полностью совпадающий с нашими измерениями `gemini-3-pro-image`: | Соотношение сторон | Размер 1K | token 1K | Размер 2K | token 2K | Размер 4K | token 4K | | ------------------ | --------- | -------- | --------- | -------- | --------- | -------- | | 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` означает «количество token для уровня разрешения 1K» — фактическое количество token на одно изображение равно значению в ячейке: 1120 token на изображение на уровнях 1K/2K, 2000 на уровне 4K. (В китайской локализации этой страницы заголовок отображается как «1,000 tokens», что легко принять за количество token на одно изображение.) Также обратите внимание: уровень 512px (747 token на изображение) существует только для моделей Flash для генерации изображений — `gemini-3-pro-image` поддерживает только 1K/2K/4K; Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`) — особый случай: у нее есть только уровень **1K**, без 512px. ## Три поведения, похожие на аномалии ### Поведение 1: candidatesTokenCount ≠ сумма candidatesTokensDetails — нормально и неизбежно В ходе тестирования **100%** выборок (49/49 успешных генераций) показали, что `candidatesTokenCount` превышает сумму деталей на **88–630 tokens** (чем сложнее prompt и чем больше изображений возвращается, тем больше разрыв). Причина: `candidatesTokensDetails` учитывает только **сам image payload** (фиксированные 1120/2000 на каждое изображение), тогда как `candidatesTokenCount` также включает внутренние tokens, сгенерированные в процессе image generation, для которых нет соответствующей записи по модальности. Это собственная схема подсчета Gemini; APIYI передает ее без изменений. **Итог: не рассматривайте details как полную разбивку `candidatesTokenCount` для проверки. Для сверки и тарификации всегда используйте `candidatesTokenCount` / `totalTokenCount`; details полезны только для оценки доли изображений.** ### Поведение 2: totalTokenCount ≠ prompt + candidates + thoughts — только в ответах без image output * При успешной генерации уравнение **строго выполняется** (49/49): `total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount`. * В ответах, заблокированных системой безопасности (без image output), уравнение **никогда не выполняется** (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`, поэтому при суммировании трех полей tokens, отвечающие за thinking, учитываются дважды. Это тоже поведение, присущее upstream. **`totalTokenCount` сам по себе точен — просто используйте его напрямую.** Если примерно 10% ответов в ваших логах «не сходятся», проверьте, есть ли в этих ответах пустой `parts` — это почти наверняка выборки, заблокированные системой безопасности. ### Поведение 3: output tokens иногда достигают 6000+ — причина в нескольких частях изображения из процесса thinking Официальная документация Google указывает, что модели Gemini 3 image являются thinking-моделями: режим «Thinking» включен по умолчанию и не может быть отключен в API. Модель генерирует промежуточные изображения для проверки композиции и логики, а «последнее изображение внутри Thinking также является финальным отрисованным изображением» (источник: раздел Thinking Process в `ai.google.dev/gemini-api/docs/image-generation`). В наших тестах эти промежуточные черновики thinking возвращаются в native `generateContent` response как **обычные части изображения**: каждая часть содержит поле `thoughtSignature`, но не имеет флага `thought: true`, и **каждая из них учитывается как 1120 tokens в `candidatesTokensDetails`**. В документации Google сказано, что Thinking генерирует не более двух промежуточных изображений, но в сложных task-подобных prompt мы наблюдали до **10 image parts** в одном ответе. Использование растет строго линейно с числом изображений: | Возвращено изображений | 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` учитывает только **text thinking** и в тестировании никогда не превышало 400 — источник высоких output tokens заключается в количестве image parts, а не в этом поле. Когда вы видите 6000+ или даже пятизначные output tokens, проверьте число частей в этом ответе — это почти наверняка multi-image ответ и нормальная тарификация (по-прежнему сверяйте с `totalTokenCount`). ## Уровни thinking и две 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` 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. Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`) is in the same 3.1 Flash family as Nano Banana 2 and also supports the `thinkingLevel` control, with the same mechanics as the table above; it hasn't been separately measured and included in the table yet. For pricing details, see [Тарификация серии Nano Banana](/ru/api-capabilities/nano-banana-pricing). ### Чем 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-парадигмы Документация Google по image-моделям теперь существует в двух вариантах: классический **generateContent API** (без состояния) и недавно рекомендованный **Interactions API** (созданный для agents и tools). Шлюз APIYI использует **нативный для Google формат generateContent — вся эта страница основана именно на нем**. Отличия, связанные с thinking: | | generateContent (эта страница) | Interactions API | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Thinking-level parameter | `generationConfig.thinkingConfig.thinkingLevel` | `generation_config.thinking_level` | | Thought content in response | `includeThoughts` переключатель (в тестах не давал видимого эффекта для image-моделей; промежуточные черновики всегда возвращаются как обычные image parts) | возвращается явно как `steps` (`type: "thought"`), без переключателя includeThoughts | | Usage field names | `thoughtsTokenCount` / `candidatesTokenCount` / `totalTokenCount` | `total_thought_tokens` / `total_output_tokens` | Полное сравнение двух парадигм (эндпоинты, управление состоянием, хранение данных и тесты совместимости шлюза APIYI) см. в [Interactions API vs generateContent](/ru/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`** (это корректно даже при отказах); не проверяйте это, суммируя три поля вручную или суммируя детали. 2. **Итерируйте по частям — никогда не предполагайте одно изображение**; любая бизнес-логика на уровне изображения должна опираться на фактическое число частей `inlineData`. 3. **Обрабатывайте заблокированные ответы с `parts = null` + HTTP 200**, ветвясь по `finishReason`. 4. Простые правки занимают \~22–25 с; сложные задачи (ответы с несколькими изображениями) занимают 35–142 с, дольше при большем числе изображений. Установите тайм-ауты клиента на ≥ 5 минут (включая любой proxy-слой). ## Связанные документы Методы интеграции, требования к входным изображениям, основы тарификации, настройки таймаута и пояснение по нескольким изображениям Три ключевых индикатора для диагностики неудачных генераций, политики модерации контента и дружественные стратегии prompt Для сбоев, не вызванных вашим вводом, кредиты возмещаются по числу неудачных запросов Цена за изображение в зависимости от разрешения и уровней модели