ДокументацияСправочник APIGemini API

Gemini API

Совместимые с Google Gemini эндпоинты — generateContent, streamGenerateContent, countTokens.

POST/v1beta/models/{model}:generateContent

Чат-эндпоинт, совместимый с телом запроса Google Gemini API. Имя модели и действие указываются в пути ({model}:generateContent); аутентификация через заголовок x-goog-api-key.

Официальный параметр Google ?key= не поддерживается — ключ передаётся только в заголовке x-goog-api-key (Google GenAI SDK использует его по умолчанию).

Тело запроса

ПолеТипОбязательноеОписание
contentsarrayДаСодержимое диалога: каждый элемент содержит role (user/model) и parts (текст или встроенные медиа).
systemInstructionobjectНетСистемный промпт ({ "parts": [{ "text": … }] }).
generationConfigobjectНетПараметры генерации: temperature, maxOutputTokens и т. д.
request.sh
curl "https://soleapi.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a haiku about the sea"}]}]
  }'

Ответ

response.json
{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "Waves fold into foam..." }],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 14,
    "candidatesTokenCount": 23,
    "totalTokenCount": 37
  }
}

Потоковая генерация

POST/v1beta/models/{model}:streamGenerateContent

Добавьте ?alt=sse для потоковой передачи по SSE — каждая строка data: содержит фрагмент ответа; без alt=sse вернётся полный JSON-массив. См. Стриминг.

Подсчёт токенов

POST/v1beta/models/{model}:countTokens
count_tokens.sh
curl "https://soleapi.com/v1beta/models/gemini-3.7-flash:countTokens" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a haiku about the sea"}]}]
  }'

# => { "totalTokens": 14 }

Генерация изображений (Nano Banana)

У моделей изображений Gemini (gemini-2.5-flash-image, gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image) нет отдельного эндпоинта для изображений — используются те же generateContent / streamGenerateContent, что и выше. Тело запроса такое же, как у текстового диалога; достаточно указать в generationConfig.responseModalities, что нужны изображения. Сгенерированные изображения возвращаются как inlineData (base64) внутри parts.

ПолеТипОписание
generationConfig.responseModalitiesarray["TEXT", "IMAGE"]; для вывода только изображений — ["IMAGE"].
generationConfig.imageConfig.aspectRatiostring1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.
generationConfig.imageConfig.imageSizestring1K (по умолчанию), 2K, 4K; gemini-3.1-flash-image также принимает 0.5K, gemini-3.1-flash-lite-image — только 1K, gemini-2.5-flash-image это поле не поддерживает.
generate_image.sh
curl "https://soleapi.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A watercolor lighthouse at dawn"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'
response.json
{
  "candidates": [
    {
      "content": {
        "parts": [
          { "text": "Here is the lighthouse." },
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgo..." } }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 1694,
    "candidatesTokensDetails": [
      { "modality": "TEXT", "tokenCount": 14 },
      { "modality": "IMAGE", "tokenCount": 1680 }
    ],
    "totalTokenCount": 1703
  }
}

Редактирование изображения: положите исходное изображение (до 14 штук) как inlineData в contents[].parts вместе с текстовой инструкцией; остальная часть запроса не меняется.

edit_request.json
{
  "contents": [{
    "parts": [
      { "text": "Turn the sky into a starry night" },
      { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
    ]
  }],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

Изображения тарифицируются по выходным токенам (запись modality = IMAGE в usageMetadata.candidatesTokensDetails); цены см. на странице модели. Изображение 1K — примерно 1 120–1 290 токенов, 2K — около 1 680, 4K — около 2 000–2 520. Потоковый режим работает так же, как для текста (streamGenerateContent?alt=sse); изображение приходит целиком в последнем фрагменте.