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-image | 1K (по умолчанию) / 2K / 4Kimage_config | до 14 (data URI / публичный URL) | всегда 1 | за запрос |
gemini-nano-banana-2.1 | 1K (по умолчанию) / 2K / 4Kimage_config | до 6 (data URI / публичный URL) | всегда 1 | за запрос |
gemini-3-pro-image | 1K (по умолчанию) / 2K / 4Kimage_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/completions | model + messages | OpenAI SDK, универсальные клиенты и большинство приложений |
| Нативный протокол Gemini | POST /v1beta/models/{model}:generateContent | contents + 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.
Выходные размеры в пикселях для каждого уровня:
| Соотношение | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 3:4 | 896x1200 | 1792x2400 | 3584x4800 |
| 4:3 | 1200x896 | 2400x1792 | 4800x3584 |
| 4:5 | 928x1152 | 1856x2304 | 3712x4608 |
| 5:4 | 1152x928 | 2304x1856 | 4608x3712 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 21:9 | 1584x672 | 3168x1344 | 6336x2688 |
- Если соотношение сторон не указано, модель выбирает формат кадра по промпту; при наличии референсов по умолчанию используется соотношение сторон первого референса. Если нужен фиксированный размер, явно передайте
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 МБ.
- Несколько референсов передаются по порядку, в промпте на них можно ссылаться как на «первое изображение», «второе изображение».
Поля запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
model | string | Да | Название модели изображений Gemini. |
messages | array | Да | Массив сообщений OpenAI Chat Completions, обычно одно сообщение user. |
messages[].content | string или array | Да | Для чистого текста — строка; для текста вместе с референсами — массив содержимого. |
content[].image_url.url | string | Нет | Референс: Data URI или публичный URL. |
extra_body.google.image_config.aspect_ratio | string | Нет | Соотношение сторон. |
extra_body.google.image_config.image_size | string | Нет | 1K, 2K, 4K. |
Ответ
Изображение возвращается в choices[0].message.content в виде изображения Markdown:
{
"choices": [
{
"message": {
"role": "assistant",
"content": ""
},
"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 instead | image_config записан в camelCase. |
mime type is not supported by Gemini | Формат референса не поддерживается, например BMP. |
failed to download file | Не удалось скачать референс по URL — убедитесь, что ссылка общедоступна. |
| Сообщение о том, что модерация контента не пройдена | Промпт или референс не прошли проверку безопасности, либо модель ответила только текстом без изображения. Измените промпт и повторите попытку. |
За перечисленные неудачные запросы плата не взимается.
API моделей изображений OpenAI
Интерфейсы, размеры, уровни качества, референсы и прозрачный фон для моделей изображений gpt-image-2, gpt-image-2.5 и серии az-gpt-image.
API моделей изображений Grok
Интерфейсы генерации по тексту и редактирования, соотношения сторон, разрешения, референсы и ошибки для моделей изображений Grok Imagine (grok-imagine-image, 2.0, quality, edit).