Нативный API Gemini

Вызывайте Gemini 4 Argon, Gemini 3.8 Flash и Gemini 3.1 Pro запросами Gemini generateContent с одним ключом BeatAPI.

• Для всех актуальных моделей Gemini: POST /v1beta/models/{model}:generateContent, а для потоковой передачи — :streamGenerateContent?alt=sse.
• Текст и изображения на входе, текст на выходе, потоковая передача, вызовы функций и рассуждения.
• Передавайте ключ в заголовке x-goog-api-key либо как токен Bearer.
• Модель указывается в URL, а не в теле запроса.

Открывает эндпоинт в API Explorer. Если ввести ключ BeatAPI и отправить запрос, будет выполнен реальный вызов с оплатой из вашего баланса.

Модели

Подставьте один из этих ID в URL вместо {model}.

• Указаны базовые цены со скидкой. Не включены тарифы для длинного контекста, кэшированного ввода и записи в кэш. См. страницу цен.
• — означает, что каталог не публикует это значение.

Старые ID этого семейства остаются доступны. См. старые модели.

Быстрый старт

Храните ключ в BEATAPI_API_KEY и не помещайте его в код браузерного приложения. ID модели указывается в URL, поэтому в теле нет поля model. Ниже показаны примеры запросов, а не записанные ответы модели.

Прочитайте ответ в candidates[0].content.parts[0].text, затем проверьте candidates[0].finishReason и usageMetadata. Сам по себе HTTP 200 не означает, что ответ решает вашу задачу: проверяйте результат в приложении. Текстовые запросы возвращают ответ напрямую; опрашивать /v1/tasks для них не нужно.

curl --request POST \
  --url https://direct.beatapi.io/v1beta/models/gemini-3.8-flash:generateContent \
  --header "x-goog-api-key: $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Design a resilient webhook retry strategy for a payments API."
        }
      ]
    }
  ]
}'

Эндпоинт и аутентификация

POST https://direct.beatapi.io/v1beta/models/{model}:generateContent

Для потоковой передачи используйте POST /v1beta/models/{model}:streamGenerateContent?alt=sse. Ключ можно передать в x-goog-api-key или в Authorization: Bearer <key>: работают оба варианта.

:countTokens недоступен и возвращает 404.

Параметры запроса

Перечислены поля, которые действительно влияют на запрос. Остальные поля Gemini принимаются, но не действуют: generationConfig.thinkingConfig, generationConfig.responseMimeType, generationConfig.responseSchema, generationConfig.seed, safetySettings, toolConfig и cachedContent. Не полагайтесь на них.

[
  {
    "role": "user",
    "parts": [
      { "text": "What is in this image?" },
      { "inlineData": { "mimeType": "image/png", "data": "<base64>" } }
    ]
  }
]

{
  "parts": [{ "text": "Answer in one short paragraph." }]
}

{
  "temperature": 0.7,
  "topP": 0.95,
  "maxOutputTokens": 2048,
  "stopSequences": ["END"]
}

[
  {
    "functionDeclarations": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ]
  }
]

Ответ

Без потоковой передачи запрос возвращает один JSON-объект. Ниже приведён сокращённый пример.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 19,
    "candidatesTokenCount": 16,
    "totalTokenCount": 120,
    "thoughtsTokenCount": 85
  }
}

Поля ответа

Потоковая передача

Вызовите :streamGenerateContent?alt=sse. Каждое событие — строка data: {...} с объектом candidates в том же формате, что и ответ без потоковой передачи.

• Последнее событие содержит finishReason, например "STOP".
• Тип ответа — text/event-stream. Ошибка до вызова модели возвращается обычным JSON-ответом с HTTP-кодом, а не событием потока.
• Явно задайте тайм-ауты и предусмотрите безопасное восстановление соединения при потоковой передаче.

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Retry"}]},"index":0}]}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":" with backoff"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":19,"candidatesTokenCount":16,"totalTokenCount":120,"thoughtsTokenCount":85}}

Устранение ошибок

Обзор HTTP-ошибок

Нативные эндпоинты Gemini возвращают ошибки в формате {"error": {"message", "type": "beatapi_error", "code"}}. Код находится в error.code, ID запроса — в конце message. Поля retryable нет. См. ошибки.

Все коды и правила повторных запросов: ошибки.

Примечания

• Модели Gemini также доступны через Chat Completions, Responses и Anthropic Messages. См. другие страницы Gemini.
• Токены рассуждений оплачиваются как выходные. Оставляйте лимит и для рассуждений, и для ответа, а не только для видимого ответа.
• Храните ключи на доверенных серверах, записывайте ID запроса из ответа и повторяйте запросы только при ошибках 429, 500 и 503.