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

# Есть ли conversational API, который выводит и текст, и сгенерированные изображения?

> Чтение изображений и генерация изображений — это две разные вещи: какие модели принимают изображение на вход, какие модели действительно могут выдавать изображения, какая семейство по-настоящему возвращает текст и изображение в одном ответе и как выбрать между четырьмя маршрутами для изображений.

## Краткий ответ

<Info>
  **Три предложения:**

  1. **«Can see images» и «can make images» — это две разные возможности.** Почти каждая современная chat-модель умеет **читать** изображения (именно это обычно и означает «multimodal»), но она не может **генерировать** изображения — это отдельный класс специализированных image-моделей.
  2. **Только семейство Gemini для изображений по-настоящему возвращает текст и изображение из одного endpoint** — `gemini-3-pro-image` (Nano Banana Pro), `gemini-3.1-flash-image` (Nano Banana 2) и другие модели чередуют текстовые и image-части в одном ответе.
  3. **Всё остальное — это orchestration**: chat-модель плюс отдельный image endpoint работают вместе, либо `gpt-5.5` с нативным инструментом Responses `image_generation`, чтобы модель сама решала, когда рисовать.
</Info>

## Сначала отделите входящие изображения от исходящих

Большая часть путаницы связана со словом «multimodal» — в контексте API по умолчанию оно относится к стороне входных данных,
то есть «вы можете подать модели изображение», а не «модель может создать изображение для вас».
Эти два сценария используют разные пулы моделей, разные эндпоинты и разную тарификацию:

| Параметр                  | Вход изображения (vision)                                                                                   | Выход изображения (generation)                                                                                              |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Какие модели              | **Почти каждая современная chat-модель** — семейства GPT-5, Claude, текстовые модели Gemini, семейство Grok | **Небольшой набор специализированных моделей для изображений** — около 30 из почти 300 моделей на платформе                 |
| Типичный эндпоинт         | `POST /v1/chat/completions`, `/v1/responses`, `/v1/messages`                                                | `POST /v1/images/generations`, `POST /v1/images/edits`                                                                      |
| Где находится изображение | В **запросе**: запись `image_url` или base64 в массиве `content`                                            | В **ответе**: `data[0].url` / `data[0].b64_json`, или `parts[].inlineData` для Gemini                                       |
| Тарификация               | Изображения преобразуются в tokens и тарифицируются по ставкам chat                                         | Тарифицируется за изображение, или по выходным tokens                                                                       |
| Как проверить             | На странице с подробностями модели указано «image» в разделе **Входные модальности**                        | Не в системе страницы с подробностями — см. [Модели генерации изображений и видео](/ru/api-capabilities/image-video-models) |

<Note>
  Так что если кто-то спрашивает: «у вас есть multimodal chat API»: если ему нужно **загрузить изображение, чтобы модель его проанализировала**,
  ответ — «это поддерживают почти все». Если же он хочет, чтобы модель **нарисовала изображение**, это совершенно
  другой набор моделей. Один такой уточняющий вопрос экономит большую часть последующего разговора.
</Note>

## Четыре способа получить изображение

| Маршрут                                                | Как вы вызываете                                    | Текст в том же ответе?                             | Лучше всего подходит для                                       |
| ------------------------------------------------------ | --------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
| **A. Отдельный image-эндпоинт** (рекомендуется)        | Модель image + `POST /v1/images/generations`        | ❌ Только изображение                               | «Мне просто нужно изображение»                                 |
| **B. Нативное семейство изображений Gemini**           | `POST /v1beta/models/{model}:generateContent`       | ✅ **Возможно**, но не гарантируется                | Вам нужны комментарии и изображение вместе                     |
| **C. Нативный инструмент Responses image\_generation** | `gpt-5.5` + `tools: [{"type": "image_generation"}]` | ✅ Да                                               | Агент, который сам решает, рисовать ли                         |
| **D. Chat endpoint на image-модели**                   | `gpt-image-2-all` / `-vip` + `/v1/chat/completions` | Изображение встроено как Markdown внутри `content` | Совместимость со старым вариантом, **больше не рекомендуется** |

<AccordionGroup>
  <Accordion title="A. Отдельный image-эндпоинт — выбирайте это почти для всего">
    Самый стандартный, дешевый и простой для отладки вариант. GPT-Image, FLUX, Seedream и Grok Imagine находятся здесь.

    ```bash theme={null}
    curl https://api.apiyi.com/v1/images/generations \
      -H "Authorization: Bearer sk-your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-image-2",
        "prompt": "An orange cat sitting on a blue sofa, simple line-art style",
        "size": "1024x1024"
      }'
    ```

    FLUX и Seedream обычно возвращают `data[0].url`; семейство GPT-Image возвращает `data[0].b64_json`.
    **Этот маршрут вообще не возвращает разговорный текст** — это не chat endpoint.

    Полная таблица моделей: [Модели для генерации изображений и видео](/ru/api-capabilities/image-video-models).
    Различия в endpoint, timeout и формате вывода для каждой модели:
    [Примечания и лучшие практики для Image API](/ru/api-capabilities/image-api-best-practices).
  </Accordion>

  <Accordion title="B. Нативное семейство изображений Gemini — единственное, которое по-настоящему возвращает текст и изображение вместе">
    Серия Nano Banana (`gemini-3-pro-image`, `gemini-3.1-flash-image` и так далее) использует нативный Gemini-эндпоинт,
    а `candidates[0].content.parts` — это **гетерогенный массив**: он может содержать только часть изображения, а может
    чередовать текстовые части с частями изображения. Это та семья, которая действительно дает вам и то, и другое в одном вызове.

    Один важный нюанс, который стоит знать заранее: **ни количество частей, ни их порядок не гарантируются.** В тестировании было
    обнаружено три варианта:

    | структура частей      | Длина | Индекс изображения |
    | --------------------- | ----- | ------------------ |
    | `inlineData`          | 1     | `0`                |
    | `text` + `inlineData` | 2     | **`1`**            |
    | `inlineData` + `text` | 2     | **`0`**            |

    Поэтому жесткое задание `parts[0]` или `parts[1]` **будет периодически давать сбой**. Правильный подход — фильтровать по наличию поля
    и брать **последний** `inlineData` (для сложных prompt модель возвращает несколько изображений, и последнее
    — финальная версия):

    ```python theme={null}
    cand = (resp.get("candidates") or [{}])[0]
    parts = (cand.get("content") or {}).get("parts") or []
    images = [p["inlineData"] for p in parts if "inlineData" in p]
    texts  = [p["text"] for p in parts if "text" in p]          # commentary lives here
    if not images:
        raise RuntimeError(f"No image returned, finishReason={cand.get('finishReason')}")
    final = images[-1]                                          # last image is the final one
    ```

    Полные подробности: [Руководство разработчика серии Nano Banana](/ru/api-capabilities/nano-banana-dev-guide).
  </Accordion>

  <Accordion title="C. Нативный инструмент image_generation в Responses — позвольте агенту самому решить, рисовать ли">
    Вызовите `POST /v1/responses` с `gpt-5.5` и подключите нативный инструмент для генерации изображений:

    ```json theme={null}
    {
      "model": "gpt-5.5",
      "input": "Draw a key visual poster for a product launch event",
      "tools": [{ "type": "image_generation" }]
    }
    ```

    Модель сама решает, рисовать ли, а изображение возвращается в base64 внутри элемента
    `image_generation_call` в массиве ответа `output`, вместе с обычным текстовым выводом.
    **Это ближе всего к «чат-модели, которая рисует» на стороне OpenAI.**

    <Warning>
      **Стоимость:** этот маршрут добавляет фиксированную плату примерно \$0.20 за изображение за вызов инструмента, поверх
      тарификации по использованию, тогда как у маршрута A `/v1/images/generations` тарификация только по использованию. Используйте его только когда ваш
      pipeline должен проходить через Responses (например, агент, который автономно принимает решения рисовать / не рисовать).
      Если вам нужно просто изображение, используйте маршрут A.
    </Warning>

    См. [Генерация изображений с помощью нативного инструмента](/ru/api-capabilities/gpt-image-2/responses-image-tool).
  </Accordion>

  <Accordion title="D. Chat endpoint на image-модели — выглядит как диалоговый, но все еще image-модель">
    `gpt-image-2-all` и `gpt-image-2-vip` можно вызывать через `/v1/chat/completions`, при этом изображение встраивается
    как Markdown-ссылка внутри `choices[0].message.content`.

    Это выглядит как «один chat endpoint, который и разговаривает, и рисует», но **это не chat model, которая умеет рисовать** —
    по сути это все еще image-модель, обернутая в chat-схему, без общей способности к диалогу.
    Она также **читает только `image_url` в последнем сообщении `user`** как базовое изображение; изображения в истории assistant
    игнорируются.

    Этот маршрут **больше не рекомендуется** — для новых интеграций следует использовать маршрут A.
  </Accordion>
</AccordionGroup>

## Создание продукта «chat and draw»: рекомендуемая схема

Что большинству агентов и продуктов на самом деле нужно, — это не один волшебный эндпоинт, а четкая цепочка оркестрации:

<Steps>
  <Step title="Пусть chat-модель определяет намерение">
    Используйте chat-модель, которую вы уже используете (`gpt-5.5`, `claude-opus-5`, `gemini-3-pro` и так далее), чтобы обработать ввод пользователя
    и определить, является ли этот ход диалогом или запросом на генерацию изображений. При необходимости можно вернуть
    структурированный флаг.
  </Step>

  <Step title="Пусть chat-модель сформирует prompt для генерации изображений">
    Этот шаг окупается сам по себе. Пользователь говорит «Сделай мне постер»; модели генерации изображений
    нужно полное визуальное описание. Если chat-модель перепишет неформальный запрос в хорошо сформированный prompt, качество
    результата становится заметно более стабильным.
  </Step>

  <Step title="Вызовите эндпоинт для генерации изображений">
    Используйте `/v1/images/generations` маршрута A. Возьмите возвращенный `url` или `b64_json` и сохраните его в вашем
    собственном object storage.
  </Step>

  <Step title="Верните изображение обратно в диалог">
    Добавьте ссылку на изображение как сообщение ассистента в историю диалога. Для пользователя это выглядит как
    «чат и рисование в одном потоке».
  </Step>
</Steps>

<Tip>
  Практические преимущества такого разделения: каждую модель можно заменять независимо (изменение модели для изображений
  не затрагивает вашу логику диалога), тарификация четко разделена в ваших логах, и
  **любой из этапов можно повторить отдельно** вместо повторного выполнения всего хода.
</Tip>

## Как проверить, принимает ли модель изображения

<Steps>
  <Step title="1. Проверьте страницу с подробностями модели">
    Откройте `/models/<model-name>` и посмотрите на строку **Модальности ввода** в таблице характеристик вверху — если
    там указано «image», модель поддерживает работу с изображениями. Это самый быстрый способ проверки.
  </Step>

  <Step title="2. Если сомневаетесь, протестируйте">
    Отправьте минимальный запрос с изображением и посмотрите на ответ:

    ```bash theme={null}
    curl https://api.apiyi.com/v1/chat/completions \
      -H "Authorization: Bearer sk-your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "the-model-you-are-testing",
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "What is in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/test.jpg"}}
          ]
        }]
      }'
    ```
  </Step>

  <Step title="3. Распознайте строку ошибки">
    Текстовые модели явно возвращают ошибку. Исходное сообщение выглядит так: `Model do not support image input`
    (грамматика у них такая, это не опечатка). Когда вы видите эту строку, модель не принимает изображения — переключитесь на другую модель.
  </Step>
</Steps>

<Warning>
  **Известные исключения, работающие только с текстом (по состоянию на 2026-08-20):** `deepseek-v4-pro`, `deepseek-v4-flash`, `glm-5.2`.

  Это меньшинство среди «современных моделей, которые всё ещё не принимают входные изображения», и они часто подводят пользователей.
  **Этот список меняется по мере изменения каталога моделей** — возможности также различаются между поколениями одного и того же
  поставщика. Всегда считайте строку «Модальности ввода» на странице модели и результат собственного теста источником
  истины, а не постоянным списком.
</Warning>

## Пять распространённых заблуждений

<AccordionGroup>
  <Accordion title="1. Мультимодальная модель может генерировать изображения">
    **Неверно.** В контексте API multimodal по умолчанию означает возможность **на стороне ввода**. `gpt-5.5` может прочитать макет дизайна,
    который вы отправляете, но не может самостоятельно сгенерировать изображение — чтобы получить его, нужен вызов tool (route C) или
    отдельный вызов к image endpoint (route A).
  </Accordion>

  <Accordion title="2. Image model можно использовать как chat model">
    **Неверно.** У image models нет общей conversational способности — не ставьте `gpt-image-2` за support
    chatbot. Даже варианты `-all` / `-vip`, которые принимают chat endpoint (route D), внутри всё равно остаются image models.
  </Accordion>

  <Accordion title="3. Включение TEXT в responseModalities гарантирует текстовую часть">
    **Обратное неверно.** Указание `responseModalities: ["TEXT", "IMAGE"]` **не** гарантирует текстовую
    часть в ответе; модель может вернуть только изображение. Однако обратное направление полезно: явное указание
    `["IMAGE"]` уменьшает количество лишних текстовых частей.
  </Accordion>

  <Accordion title="4. Переключение между parts[0] и parts[1] исправляет сломанное извлечение изображения">
    **Это не так.** Эти два подхода с жёстко заданным индексом **взаимодополняющие** — изображение всегда попадает в `[0]`
    или `[1]`, поэтому какой бы вариант вы ни выбрали, часть запросов его не найдёт. Изменение индекса лишь меняет,
    какие запросы будут завершаться неудачей. **Стабильна только фильтрация по наличию поля.**
  </Accordion>

  <Accordion title="5. Передача reference image в /v1/images/generations выполняет редактирование">
    **Неверно, и ошибка происходит без уведомления.** Grok Imagine — самый наглядный пример: передача `image` / `image_url` /
    `images` в generation endpoint **возвращает 200 с обычным изображением, но reference image silently
    отбрасывается, и вы тратитесь как обычно** — на выходе вы получаете обычный результат text-to-image.

    Image editing должно проходить через `/v1/images/edits` (а Grok Imagine там дополнительно требует
    `multipart/form-data` — при отправке JSON возвращается жёсткий 400).
  </Accordion>
</AccordionGroup>

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

<CardGroup cols={2}>
  <Card title="Vision (понимание изображений) API" icon="eye" href="/ru/api-capabilities/vision-understanding">
    Полное руководство по стороне ввода: поддерживаемые модели, URL и base64, ввод нескольких изображений, распространённые ошибки
  </Card>

  <Card title="Модели для генерации изображений и видео" icon="palette" href="/ru/api-capabilities/image-video-models">
    Полная таблица моделей для стороны вывода с ценами — место, где можно проверить, какие модели могут генерировать изображения
  </Card>

  <Card title="Руководство для разработчиков серии Nano Banana" icon="banana" href="/ru/api-capabilities/nano-banana-dev-guide">
    Как правильно вызывать семейство изображений Gemini: обход parts, вывод нескольких изображений, обработка mimeType
  </Card>

  <Card title="Генерация изображений с помощью нативного инструмента" icon="wand-sparkles" href="/ru/api-capabilities/gpt-image-2/responses-image-tool">
    Использование инструмента image\_generation в Responses, чтобы модель сама создавала изображение, включая дополнительную плату за вызов инструмента
  </Card>

  <Card title="Примечания и лучшие практики по Image API" icon="list-checks" href="/ru/api-capabilities/image-api-best-practices">
    Матрица endpoint, timeout и формата вывода для моделей image
  </Card>

  <Card title="Как выбрать подходящую модель ИИ?" icon="compass" href="/ru/faq/model-selection-guide">
    Выбор модели по сценарию использования, стоимости и скорости
  </Card>
</CardGroup>