> ## 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.

# Нативная генерация изображений через инструмент

> Позвольте модели самостоятельно генерировать изображения через нативный инструмент image_generation в OpenAI Responses API — активируется gpt-5.5, возвращается в base64, с примечаниями по тарификации вызовов инструментов.

## Обзор

Помимо отдельных [text-to-image](/ru/api-capabilities/gpt-image-2/text-to-image) / [image-edit](/ru/api-capabilities/gpt-image-2/image-edit) эндпоинтов, APIYI также поддерживает **нативный tool OpenAI Responses API для `image_generation`**: основная модель `gpt-5.5` сама решает, когда рисовать, внутренне выбирает модель GPT Image и возвращает изображение как **base64** в массиве ответа `output`.

<Note>
  **Проверено и работает (2026-06-17)**: `gpt-5.5` + `POST /v1/responses` + `tools: [{"type": "image_generation"}]` возвращает корректный base64 PNG. Оба пути для изображений напрямую маршрутизируются через официальный upstream OpenAI.
</Note>

<Info>
  **Что выбрать?** Для подавляющего большинства случаев «я просто хочу изображение» лучше использовать отдельный [`/v1/images/generations`](/ru/api-capabilities/gpt-image-2/text-to-image) эндпоинт — тарификация идет только по фактическому использованию, поэтому это дешевле и лучше контролируется. **Используйте нативный метод tool на этой странице только тогда, когда ваш pipeline обязательно должен проходить через Responses** (например, если вы хотите, чтобы `gpt-5.5` автономно решала, рисовать ли изображение внутри Agent conversation). Он добавляет фиксированную плату за вызов tool примерно \$0.20 за изображение.
</Info>

## Сравнение двух методов

| Аспект                 | Нативный метод инструмента (эта страница)                                                                                                  | API изображений                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| **Канал**              | Прямой официальный релей OpenAI                                                                                                            | Прямой официальный релей OpenAI                                               |
| **Эндпоинт**           | `/v1/responses`                                                                                                                            | `/v1/images/generations`, `/v1/images/edits`                                  |
| **Инструмент**         | `image_generation`                                                                                                                         | Нет (передавайте prompt напрямую)                                             |
| **Тарификация**        | По использованию **+ плата за вызов инструмента**                                                                                          | По использованию                                                              |
| **Детали тарификации** | Ввод/вывод текста/изображений тарифицируется так же, как у официального релея; **фиксированная плата за вызов инструмента ≈ \$0.20/вызов** | Ввод/вывод текста/изображений тарифицируется так же, как у официального релея |
| **Лучше всего для**    | Сценариев, где требуются Responses (например, автономность агента)                                                                         | **Большинства сценариев с изображениями** — более разумная тарификация        |

> Ключевое отличие: **нативный метод инструмента добавляет фиксированную плату ≈\$0.20 за изображение**, тогда как API изображений тарифицируется только по фактическому использованию — поэтому в большинстве случаев он дешевле.

## Минимальный запрос

### cURL

```bash theme={null}
curl https://api.apiyi.com/v1/responses \
  -H "Authorization: Bearer $APIYI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Generate an image of a gray tabby cat hugging an otter with an orange scarf",
    "tools": [
      { "type": "image_generation" }
    ]
  }'
```

### Python (requests)

```python theme={null}
import base64, requests

resp = requests.post(
    "https://api.apiyi.com/v1/responses",
    headers={
        "Authorization": "Bearer $APIYI_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5.5",
        "input": "Generate an image of a gray tabby cat hugging an otter with an orange scarf",
        "tools": [{"type": "image_generation"}],
    },
    timeout=300,           # Generation is slow; allow plenty of timeout (~60-90s per image)
)
data = resp.json()

# Pull the image tool result out of the output array
for item in data["output"]:
    if item.get("type") == "image_generation_call":
        raw = base64.b64decode(item["result"])   # result field is a base64 image
        with open("output.png", "wb") as f:
            f.write(raw)
        print("Saved output.png,", len(raw), "bytes")
```

<Tip>
  Необязательные параметры помещаются в элемент `tools`: `{"type": "image_generation", "output_format": "png|jpeg|webp", "size": "1024x1024", ...}`. Не указывайте их, чтобы использовать значения по умолчанию (png).
</Tip>

## Структура ответа (ключевые поля)

При успехе (HTTP 200) тело ответа содержит:

```jsonc theme={null}
{
  "id": "resp_...",
  "model": "gpt-5.5-2026-04-23",
  "status": "completed",
  "output": [
    {
      "type": "image_generation_call",   // <- key: the tool actually fired
      "result": "<a very long base64 PNG string>"  // <- the image itself, base64, png by default
    },
    { "type": "message", "content": [ /* may be empty; image responses don't always include text */ ] }
  ],
  "usage": { "input_tokens": 2347, "output_tokens": 74 }
}
```

Как определить, действительно ли было создано изображение:

* ✅ **Успех**: `output` содержит `type="image_generation_call"`, а `result` декодируется в допустимое изображение, начинающееся с `\x89PNG`.
* ⚠️ **Без явного уведомления удалено**: HTTP 200, но в `output` нет `image_generation_call`, только текст (это часто бывает, когда канал не поддерживает инструмент).
* ❌ **Ошибка**: не-200 или возвращает `unknown tool` / `no available channels` и т. д. Для двух последних вариантов используйте `/v1/images/generations`.

## 💰 Тарификация

Возьмем один реальный вызов в качестве примера (входные 2347 tokens, выходные 74 tokens, генерация одного PNG 1122×1402). **Итоговая плата = \$0.213954** — это верно. Разбивка:

| Компонент                                   | Расчет квоты                                                                                 | USD                        |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------- |
| Текстовая часть                             | `(input 2347 + output 74×completion multiplier 6) × input multiplier 2.5` = **6977.5 квоты** | ≈ \$0.014                  |
| **Часть инструмента генерации изображений** | **≈ 100,000 квоты** (за изображение, независимо от tokens)                                   | **≈ \$0.20 / изображение** |
| **Итого**                                   | **106,977 квоты**                                                                            | **\$0.213954**             |

> Преобразование: `500,000 quota = \$1` (получено из `106977 quota = \$0.213954`).

<Warning>
  **Особенность отображения на странице деталей в консоли (заранее поясняйте это клиентам)**

  На странице APIYI «условная детализация тарификации»:

  * В верхнем разделе отображается только **текстовая часть** расчета (`base cost = (2347 + 74×6) × 2.5 = 6977.50`);
  * **Начисление за вызов инструмента генерации изображений (≈100,000 квоты / ≈\$0.20) показывается как пустая строка в списке деталей — оно не отрисовывается**;
  * но **оно корректно учитывается** в итоговой строке «итоговая квота 106977 / \$0.213954».

  **Вывод: тарификация нормальная и точная** — интерфейс детализации просто не показывает строку «image tool», поэтому позиции не сходятся с итоговой суммой. При объяснении клиентам делайте акцент: **итог верен; разница — это плата за tool этого изображения (≈\$0.20/изображение), просто она не выделена отдельно.**
</Warning>

### Примечания по стоимости

* Плата за генерацию **фиксирована за изображение** (≈\$0.20/изображение) и не зависит от длины prompt; стоимость tokens для текста на этом фоне невелика.
* На каждое изображение уходит \~60-90 с; задайте тайм-аут клиента не менее 300 с.
* Если вам нужно только изображение и не требуется, чтобы model принимала решение самостоятельно, отдельный [`/v1/images/generations`](/ru/api-capabilities/gpt-image-2/text-to-image) endpoint, вероятно, дешевле и лучше поддается контролю.

## Устранение неполадок

| Симптом                             | Вероятная причина                                          | Исправление                                                     |
| ----------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| 200, но нет `image_generation_call` | Текущий канал не поддерживает инструмент (молча удаляется) | Переключите ключ/канал или используйте `/v1/images/generations` |
| `no available channels`             | Под ключом нет подходящего канала в группе                 | Переключитесь на группу ключей с каналами GPT/image             |
| Тайм-аут запроса                    | Генерация идет медленно                                    | Установите тайм-аут клиента на 300 с                            |
| `result` не декодируется в PNG      | Формат вывода изменился / аномалия канала                  | Проверьте `output_format`, убедитесь в magic bytes              |

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

* [GPT-Image-2 Overview](/ru/api-capabilities/gpt-image-2/overview) - Обзор модели и тарификация
* [Text-to-Image API Reference](/ru/api-capabilities/gpt-image-2/text-to-image) - `/v1/images/generations`, выбор по умолчанию для большинства случаев
* [Image Edit API Reference](/ru/api-capabilities/gpt-image-2/image-edit) - `/v1/images/edits`, редактирование по опорному изображению / слияние нескольких изображений / маска