88API88API
Руководство пользователяAI-приложенияAPIПомощь и поддержка
Изображения (Image)

API моделей изображений Gemini

Форматы запросов через OpenAI-совместимый протокол и нативный протокол Gemini, соотношения сторон, разрешения и референсы для Gemini 3.1 Flash Image, Nano Banana 2.1 и Gemini 3 Pro Image.

Область применения

На этой странице описаны модели изображений Gemini. О моделях изображений OpenAI см. API моделей изображений OpenAI, о моделях изображений Grok — API моделей изображений Grok.

Ключевое отличие

Модели изображений Gemini не являются моделями OpenAI Images API. Используйте /v1/chat/completions или нативный для Gemini /v1beta/models/{model}:generateContent; не отправляйте запросы на /v1/images/generations или /v1/images/edits.

Модели и возможности

МодельРазрешениеРеференсыИзображений за запросОплата
gemini-3.1-flash-image1K (по умолчанию) / 2K / 4K
image_config
до 14 (data URI / публичный URL)всегда 1за запрос
gemini-nano-banana-2.11K (по умолчанию) / 2K / 4K
image_config
до 6 (data URI / публичный URL)всегда 1за запрос
gemini-3-pro-image1K (по умолчанию) / 2K / 4K
image_config
до 14 (data URI / публичный URL)всегда 1за запрос

Поддерживаемые соотношения сторон: 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9

  • Все три модели тарифицируются за запрос, цена не зависит от разрешения и количества референсов.
  • Каждый запрос возвращает только 1 изображение, n и candidateCount не действуют; если нужно несколько изображений, отправляйте несколько запросов параллельно.
  • Для gemini-nano-banana-2.1 рекомендуется передавать не более 6 референсов за запрос — остальные могут быть не использованы.

Фактически доступные модели определяются списком моделей в консоли.

Поддерживаемые протоколы

ПротоколКонечная точкаФормат тела запросаСценарий
OpenAI-совместимый протокол (рекомендуется)POST /v1/chat/completionsmodel + messagesOpenAI SDK, универсальные клиенты и большинство приложений
Нативный протокол GeminiPOST /v1beta/models/{model}:generateContentcontents + generationConfigПрямое использование Gemini SDK или нужны нативные поля

Аутентификация

Для OpenAI-совместимого протокола:

Authorization: Bearer $API_KEY
Content-Type: application/json

В нативном протоколе Gemini можно, как принято в клиентах Gemini, использовать заголовок x-goog-api-key — в нём указывается тот же токен 88API. Не размещайте реальный ключ во фронтенд-коде, логах или публичных примерах.

Соотношение сторон и разрешение

Соотношение сторон и разрешение задаются через image_config:

  • aspect_ratio: см. таблицу возможностей выше.
  • image_size: 1K (по умолчанию), 2K, 4K; используйте заглавную K.

Выходные размеры в пикселях для каждого уровня:

Соотношение1K2K4K
1:11024x10242048x20484096x4096
2:3848x12641696x25283392x5056
3:21264x8482528x16965056x3392
3:4896x12001792x24003584x4800
4:31200x8962400x17924800x3584
4:5928x11521856x23043712x4608
5:41152x9282304x18564608x3712
9:16768x13761536x27523072x5504
16:91376x7682752x15365504x3072
21:91584x6723168x13446336x2688
  • Если соотношение сторон не указано, модель выбирает формат кадра по промпту; при наличии референсов по умолчанию используется соотношение сторон первого референса. Если нужен фиксированный размер, явно передайте aspect_ratio.
  • Результат может быть в формате JPEG или PNG — сохраняйте файл по возвращённому MIME-типу, не полагайтесь на расширение.

OpenAI-совместимый протокол (рекомендуется)

Генерация по тексту

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "messages": [
      {
        "role": "user",
        "content": "Сгенерируй изображение рыжего кота, сидящего у окна, естественный дневной свет, реалистичная фотография"
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "16:9",
          "image_size": "2K"
        }
      }
    }
  }'

Как указывать image_config

Соотношение сторон и разрешение нужно указывать в extra_body.google.image_config, имена полей — aspect_ratio и image_size (через подчёркивание). image_config, aspect_ratio и size на верхнем уровне запроса игнорируются; варианты в camelCase, например imageConfig или aspectRatio, отклоняются.

Запрос с референсом

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "По образцу персонажа с первого изображения создай киноафишу с этим же персонажем" },
          { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
        ]
      }
    ],
    "extra_body": {
      "google": { "image_config": { "aspect_ratio": "2:3", "image_size": "2K" } }
    }
  }'
  • image_url.url может быть Data URI или публичным URL изображения. Data URI должен содержать полный префикс медиатипа, например data:image/png;base64,....
  • Поддерживаются PNG, JPEG, WebP, GIF; BMP не поддерживается. Рекомендуемый размер одного изображения — не более 7 МБ.
  • Несколько референсов передаются по порядку, в промпте на них можно ссылаться как на «первое изображение», «второе изображение».

Поля запроса

ПолеТипОбязательноОписание
modelstringДаНазвание модели изображений Gemini.
messagesarrayДаМассив сообщений OpenAI Chat Completions, обычно одно сообщение user.
messages[].contentstring или arrayДаДля чистого текста — строка; для текста вместе с референсами — массив содержимого.
content[].image_url.urlstringНетРеференс: Data URI или публичный URL.
extra_body.google.image_config.aspect_ratiostringНетСоотношение сторон.
extra_body.google.image_config.image_sizestringНет1K, 2K, 4K.

Ответ

Изображение возвращается в choices[0].message.content в виде изображения Markdown:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "![image](data:image/jpeg;base64,/9j/4AAQ...)"
      },
      "finish_reason": "stop"
    }
  ]
}

Чтобы получить изображение, извлеките data:<mime>;base64,... из content. Не разбирайте ответ как массив data из /v1/images/generations.

Нативный протокол Gemini

Генерация по тексту

curl "https://api.88api.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Сгенерируй изображение рыжего кота, сидящего у окна, естественный дневной свет, реалистичная фотография" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Референс

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "По образцу этого изображения создай киноафишу с этим же персонажем" },
        { "inlineData": { "mimeType": "image/png", "data": "<BASE64_DATA>" } }
      ]
    }
  ],
  "generationConfig": {
    "imageConfig": { "aspectRatio": "2:3" }
  }
}

Для публичных изображений можно также использовать fileData: { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }.

Ответ

Изображение находится в candidates[0].content.parts[].inlineData: mimeType — тип изображения, data — Base64.

Потоковый режим и тайм-ауты

stream: true использовать можно, но изображение приходит целиком в одном событии, постепенного предпросмотра нет. Рекомендуем использовать непотоковые запросы и ставить тайм-аут клиента не меньше 5 минут: генерация изображения 4K обычно занимает 30–60 секунд, а в часы пик — дольше.

Как не нужно делать запрос

# Неправильно: для моделей изображений Gemini не используйте путь OpenAI Images API
curl https://api.88api.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "Рыжий кот"
  }'

Такой запрос вернёт 请使用 Gemini 原生接口调用 / please use the Gemini native API. Используйте формат Chat Completions или нативный generateContent, описанные на этой странице.

Частые ошибки

ОшибкаПричина
请使用 Gemini 原生接口调用 (используйте нативный интерфейс Gemini)Запрос отправлен на /v1/images/*.
extra_body.google.imageConfig is not supported, use extra_body.google.image_config insteadimage_config записан в camelCase.
mime type is not supported by GeminiФормат референса не поддерживается, например BMP.
failed to download fileНе удалось скачать референс по URL — убедитесь, что ссылка общедоступна.
Сообщение о том, что модерация контента не пройденаПромпт или референс не прошли проверку безопасности, либо модель ответила только текстом без изображения. Измените промпт и повторите попытку.

За перечисленные неудачные запросы плата не взимается.