API Reference

Gemini API: текст и видео через BetterToken

Вызывайте Gemini через OpenAI Chat Completions или нативный API Gemini в BetterToken. Аутентификация, SDK, потоковые ответы, инструменты, видео и устранение ошибок.

Вызывайте gemini-3.8-flash и gemini-4-argon с вашим BetterToken API Key. Оба интерфейса поддерживают текст, видео, потоковые ответы, вызовы инструментов и передачу их результатов.

Выберите интерфейс

Интерфейс	Base URL	Когда использовать
OpenAI-совместимый	`https://bettertoken.ai/v1`	Ваше приложение использует Chat Completions или OpenAI SDK.
Нативный Gemini	`https://bettertoken.ai`	Ваше приложение использует поля запросов Gemini или Google GenAI SDK.

Во всех примерах используется gemini-3.8-flash. Замените его на gemini-4-argon, чтобы вызвать другую модель. Актуальные цены смотрите в каталоге моделей. Для генерации изображений откройте отдельное руководство по Nano Banana.

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

Создайте BetterToken API Key, затем замените YOUR_API_KEY ниже. Выполните команду в том же терминале, где будете запускать примеры.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Интерфейс	Аутентификация
OpenAI-совместимый	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Нативный Gemini	`x-goog-api-key: $BETTERTOKEN_API_KEY` (рекомендуется) или `Authorization: Bearer $BETTERTOKEN_API_KEY`

Ключ Google AI Studio здесь не работает. Используйте BetterToken API Key. Нативный интерфейс также принимает ?key=, но лучше передавать ключ в заголовке: URL могут попадать в журналы.

OpenAI-совместимый интерфейс

Отправляйте запросы на POST https://bettertoken.ai/v1/chat/completions. Для SDK укажите Base URL https://bettertoken.ai/v1: SDK сам добавит /chat/completions.

curl: базовый запрос

curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Explain why the sky is blue."}]
  }'

Читайте текст из choices[0].message.content. Для потокового ответа в curl добавьте "stream": true в тело JSON и используйте curl --no-buffer.

Python: базовый запрос и потоковый ответ

Установите OpenAI SDK в своё окружение Python, затем запустите пример.

python -m pip install openai

Потоковый запрос использует stream=True. Читайте текст из choices[0].delta.content каждого блока.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
)
messages = [{"role": "user", "content": "Explain why the sky is blue."}]

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
)
print(response.choices[0].message.content)

stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

Вызов инструментов

Объявите функции в tools: укажите type: "function", имя функции name и JSON Schema в parameters. Когда assistant вернёт tool_calls, выполните нужные функции в своём приложении.

Сохраните полное сообщение assistant, включая tool_calls, в диалоге. Для каждого результата добавьте сообщение role: "tool". Укажите ID соответствующего вызова в tool_call_id, а результат — в content. Снова отправьте обновлённые messages и tools в Chat Completions.

Для входных изображений в этом интерфейсе используйте элемент image_url с HTTP URL или data URL, как и для других моделей.

Нативный интерфейс Gemini

Для Google GenAI SDK задайте Base URL https://bettertoken.ai. Не добавляйте /v1beta: SDK добавляет его сам. Для прямых HTTP-запросов используйте полные пути ниже.

curl: generateContent

curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

Читайте текст из candidates[].content.parts[].text.

curl: потоковый ответ

streamGenerateContent?alt=sse возвращает события Server-Sent Events (SSE). Параметр --no-buffer выводит события по мере поступления.

curl --fail-with-body --no-buffer \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

Python: Google GenAI SDK

Установите google-genai в своё окружение Python. Пример сначала отправляет обычный запрос, затем потоковый.

python -m pip install google-genai

import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    http_options=types.HttpOptions(base_url="https://bettertoken.ai"),
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
)
print(response.text)

for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
):
    print(chunk.text or "", end="", flush=True)
print()

Node.js: Google GenAI SDK

Установите @google/genai. Сохраните JavaScript-пример как gemini.mjs, затем выполните node gemini.mjs.

npm install @google/genai

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  httpOptions: { baseUrl: "https://bettertoken.ai" },
});

const response = await client.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
console.log(response.text);

const stream = await client.models.generateContentStream({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}
console.log();

Вызов инструментов

Объявите функции в tools[].functionDeclarations. Прочитайте имя функции и аргументы из functionCall в частях ответа модели, затем выполните функцию в своём приложении.

Сохраните полное содержимое ответа модели в contents. Добавьте запись role: "user", в которой parts содержит functionResponse. Укажите соответствующее имя функции name и объект response с результатом. Снова отправьте обновлённые contents и tools в generateContent.

Список моделей

Получите список моделей через GET https://bettertoken.ai/v1beta/models.

curl --fail-with-body "https://bettertoken.ai/v1beta/models" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY"

Видеовход

Перед отправкой любого примера замените REPLACE_WITH_VIDEO_BASE64 на base64 вашего видео в одну строку. В примерах используется MP4. Для другого формата измените MIME-тип и имя файла.

Допустимые MIME-типы: video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/wmv, video/flv, video/mpegps.

Передавайте видео в виде встроенных данных base64 в теле запроса. Base64 увеличивает объём примерно на треть относительно файла. Используйте короткие или сжатые ролики: слишком большой запрос может вернуть HTTP 413.

В OpenAI-совместимом интерфейсе file.file_data включает префикс data:video/mp4;base64,. В нативном интерфейсе inlineData.data содержит только base64, без этого префикса.

Chat Completions: встроенный файл

curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gemini-3.8-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "file", "file": {
        "filename": "clip.mp4",
        "file_data": "data:video/mp4;base64,REPLACE_WITH_VIDEO_BASE64"
      }},
      {"type": "text", "text": "Describe what happens in this video."}
    ]
  }]
}
JSON

Нативный Gemini: inlineData

curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "video/mp4", "data": "REPLACE_WITH_VIDEO_BASE64"}},
      {"text": "Describe what happens in this video."}
    ]
  }]
}
JSON

Использование токенов и оплата

Chat Completions: токены рассуждения/размышления входят в completion_tokens и оплачиваются как выходные.

Нативный Gemini: usageMetadata.thoughtsTokenCount оплачивается как выходные токены. cachedContentTokenCount показывает кешированный вход. Видео учитывается как входные токены; в promptTokensDetails оно обозначено модальностью VIDEO.

Ограничения

POST /v1/responses не поддерживает эти модели Gemini. Codex CLI и другие клиенты, использующие только Responses API, не могут их вызывать. Используйте Chat Completions или нативный интерфейс.
Ссылки file_id и загрузки Google File API через fileData.fileUri не поддерживаются. Передавайте видео как встроенные данные base64.

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

Ошибка	Что делать
`401`	Проверьте BetterToken API Key и заголовок аутентификации. Добавьте отсутствующий ключ или замените неверный.
`413`	Тело запроса слишком большое. Сократите или сожмите видео.
`429`	Ограничение частоты или временная нехватка мощности у поставщика. Повторяйте запрос с увеличением задержки.
`503` с кодом `model_not_found`	Сейчас нет доступной мощности. Повторите позже.

Другие ошибки описаны на странице ошибок API.