Gemini Image Generation REST API: актуальный cURL-гайд

По состоянию на 27 марта 2026 года самый безопасный default для Gemini image generation через raw REST — POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent. Начинайте с этой точки, добавляйте responseModalities и imageConfig, сохраняйте возвращенный inlineData, и только потом решайте, нужен ли вам OpenAI-compatible слой, прокси или другой model branch.

Это лучший current default не потому, что compatibility route бесполезен, а потому, что Google по-прежнему разносит ответ по разным страницам. Image generation docs показывают native path, API reference фиксирует generateContent и imageConfig, а OpenAI compatibility docs объясняют отдельный совместимый endpoint family. Если читать эти страницы подряд, легко решить, что они одинаково подходят как первый шаг. Для нового raw REST workflow это не так.

Второй caveat надо назвать сразу. Текущие Gemini 3 image models остаются preview, а naming и рекомендуемые пути за последние месяцы менялись достаточно быстро, чтобы старые snippets продолжали путать разработчиков. В официальном OpenAI-compatible image example до сих пор фигурирует gemini-2.5-flash-image, тогда как в native image docs в центре уже стоят gemini-3.1-flash-image-preview и gemini-3-pro-image-preview. Если не разделить эти два слоя заранее, вы рискуете дебажить не ту часть системы.

Краткое содержание

Если вам важен именно split между host и path, без полного workflow, начните с Base URL для Gemini image generation API. Если нужны примеры SDK вместе с cURL, дальше логично идти в примеры кода Gemini image generation.

Сначала используйте native Gemini REST route

Для нового REST workflow полезно держать одну простую мысль: Gemini image generation — это обычный native Gemini API request, который возвращает image data, а не отдельный загадочный image host. Текущий API reference по-прежнему определяет contract внутри generateContent, и image-generation guide учит той же самой method family.

Именно это важно raw REST пользователю, потому что в первой успешной request вы обычно хотите доказать сразу три вещи:

• какой host и model path сейчас правильные
• где лежат image-specific controls
• как выглядит реальный response без SDK abstractions

Native route дает все три. Host понятен, docs свежие, а imageConfig живет в том же request-body без совместимого translation layer. Для cURL-debugging, самописных wrappers и unsupported languages это самый ясный default.

Практический starting model — gemini-3.1-flash-image-preview. Google по-прежнему показывает его в models как текущую efficient image line, а gemini-3-pro-image-preview оставляет для более дорогого premium branch. Legacy lane gemini-2.5-flash-image еще жива, но Google в deprecations уже ставит ей shutdown date 2 октября 2026 года и рекомендует вместо нее gemini-3.1-flash-image-preview.

Скопируйте одну working cURL request

Не пытайтесь сразу построить production pipeline. Сначала докажите host, model и image output. Минимальная request должна быть скучной: один prompt, одна текущая model, одно image output, явный aspectRatio и imageSize.

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a clean 16:9 product image of a matte black travel mug on a light concrete surface with soft studio lighting and premium ecommerce styling."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

Эта request ценна тем, что одновременно подтверждает native path, current model и image controls. По текущему API reference, imageConfig по-прежнему поддерживает aspectRatio и imageSize, а доступные size values — 512, 1K, 2K и 4K.

Если ваша задача — posters, diagrams или text-heavy visuals, где ошибка дорогая, меняйте только model path на gemini-3-pro-image-preview. Если следующий вопрос уже про cost, а не про REST shape, логичнее открыть цены Gemini image generation API.

Сохраните картинку из REST response

Большинство REST-страниц останавливаются на моменте, когда request уже ушла. Но raw REST чаще ломается на следующем шаге: native Gemini response не отдает вам готовый file path, а возвращает image bytes внутри inlineData в JSON.

Именно поэтому многие думают, что “API вернул только JSON и не нарисовал картинку”. Обычно проблема не в том, что model не сработала. Проблема в том, что вы еще не сделали decode и save step.

На native route безопасный порядок такой:

1. прочитать candidates[0].content.parts
2. найти part с inlineData
3. вытащить .inlineData.data
4. сделать base64 decode и записать файл

Один из простых shell-вариантов:

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a square studio photo of a red ceramic teacup on a white background."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }' \
| jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
| base64 --decode > gemini-image.png

На macOS вместо base64 --decode может понадобиться base64 -D. Суть не в конкретном shell flag, а в том, что успешный native response все еще требует явного decode-to-file шага. Именно это отличает “получил JSON” от “получил готовый PNG на диске”.

Когда OpenAI-compatible image path действительно уместен

OpenAI-compatible route реальна, и у нее есть нормальный use case. Google в текущих compatibility docs по-прежнему показывает:

text
https://generativelanguage.googleapis.com/v1beta/openai/

и image endpoint:

text
/v1beta/openai/images/generations

Если ваш project уже завязан на OpenAI-style client surface и business goal звучит как “подключить Gemini с минимальным rewrite”, эта route имеет смысл. Она позволяет быстро проверить совместимость без полной переделки client-side logic.

Но это не лучший default под запрос “gemini image generation rest api”. Здесь читателю нужен текущий native Gemini contract, а не самый дешевый migration layer для OpenAI tooling. Это разные задачи.

Разница хорошо видна и в docs, и в community friction. На 27 марта 2026 года официальный совместимый image example все еще использует gemini-2.5-flash-image, тогда как current native docs уже учат Gemini 3 image line. В forum threads видно и другое: как только разработчики пытаются передать native image expectations через OpenAI-compatible route, появляются 404 или invalid-payload errors.

Практическое правило поэтому короткое:

• новый проект, cURL, raw REST, current docs: native Gemini first
• уже существующий OpenAI-style stack: compatibility route по необходимости
• не мешайте эти два contract в одной первой debug-сессии

Какие model, pricing и status caveats реально меняют решение

Даже корректный REST syntax не гарантирует, что вы выбрали правильную implementation route. На решение влияют model lane, preview status, billing и live limits.

Billing и limits тоже нельзя игнорировать. Google на billing page по-прежнему пишет, что новые accounts стартуют с Free Tier и что только certain models доступны в этих рамках. А rate-limits page прямо говорит: limits зависят от usage tier и смотрятся в AI Studio, а не угадываются по чужому tutorial.

Именно поэтому эта страница не обещает вам “полностью бесплатный Gemini image REST API”. Current surface сложнее. Request может быть написана правильно, но проблема все равно окажется в model access, project tier или preview-limit policy.

Troubleshooting: сначала поймите, какой слой реально сломан

У этого keyword есть явный troubleshooting-intent. Очень часто разработчик ищет его только после первого провала, а не заранее. Хорошая новость в том, что самые частые failures повторяются из раза в раз.

Главный time saver здесь один: меняйте по одному слою за раз. Не переключайте одновременно host, model, prompt и save logic. Сначала докажите native request, потом save step, потом уже сравнивайте quotas, wrappers и compatibility behavior.

Если ваш problem-space уже перешел из endpoint-choice в 429, 400 или 500, следующая полезная страница — Gemini API error fix 2026: 429, 400, 500.

FAQ

Неправильный ли /v1beta/openai/images/generations сам по себе?

Нет. Эта route существует и подходит, когда у вас уже есть OpenAI-style client surface и вы сознательно хотите сохранить совместимую схему вызова. Но для нового raw REST workflow это не лучший первый шаг. В большинстве случаев быстрее сначала доказать native generateContent, а уже потом сравнивать compatibility behavior. Так вы сразу поймете, проблема в endpoint family, в payload shape или уже в migration layer поверх базового Gemini contract.

Почему API возвращает только JSON, а не готовый файл?

Потому что на native route успешный ответ и должен возвращать image bytes внутри JSON, обычно в inlineData. Это не признак ошибки. Это признак того, что последний шаг еще не выполнен: нужно извлечь .inlineData.data, сделать base64 decode и записать картинку в файл.

С какой image model сейчас реально начинать?

Практический default сейчас — gemini-3.1-flash-image-preview, потому что именно на нее указывает текущая native documentation как на рабочую эффективную image lane. Если вам нужны posters, diagrams или text-heavy visuals, где цена ошибки выше, имеет смысл смотреть на gemini-3-pro-image-preview. Старый gemini-2.5-flash-image еще встречается в compatibility examples, но Google уже поставил ему shutdown date: 2 октября 2026 года.

Что проверять первым, если AI Studio работает, а cURL нет?

Сначала проверьте не URL, а context. Должны совпадать project, API key и model access. Затем уже смотрите billing, tier и live limits. Очень многие проблемы, которые выглядят как REST bug, на деле оказываются несоответствием project state между browser test и raw API call. Если один и тот же prompt работает в UI, но не воспроизводится через cURL, почти всегда полезнее сравнить project binding и access policy, чем сразу переписывать весь request body.

Итог

Для текущего raw HTTP image generation начинайте с native Gemini Developer API:

text
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent

Используйте responseModalities и imageConfig, сохраните inlineData, и только потом переходите к /v1beta/openai/images/generations, если ваш stack действительно должен сохранить OpenAI-compatible semantics.

Это и есть самый безопасный current default: он совпадает с актуальными native Gemini docs, использует текущую image-model family и убирает главное заблуждение вокруг этого keyword — попытку считать совместимый OpenAI image path universal starting point для всех Gemini image REST scenarios.

Проще говоря: сначала докажите native route, потом сохранение файла, и только после этого принимайте решение о compatibility layer. Такой порядок почти всегда сокращает время дебага заметно.