Gemini

Half Off Dev предоставляет собственные методы Gemini generateContent, streamGenerateContent и countTokens по адресу /v1beta/models/{model}. Передайте Google Gen AI SDK базовый URL https://halfoff.dev и ваш ключ Half Off Dev в качестве API-ключа, и существующий код на Gemini продолжит работать за половину прайсовой цены. Тела пересылаются без изменений, поэтому каждое поле описано в справочнике API Google.

Настройте SDK#

SDK аутентифицируются через x-goog-api-key. Параметр запроса ?key= тоже принимается.

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Summarize what a CDN does for a small blog."}]}]
  }'

Установка: pip install google-genai или npm install @google/genai. Id моделей берите из GET /v1/models; написания от Google вроде gemini-3.1-pro-preview сводятся к той же модели. Список в формате ответа Gemini вернёт GET /v1beta/models.

Потоковая передача через server-sent events#

Запросите :streamGenerateContent?alt=sse, чтобы получать SSE. Каждое событие — частичный GenerateContentResponse, а последнее содержит полный usageMetadata. SDK добавляют alt=sse сами.

curl -N "https://halfoff.dev/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Write a four-line poem about compilers."}]}]}'

Если опустить alt=sse, метод отдаёт один JSON-массив. Это работает, но SSE проще разбирать по частям, и только в этом режиме шлюз может отправить корректное событие об ошибке, если поток зависнет. См. Потоковая передача.

Системные инструкции и thinking#

systemInstruction, generationConfig, safetySettings и объявления функций в tools проходят ровно так, как описывает Google. Модели Gemini 3 по умолчанию размышляют; настраивайте это через thinkingConfig по руководству Google по thinking.

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="Suggest a weekly study plan for learning Rust in two months.",
    config=types.GenerateContentConfig(
        system_instruction="You are a practical programming coach. Use bullet points.",
        max_output_tokens=4096,
    ),
)
print(response.text)
print(response.usage_metadata)

Размышления отображаются в usageMetadata.thoughtsTokenCount и тарифицируются по цене выходных токенов вместе с candidatesTokenCount. Как и в API Google, сводки размышлений возвращаются частями с пометкой "thought": true, только если вы задали generationConfig.thinkingConfig.includeThoughts: true; иначе в ответе нет частей с размышлениями.

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

:countTokens принимает те же contents, с которыми вы бы генерировали, и возвращает totalTokens. Это бесплатно и работает при нулевом балансе. Считайте число приблизительным: оно годится для сверки с контекстным окном, но не для предсказания списания с точностью до цента.

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:countTokens" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Measure this sentence."}]}]}'

Gemini CLI#

Gemini CLI берёт адрес и ключ из переменных окружения:

export GOOGLE_GEMINI_BASE_URL=https://halfoff.dev
export GEMINI_API_KEY="$HALFOFF_API_KEY"
gemini -m gemini-3.1-pro

Полное руководство — в разделе Gemini CLI.

Кеширование#

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

Что не поддерживается#

Эти функции API Gemini возвращают 404: cachedContents (явное кеширование контекста), загрузка файлов, embedContent и batchEmbedContents, пакетный режим и Live API.

Заголовки запроса#

Ошибки имеют формат Gemini, {"error": {"code": 429, "message": "...", "status": "RESOURCE_EXHAUSTED"}}; см. Ошибки.