Gemini 3.1 Pro · API

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

Два шага: отправить запрос, а затем получить ответ в потоковом режиме. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть. Эндпоинт совместим с OpenAI Chat Completions, поэтому в готовом коде для OpenAI достаточно поменять base_url и model.

Шаг 1 · Отправка запроса

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'

Ответ (HTTP 200)

{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-3.1-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Фотосинтез — это процесс, в котором растения с помощью солнечного света превращают углекислый газ и воду в сахар и выделяют кислород."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60,
    "prompt_tokens_details": {"cached_tokens": 0}
  }
}

message.content — это ответ. В usage — токены, по которым оплачивается этот запрос; prompt_tokens_details.cached_tokens — часть, взятая из кэша и оплачиваемая по цене кэша.

Шаг 2 · Потоковый вывод (рекомендуется)

curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "stream": true, "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'

Поток — это стандартный SSE: каждый фрагмент несёт текст в choices[0].delta.content, последний фрагмент содержит usage, а завершается поток строкой data: [DONE]. Для длинных ответов и моделей с размышлениями используйте потоковый вывод: непотоковый запрос обрывается примерно через 10 минут.

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="https://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. Один запрос — один ответ
resp = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
)
print(resp.choices[0].message.content)

# 2. Потоковый вывод
stream = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Чтобы начать, создайте API-ключ в консоли.

Основные характеристики

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

JSON-тело запроса POST /v1/chat/completions — такое же, как в OpenAI Chat Completions. Основные параметры и то, как каждый из них работает у этой модели:

Остальные параметры OpenAI (например, stop, seed, user) передаются модели без изменений; сработают ли они, зависит от модели.

Цена

Оплата за токены по актуальным ценам ниже (за миллион токенов). Оплачиваются только успешные запросы и только по фактическому расходу: неудачные, прерванные по таймауту и отклонённые запросы бесплатны. 1 кредит = $0.005.

Например, запрос с 2000 входных токенов и 1000 выходных (включая размышления) стоит около $0.004.

Размышления

Два уровня: без параметра или с reasoning_effort: "low" — стандартный уровень, быстрее и с меньшим числом токенов размышлений; medium, high или xhigh — уровень глубоких рассуждений: модель размышляет глубже, а оплата идёт по цене этого уровня (см. «Цена» выше); запросы на уровне глубоких рассуждений отображаются в списаниях и в журнале запросов как gemini-3.1-pro-preview.

Уровень можно задать и через ID модели: gemini-3.1-pro-high — уровень глубоких рассуждений, gemini-3.1-pro-low — стандартный уровень.

Токены размышлений входят в usage.completion_tokens и оплачиваются по цене выхода (некоторые модели ещё и указывают их отдельно в completion_tokens_details.reasoning_tokens).

Кэширование промптов

Параметры не нужны: повторяющийся длинный префикс (тот же системный промпт, предыдущие ходы диалога) поставщик модели может закэшировать автоматически, и закэшированная часть оплачивается по более низкой цене кэша. Кэшировать ли и сколько, решает поставщик; чтобы чаще попадать в кэш, ставьте неизменные части в самое начало сообщений.

Число токенов из кэша возвращается в usage.prompt_tokens_details.cached_tokens; эта часть оплачивается по цене попадания в кэш, а остальной вход — по цене входа.

Ввод изображений

Добавьте в массив content часть image_url. Рекомендуемый вариант — data URI в base64 (data:image/png;base64,...): его всегда удаётся прочитать. Изображение по публичной ссылке сначала нужно скачать, и иногда это не удаётся или не укладывается в таймаут. Изображения пересчитываются во входные токены по правилам разработчика модели.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "messages": [{"role": "user", "content": [{"type": "text", "text": "Что изображено на этой картинке"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

Веб-поиск

Добавьте в запрос "web_search": true (или элемент {"type": "web_search"} в tools): шлюз сначала ищет в интернете в реальном времени по содержанию диалога, передаёт модели до 5 результатов со ссылками как справочные материалы, а модель отвечает и указывает источники. Сам поиск бесплатный; справочный текст оплачивается как входные токены.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "web_search": true, "messages": [{"role": "user", "content": "Какие главные технологические новости сегодня"}]}'

Надёжность и автоматические повторы

• Если запрос завершился ошибкой, не уложился в таймаут или упёрся в предел нагрузки, шлюз ещё до начала ответа автоматически повторяет его: повторять запрос самому не нужно, и дважды ничего не спишется.
• Начав передачу, поток больше не повторяется автоматически: если он оборвётся на середине, оплачивается то, что успело сгенерироваться до обрыва (см. Оплата и возвраты).
• Если модель загружена до предела, шлюз возвращает 429 с Retry-After: подождите указанное число секунд и повторите. Неудачные запросы не оплачиваются. Статус каждой модели — на странице статуса.

Ошибки и возвраты

Ошибки возвращаются объектом error (message, type, code, param); ориентируйтесь на HTTP-статус и code, а не на текст message. Неудачные запросы не оплачиваются; полный список — в разделе Коды ошибок.

Если поток дал сбой уже после начала передачи, код статуса не меняется: ошибка приходит строкой данных с error, или поток просто заканчивается (без data: [DONE]). Считайте такой поток оборванным.