apiToken.saleДокументация

Подключение моделей

Один API‑ключ, один endpoint, все доступные модели — нативные протоколы Anthropic, OpenAI и Gemini плюс OpenAI‑совместимый API для любого клиента. AI‑агент сам настроит и проверит подключение.

Для вашего AI‑агента

Прочитай https://apitoken.sale/md/connect и следуй инструкциям, чтобы подключить этот проект к apiToken.sale.

Помощь с подключением

IDE, SDK, endpoint, модели и ошибки запросов.

TelegramAI 24/7 · человек при необходимости
02

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

Подключите apiToken.sale к coding agent, который читает, изменяет и запускает ваш проект. Выберите стек — точная инструкция появится ниже.

Интеграции

Подключите coding agent

Выберите провайдера, coding agent и операционную систему — инструкция обновится сразу.

Провайдер
Операционная система
Coding agent

Claude Code · Claude Fable 5.1

Нативный coding agent Claude через Anthropic Messages API.

  • Claude
  • Claude Code
  • macOS / Linux · zsh · bash
  • Claude Fable 5.1
Endpointhttps://router.apitoken.sale
  1. Запустите установку одной командой

    Установка спросит провайдера и ключ, получит все модели провайдера, создаст приватный launcher и уберёт конфликтующую переменную авторизации.

    Терминал
    curl -fsSL https://apitoken.sale/setup/connect.sh | bash
  2. Запустите Claude Code

    Явный model flag не даст подхватить модель из старого логина или настроек проекта.

    Запуск
    "$HOME/.local/bin/apitoken-claude-code" --model claude-fable-5-1
  3. Проверьте внутри Claude Code

    В статусе должны быть apiToken.sale как Anthropic base URL и ANTHROPIC_API_KEY как источник ключа.

    В Claude Code
    /statusReply with exactly: connected
03

Один endpoint, все протоколы

router.apitoken.sale — единая точка входа для всех провайдеров. Coding‑агенты и официальные SDK получают нативные API байт‑в‑байт; любой OpenAI‑совместимый клиент работает со всеми моделями каталога через один универсальный маршрут. Тот же ключ sk‑pool и тот же предоплаченный баланс.

Base URLhttps://router.apitoken.sale

Нативные API

Протоколы провайдеров байт‑в‑байт — для coding‑агентов и официальных SDK, которым нужна полная точность: thinking, tool use, кеширование промптов, beta‑возможности.

  • POST/v1/messagesAnthropic
  • POST/v1/responsesOpenAI
  • POST/v1beta/models/{model}:generateContentGemini

OpenAI-совместимый

Один универсальный маршрут для всех моделей каталога — Claude, GPT и Gemini — из любого OpenAI‑совместимого клиента или SDK. Неподдерживаемые параметры fail-closed с понятным 400.

  • POST/v1/chat/completionsЛюбая модель каталога

Единый каталог

Все доступные модели с namespaced ID — anthropic/*, openai/*, google/*, kimi/*. Обычные нативные ID продолжают работать, пока они однозначны.

  • GET/v1/modelsЛюбая модель каталога

Уже подключены? Per-provider endpoint'ы api.apitoken.sale, openai.api.apitoken.sale/v1 и gemini.api.apitoken.sale полностью поддерживаются с тем же ключом и балансом — единый router рекомендован для новых интеграций.

Claude · Native API · cURL

Anthropic Messages API на едином endpoint — протокол байт-в-байт, ключ sk-pool в x-api-key. SDK добавляют anthropic-version автоматически.

  • Claude
  • x-api-key · anthropic-version
Endpointhttps://router.apitoken.sale
  1. Сохраните ключ в окружении

    Держите ключ на сервере: переменная окружения или менеджер секретов, не браузерный bundle. В Windows PowerShell используйте $env:APITOKEN_API_KEY.

    Терминал
    export APITOKEN_API_KEY="sk-pool-•••"
  2. Отправьте первый запрос

    Все доступные модели Claude отвечают на этом маршруте. Актуальный список получайте через GET /v1/models на том же endpoint, а не зашивайте ID в код.

    HTTP
    curl https://router.apitoken.sale/v1/messages \  -H "x-api-key: $APITOKEN_API_KEY" \  -H "anthropic-version: 2023-06-01" \  -H "Content-Type: application/json" \  -d {    "model": "claude-fable-5-1",    "max_tokens": 1024,    "messages": [{"role": "user", "content": "Reply with exactly: connected"}]  }
  3. Считайте баланс и расход

    Тот же ключ читает свой аккаунт: GET https://router.apitoken.sale/usage возвращает живой баланс и расход за любое окно — from и to в RFC3339 UTC (to не включается), group_by — одно из model, provider, day, day,provider, day,model, api_key. По умолчанию — последние 30 дней в разрезе моделей. Один отчёт покрывает всех провайдеров каталога. cost — что списано с вас, list_cost — прайс провайдера за тот же трафик; оба дублируются точной целой строкой *_nano — читайте деньги как строку, не как float. Окно не длиннее 366 дней. GET https://router.apitoken.sale/balance отдаёт только баланс.

    HTTP
    curl -sG "https://router.apitoken.sale/usage" \  -H "x-api-key: $APITOKEN_API_KEY" \  --data-urlencode "from=2026-08-01T00:00:00Z" \  --data-urlencode "to=2026-09-01T00:00:00Z" \  --data-urlencode "group_by=model"
Один ключ sk-pool работает на всех маршрутах единого endpoint. Не включайте его в клиентский код.Получить API‑ключ
04

API баланса и расхода

Тот же ключ, который тратит деньги, читает, на что они ушли. Один маршрут отдаёт живой баланс и точный расход за любое окно по всем провайдерам — без личного кабинета и без второго ключа.

ПараметрЧто задаёт
fromНачало окна, включительно. RFC3339 UTC — 2026-08-01T00:00:00Z, явный числовой offset или голая дата 2026-08-01. По умолчанию — to минус 30 дней.
toКонец окна, **не включается**. Те же формы. По умолчанию — «сейчас»; будущее значение подрезается до «сейчас».
group_bymodel (по умолчанию), provider, day, day,provider, day,model или api_key. Порядок в списке не важен, а model,provider — просто псевдоним model: строка модели и так называет своего провайдера.

Один запрос

Передайте свой ключ sk-pool- в x-api-key (или как Authorization: Bearer). Маршрут обслуживают все точки входа.

HTTP · Request
curl -sG "https://router.apitoken.sale/usage" \  -H "x-api-key: $APITOKEN_API_KEY" \  --data-urlencode "from=2026-08-01T00:00:00Z" \  --data-urlencode "to=2026-09-01T00:00:00Z" \  --data-urlencode "group_by=model"

Ответ

В ответе эхом возвращается ровно то окно, по которому посчитан отчёт, затем живой баланс, итоги и по строке на группу.

JSON · Response
{  "account": "acct_…",  "from": "2026-08-01T00:00:00Z",  "to": "2026-09-01T00:00:00Z",  "group_by": "model",  "balance": {    "balance": "$12.345678",    "balance_nano": 12345678000,    "reserved_nano": 0,    "spent": "$3.210000",    "status": "active"  },  "totals": {    "requests": 1804,    "cost": "$3.210000",    "cost_nano": "3210000000",    "list_cost": "$6.420000",    "input_tokens": 9000000,    "output_tokens": 250000,    "cache_read_tokens": 4100000  },  "data": [    {      "provider": "anthropic",      "model": "claude-opus-4-8",      "requests": 1200,      "cost": "$2.100000",      "cost_nano": "2100000000",      "list_cost": "$4.200000",      "input_tokens": 7000000,      "output_tokens": 180000    }  ]}

Две цены, обе точные. cost — что списано с вас; list_cost — прайс провайдера за тот же трафик, разница и есть ваша скидка. Обе дублируются целой строкой *_nano. Читайте деньги как строку, никогда как float.

Только явный UTC. Локальное время без offset отклоняется: догадка о зоне молча сдвинула бы границы денежного отчёта. Окно должно быть положительным и не длиннее 366 дней, иначе придёт 400 в конверте ошибок протокола хоста (Anthropic, OpenAI или Google этого хоста), с причиной в error.message.

Разрезы сходятся. Любой разрез одного окна даёт тот же итог: все они читаются из одного согласованного снимка. Токены есть в разрезах model, provider и day,model; простые дневные разрезы несут деньги и число запросов. Разрез day,model — расход по каждой модели по дням — ограничен 92 днями и за этой границей отвечает 400, а не молча теряет строки. Ключи маскируются. GET /balance отдаёт только баланс.

05

Модели и цены

Все провайдеры, все доступные модели и точные ставки за 1M токенов — официальная цена против той, что платите вы с единой скидкой 50%.

Claude · Anthropic Messages API

router.apitoken.salePOST /v1/messages
x-api-key
МодельКонтекстМакс. выводВводКеш. вводЗапись в кешВывод
Claude Fable 5.1Новаяclaude-fable-5-11M128K$5$10$0.125$0.25$6.25$12.5$25$50
Claude Opus 5claude-opus-51M128K$2.5$5$0.25$0.5$3.125$6.25$12.5$25
Claude Fable 5claude-fable-51M128K$5$10$0.5$1$6.25$12.5$25$50
Claude Opus 4.8claude-opus-4-81M128K$2.5$5$0.25$0.5$3.125$6.25$12.5$25
Claude Opus 4.7claude-opus-4-71M128K$2.5$5$0.25$0.5$3.125$6.25$12.5$25
Claude Sonnet 5claude-sonnet-51M128K$1$2$0.1$0.2$1.25$2.5$5$10
Claude Sonnet 4.6claude-sonnet-4-6200K128K$1.5$3$0.15$0.3$1.875$3.75$7.5$15
Claude Haiku 4.5claude-haiku-4-5200K64K$0.5$1$0.05$0.1$0.625$1.25$2.5$5
Чтение из кеша тарифицируется по ставке кешированного ввода (10% от ввода). Запись: 1,25× ввода при TTL 5 минут, 2× при TTL 1 час — заголовок anthropic-beta: extended-cache-ttl-2025-04-11 передайте самостоятельно.

GPT · OpenAI Responses API

router.apitoken.salePOST /v1/responses · POST /v1/chat/completions
Authorization: Bearer
МодельКонтекстМакс. выводВводКеш. вводЗапись в кешВывод
GPT-6 AstraНоваяgpt-6-astra872K128K$5$10$0.5$1$6.25$12.5$25$50
GPT-5.6 Solgpt-5.6-sol1.05M128K$2$4$0.2$0.4$2.5$5$10$20
GPT-5.6 Terragpt-5.6-terra1.05M128K$1$2$0.1$0.2$1.25$2.5$6$12
GPT-5.6 Lunagpt-5.6-luna1.05M128K$0.1$0.2$0.01$0.02$0.125$0.25$0.6$1.2
GPT-5.5gpt-5.51.05M128K$2.5$5$0.25$0.5$2.5$5$15$30
GPT-5.4gpt-5.41.05M128K$1.25$2.5$0.125$0.25$1.25$2.5$7.5$15
GPT Image 2gpt-image-2per request1 image$2.5$5$0.625$1.25$0$0$15$30
GPT Image 2.5 Flaregpt-image-2.5-flareper request1 image$2.5$5$0.625$1.25$0$0$15$30
GPT Image 2.5 Sunburstgpt-image-2.5-sunburstper request1 image$2.5$5$0.625$1.25$0$0$15$30
GPT-6 Astra — новейшая модель GPT: максимум 872K контекста и 128K вывода. Кеширование автоматическое — повторяющиеся префиксы тарифицируются по ставке кешированного ввода, ничего включать не нужно. gpt-5.6 — алиас gpt-5.6-sol.

Gemini · Google Gemini API

router.apitoken.salePOST /v1beta/models/{model}:generateContent
x-goog-api-key
МодельКонтекстМакс. выводВводКеш. вводЗапись в кешВывод
Gemini 3.8 FlashНоваяgemini-3.8-flash1M64K$0.375$0.75$0.0375$0.075$1.875$3.75
Gemini 3.7 Flashgemini-3.7-flash1M64K$0.375$0.75$0.0375$0.075$1.875$3.75
Gemini 3.6 Flashgemini-3.6-flash1M64K$0.375$0.75$0.0375$0.075$1.875$3.75
Gemini 3.5 Flashgemini-3.5-flash1M64K$0.75$1.5$0.075$0.15$4.5$9
Gemini 3 Flash Previewgemini-3-flash-preview1M64K$0.25$0.5$0.025$0.05$1.5$3
Gemini 3.1 Pro Previewgemini-3.1-pro-preview1M64K$1$2$0.1$0.2$6$12
Gemini 3.1 Flash-Litegemini-3.1-flash-lite1M64K$0.125$0.25$0.0125$0.025$0.75$1.5
Gemini 2.5 Flashgemini-2.5-flash1M64K$0.15$0.3$0.015$0.03$1.25$2.5
Gemini 2.5 Flash-Litegemini-2.5-flash-lite1M64K$0.05$0.1$0.005$0.01$0.2$0.4
Кешированный ввод тарифицируется по ставке кешированного ввода (10% от ввода). Gemini Batch использует тот же стандартный токен-тариф Google и обычную скидку аккаунта: отдельной Batch-скидки и гарантии срока выполнения нет. Batch работает асинхронно, а принятые задания могут оставаться в очереди при временном дефиците мощности. gemini-3.1-pro-preview переключается на long-context ставки свыше 200K входных токенов.

Kimi · Anthropic Messages API

router.apitoken.salePOST /v1/messages
x-api-key
МодельКонтекстМакс. выводВводКеш. вводЗапись в кешВывод
Kimi K3Новаяk31Mnot published$1.5$3$0.15$0.3$1.5$3$7.5$15
Kimi K3 (256K)k3-256k256Knot published$1.5$3$0.15$0.3$1.5$3$7.5$15
Kimi for Codingkimi-for-coding256Knot published$0.475$0.95$0.095$0.19$0.475$0.95$2$4
Kimi for Coding HighSpeedkimi-for-coding-highspeed256Knot published$0.95$1.9$0.19$0.38$0.95$1.9$4$8
Кешированный ввод тарифицируется по ставке кешированного ввода (10% от ввода). Отдельной ставки записи в кеш у Kimi нет — запись это промах и тарифицируется по ставке ввода. k3[1m] — алиас k3 для клиентов, которые так пишут 1M-окно; k3-256k — та же модель и те же ставки с окном 256K.
Пример · Claude Opus 4.82M input × $10 = $20400K output × $50 = $20Официально итого = $40
Вы платите$20
Пополнение на $100 даёт $200 официального использования API на любой модели — каждый доллар конвертируется по той же ставке.
  • Ставки указаны за 1M токенов; списание идёт за фактические токены по официальным ставкам, затем вычитается единая скидка 50%.
  • Токены размышлений (thinking/reasoning) тарифицируются как вывод у обоих провайдеров.
  • GPT-запросы свыше 272K входных токенов тарифицируются по официальным ставкам длинного контекста: 2× ввод и 1,5× вывод на весь запрос.
  • Ставки Gemini соответствуют официальному стандартному платному тарифу Google.
  • Актуальный список доступных моделей — всегда в GET /v1/models на едином endpoint: один агрегированный каталог для всех провайдеров.
06

Gemini Batch API

Запускайте множество независимых запросов Gemini асинхронно, опрашивайте одну durable operation и получайте каждый ответ модели или ошибку отдельного item. Один нативный API работает через unified router и прямой Gemini endpoint.

Используйте рекомендуемый https://router.apitoken.sale или прямой https://gemini.api.apitoken.sale. Меняется только hostname: пути, тела и авторизация x-goog-api-key одинаковы. Храните ключ только на сервере.

Endpoints

МетодПутьНазначение
POST/v1beta/models/{model}:batchGenerateContentСоздать асинхронную operation
GET/v1beta/batches/{id}Проверить состояние и получить результаты
GET/v1beta/batches?pageSize={n}&pageToken={token}Список операций этого аккаунта
POST/v1beta/batches/{id}:cancelЗапросить отмену; отправленные items могут завершиться
DELETE/v1beta/batches/{id}Удалить завершённую операцию
POST/upload/v1beta/filesНачать или продолжить resumable-загрузку JSONL
GET/v1beta/filesСписок account-scoped файлов шлюза
GET/v1beta/files/{id}Получить метаданные файла
GET/v1beta/files/{id}:downloadПотоково или диапазоном скачать активный файл
DELETE/v1beta/files/{id}Удалить файл без активных ссылок

1. Создайте inline Batch

Сохраните возвращённое name (batches/batch-…). Idempotency-Key необязателен, но рекомендуется: точный replay вернёт ту же operation, а другое тело с тем же ключом даст 409. Без заголовка каждый POST создаёт новое задание.

Bash · curl
export APITOKEN_API_KEY="sk-pool-…"export GEMINI_BASE="https://router.apitoken.sale"# Direct alternative:# export GEMINI_BASE="https://gemini.api.apitoken.sale"OPERATION=$(curl -fsS   "$GEMINI_BASE/v1beta/models/gemini-3.6-flash:batchGenerateContent"   -H "x-goog-api-key: $APITOKEN_API_KEY"   -H "content-type: application/json"   -H "Idempotency-Key: product-summary-2026-09-01"   -d '{    "batch": {      "displayName": "Product summaries",      "inputConfig": {        "requests": {          "requests": [            {"request":{"contents":[{"role":"user","parts":[{"text":"Summarize product A."}]}]},"metadata":{"key":"product-a"}},            {"request":{"contents":[{"role":"user","parts":[{"text":"Summarize product B."}]}]},"metadata":{"key":"product-b"}}          ]        }      }    }  }')BATCH_NAME=$(printf '%s' "$OPERATION" | jq -r .name)echo "$BATCH_NAME"

2. Опрашивайте и читайте каждый item

Опрашивайте с задержкой до done=true. Затем проверьте state, строковые batchStats и каждый элемент inlinedResponses. В элементе есть либо response, либо error; terminal job может содержать ошибки отдельных items.

Bash · poll
while :; do  OPERATION=$(curl -fsS     "$GEMINI_BASE/v1beta/$BATCH_NAME"     -H "x-goog-api-key: $APITOKEN_API_KEY")  [ "$(printf '%s' "$OPERATION" | jq -r .done)" = "true" ] && break  sleep 5done# Official nested inline results: each entry contains either .response or .error.printf '%s' "$OPERATION" | jq '.response.inlinedResponses.inlinedResponses[]'

3. Разберите terminal operation

Счётчики приходят десятичными строками — разбирайте их через BigInt. Само по себе done=true не означает успех каждого item.

TypeScript
const operation = await response.json();if (!operation.done) {  console.log("Still running:", operation.metadata?.state);  return;}if (operation.error) throw new Error(operation.error.message);const stats = operation.metadata?.batchStats ?? {};const total = BigInt(stats.requestCount ?? "0");const failed = BigInt(stats.failedRequestCount ?? "0");for (const [index, item] of     (operation.response?.inlinedResponses?.inlinedResponses ?? []).entries()) {  if (item.error) {    console.error(index, item.error.status, item.error.message);  } else {    console.log(index, item.response?.candidates ?? []);  }}

4. List, cancel и delete ресурсов

Используйте полное имя batches/{id} из create. Для уже отправленных items отмена работает best effort; удаляйте Batch только после terminal state. Файлы account-scoped и не удаляются, пока на них ссылается активное задание.

Bash · lifecycle
# List Batches (save nextPageToken for the next page).curl -fsS "$GEMINI_BASE/v1beta/batches?pageSize=20"   -H "x-goog-api-key: $APITOKEN_API_KEY"# Read one operation. BATCH_NAME is the complete batches/{id} from create.curl -fsS "$GEMINI_BASE/v1beta/$BATCH_NAME"   -H "x-goog-api-key: $APITOKEN_API_KEY"# Request cancellation. Items already dispatched may still finish.curl -fsS -X POST "$GEMINI_BASE/v1beta/$BATCH_NAME:cancel"   -H "x-goog-api-key: $APITOKEN_API_KEY"   -H "content-type: application/json" -d '{}'# Delete only after the operation is terminal.curl -fsS -X DELETE "$GEMINI_BASE/v1beta/$BATCH_NAME"   -H "x-goog-api-key: $APITOKEN_API_KEY"# Files list supports pageSize, but currently has no pageToken.curl -fsS "$GEMINI_BASE/v1beta/files?pageSize=20"   -H "x-goog-api-key: $APITOKEN_API_KEY"FILE_ID="file-…" # ID without the files/ prefixcurl -fsS "$GEMINI_BASE/v1beta/files/$FILE_ID"   -H "x-goog-api-key: $APITOKEN_API_KEY"# Public download supports active files up to 20 MiB.curl -fsS "$GEMINI_BASE/v1beta/files/$FILE_ID:download"   -H "x-goog-api-key: $APITOKEN_API_KEY" -o downloaded.bin# Deletion fails while a live Batch references the file.curl -fsS -X DELETE "$GEMINI_BASE/v1beta/files/$FILE_ID"   -H "x-goog-api-key: $APITOKEN_API_KEY"

Большой ввод через JSONL

Каждая непустая строка — отдельный JSON object с correlation key и объектом request. Не оборачивайте строки в массив. Пустые строки и CRLF допустимы. Загрузите файл в этот шлюз и передайте возвращённое files/{id} в inputConfig.fileName.

Формат входного JSONL

Для file input поле key обязательно и может занимать до 512 байт. Результаты сохраняют порядок ввода; храните key в своей карте input→output.

JSONL
{"key":"product-a","request":{"contents":[{"role":"user","parts":[{"text":"Summarize product A."}]}]}}{"key":"product-b","request":{"contents":[{"role":"user","parts":[{"text":"Summarize product B."}]}]}}

Resumable upload и create через fileName

Возвращаемый upload URL относительный. Нефинальные chunks имеют ровно 8 МиБ и точные offsets; после неоднозначного ответа выполните command=query перед повтором. Полный output скачивается потоком, а Range даёт возобновляемые ограниченные чтения.

Bash · upload
FILE=batch-input.jsonlSIZE=$(wc -c < "$FILE" | tr -d ' ')# 1. Start a resumable upload.curl -fsS -D upload.headers -o /dev/null   -X POST "$GEMINI_BASE/upload/v1beta/files"   -H "x-goog-api-key: $APITOKEN_API_KEY"   -H "x-goog-upload-protocol: resumable"   -H "x-goog-upload-command: start"   -H "x-goog-upload-file-name: batch-input.jsonl"   -H "x-goog-upload-header-content-type: application/jsonl"   -H "x-goog-upload-header-content-length: $SIZE"UPLOAD_PATH=$(awk 'BEGIN{IGNORECASE=1} /^x-goog-upload-url:/{gsub("\r",""); print $2}' upload.headers)# 2. Upload and finalize this file in one chunk (up to 8 MiB).# For larger files, repeat command=upload with exact 8 MiB chunks and# increasing x-goog-upload-offset, then use "upload, finalize" on the last chunk.curl -fsS "$GEMINI_BASE$UPLOAD_PATH"   -X POST   -H "x-goog-api-key: $APITOKEN_API_KEY"   -H "x-goog-upload-protocol: resumable"   -H "x-goog-upload-command: upload, finalize"   -H "x-goog-upload-offset: 0"   -H "content-length: $SIZE"   --data-binary "@$FILE" > uploaded-file.jsonFILE_NAME=$(jq -r .file.name uploaded-file.json)# 3. Use the returned files/{id} as Batch JSONL input.curl -fsS   "$GEMINI_BASE/v1beta/models/gemini-3.6-flash:batchGenerateContent"   -H "x-goog-api-key: $APITOKEN_API_KEY"   -H "content-type: application/json"   -d "{"batch":{"displayName":"JSONL summaries","inputConfig":{"fileName":"$FILE_NAME"}}}"

Лимиты и хранение

ЛимитЗначение
Тело inline create20 МиБ
Items в одном BatchНет потолка. Один клиентский job остаётся одним job.
Незавершённых Batches на аккаунт100
Одна строка JSONL20 МиБ
Один upload chunk8 МиБ
TTL загруженного файла48 часов
Максимальное время в очереди48 часов
Хранение terminal result42 дня
Размер страницы list1–1 000

На аккаунте должен быть положительный предоплаченный баланс. Принятое задание сохраняется и может оставаться в очереди при временном дефиците мощности. Ultra использует до 20 durable Batch slots, остальные планы — 2; старты на одной подписке разделены случайным durable интервалом 2–5 секунд. Действуют обычные цены Gemini и скидка аккаунта; отдельной Batch-скидки и гарантии срока нет.

Отличия от официального Google Batch

ОбластьПоведение apiToken.sale
ExecutionАсинхронные непотоковые задания шлюза; это не Vertex AI Batch, GCS или BigQuery.
PricingОбычный тариф Gemini и скидка аккаунта. Отдельной Batch-скидки и гарантии срока нет.
Inline schemaПринимаются официальная обёртка InlinedRequests (requests.requests[]) и сырой массив. Алиасы proto-JSON snake_case принимаются.
FilesФайлы принадлежат аккаунту apiToken.sale, а не Google Cloud project. Чужие Google-файлы недоступны.
fileDataСинхронный fileData — 400 INVALID_ARGUMENT / FILE_URI_UNSUPPORTED: официальный Gemini API поле принимает; отправьте inlineData. Batch JSONL использует inputConfig.fileName.
File outputЗадания с файловым вводом публикуют упорядоченный зашифрованный JSONL responsesFile до done=true; inline jobs сохраняют inlinedResponses.
TimestampsВремена operation — RFC 3339 UTC (google-datetime).
UnsupportedНет webhooks, embedding/update Batch, image-output моделей, Google IAM и Vertex resource semantics.

Ошибки Batch

СтатусЧто делать
400 INVALID_ARGUMENTИсправьте JSON, выбор input form, JSONL, модель или поле. Не повторяйте неизменённый запрос.
400 INVALID_ARGUMENT / API_KEY_INVALIDОтсутствующий, неверный или отозванный ключ: линия Gemini отвечает 400 с причиной API_KEY_INVALID в `error.details`, как официальный Google API (не 401). Передайте активный sk-pool ключ в x-goog-api-key и не повторяйте запрос с отозванным ключом.
402 FAILED_PRECONDITIONДля paid Batch create нужен положительный предоплаченный баланс. HTTP 402 FAILED_PRECONDITION — деньги аккаунта движка, не RESOURCE_EXHAUSTED и не 429.
404 NOT_FOUNDНеверный, удалённый, истёкший или чужой job/file; проверьте полное имя и аккаунт.
409 ABORTEDIdempotency key использован с другим телом либо не совпал upload offset.
FAILED_PRECONDITIONДождитесь/отмените Batch перед удалением; активная ссылка Batch также блокирует удаление файла.
429 / 503Временный лимит мощности, квоты или authority. Используйте ограниченный exponential backoff с jitter.
07

Как отправлять файлы в Gemini

Синхронный generateContent требует inline-байты: files/… из любого Google-проекта невидим этому шлюзу. Для большого Gemini Batch input загрузите account-scoped JSONL в этот шлюз и передайте возвращённое имя как inputConfig.fileName. Загруженные файлы живут 48 часов.

Тип данныхПоддержкаКак отправлять
Изображения (PNG, JPEG, WebP)Даinline_data с mime_type и base64. Примерно до 23 МБ исходного файла.
PDF-документыДаinline_data с application/pdf. Модель читает текст внутри документа.
Текстовые файлыДаinline_data с text/plain — или просто вставьте текст в text.
АудиоВсе текстовые моделиЛюбая текстовая модель, inline audio/wav.
Files API (file_uri / fileData)Одна модельТолько JSONL input для Batch: загрузите файл в этот шлюз и передайте files/{id} как inputConfig.fileName. Встраивание через fileData не поддерживается. В синхронном generateContent передавайте байты inline.
cachedContentНетНедоступно. Передавайте содержимое inline.

Запрос с файлом

Загрузка и ссылка на файл заменяются одним запросом. Base64 добавляет примерно треть объёма, поэтому в наш лимит тела 32 МБ укладывается исходный файл примерно до 23 МБ.

JSON · Request
{  "contents": [    {      "role": "user",      "parts": [        { "text": "Describe this file" },        { "inline_data": { "mime_type": "image/png", "data": "<base64>" } }      ]    }  ]}

Когда мы отказываем. Данные, которые шлюз принять не может, отклоняются до отправки провайдеру — 400 INVALID_ARGUMENT со стабильной причиной ErrorInfo: FILE_URI_UNSUPPORTED, CACHED_CONTENT_UNSUPPORTED, AUDIO_INPUT_UNSUPPORTED. Сообщение следует шаблону {field} cannot be honoured on this endpoint. The official Gemini API accepts it; {workaround}. FILE_URI_UNSUPPORTED относится к синхронному generateContent и чужим Google-файлам; Batch умеет разрешать только файлы, загруженные в этот шлюз тем же аккаунтом. Такой отказ окончательный: помогает изменение запроса, а не повтор. В каждой ошибке есть заголовок x-request-id — назовите его поддержке, и мы найдём именно ваш запрос.

08

Основные коды ответа

На едином endpoint каждый протокол сохраняет свой формат ошибок: маршруты Anthropic (включая маршрут KIMI на kimi/*) возвращают JSON Anthropic (ограничения шлюза добавляют `error.details.error_code` / `param`), маршруты OpenAI — {"error":{"message","type","param","code"}}, маршрут Gemini — {"error":{"code","message","status","details"}}. Коды 401 и 402 требуют исправить состояние аккаунта; автоматически повторяйте только временные ошибки 429 и 5xx. Полный каталог с точным текстом — /docs/errors.

СтатусЗначениеЧто делать
400Некорректный запрос, unsupported_parameter или documented_limitationИсправьте тело. Если error.code или error.details.error_code — documented_limitation или unsupported_parameter, уберите или перенесите названное поле: официальный API этого протокола его принимает, этот endpoint — нет. Не повторяйте неизменённый запрос.
401API-ключ отсутствует, неверен или отозванПередайте активный ключ sk-pool в x-api-key. Если ключ отозван, создайте новый; повторять запрос с тем же ключом не нужно. На нативной линии Gemini та же ошибка приходит как 400 INVALID_ARGUMENT с причиной `API_KEY_INVALID` в `error.details` — как в официальном Google API; обрабатывайте её так же, как 401.
402Доступного предоплаченного баланса недостаточноПополните аккаунт, убедитесь, что баланс зачислен, и повторите запрос. Ожидание само по себе не устранит 402. Маршруты Anthropic: 402 billing_error. Маршруты OpenAI: 402 insufficient_quota (не 429 — SDK ретраят 429). Нативный Gemini: 402 FAILED_PRECONDITION.
429Лимит запросов или временный дефицит мощности провайдераУчитывайте Retry-After, если он есть; используйте ограниченную экспоненциальную задержку со случайным смещением.
5xxВременная ошибка шлюза или инфраструктуры провайдераПовторите запрос с ограниченной экспоненциальной задержкой. Сохраните ID запроса и не допускайте бесконечных повторов.

Полный каталог ошибок с точным текстом ответа →

09

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

Запросы Claude автоматически получают prompt cache на 5 минут. Можно задать явный брейкпоинт или выбрать TTL 1 час; каждое следующее чтение стоит 10% от цены входных токенов.

Claude — нативный Messages

На /v1/messages непустой брейкпоинт cache_control проходит без изменений. Если поле отсутствует или везде равно null, мы автоматически добавляем верхнеуровневый cache на 5 минут. Для TTL 1 час добавьте ttl: "1h" в брейкпоинт и передайте anthropic-beta: extended-cache-ttl-2025-04-11.

JSON · Request
{  "model": "claude-opus-4-8",  "max_tokens": 1024,  "system": [    {      "type": "text",      "text": "Long stable instructions…",      "cache_control": { "type": "ephemeral" }    }  ],  "messages": [{ "role": "user", "content": "Short varying question" }]}

Claude — OpenAI-совместимый Chat

Для модели anthropic/* на /v1/chat/completions передайте cache_control как верхнеуровневое пользовательское расширение. Если поле отсутствует или равно null, переведённый запрос Claude получает автоматический cache на 5 минут. Для TTL 1 час передайте тот же beta-заголовок. В OpenAI SDK используйте extra_body для расширения и extra_headers для beta. Попадания видны в usage.prompt_tokens_details.cached_tokens.

JSON · Request
{  "model": "anthropic/claude-opus-4-8",  "messages": [    { "role": "system", "content": "Long stable instructions…" },    { "role": "user", "content": "Short varying question" }  ],  "max_completion_tokens": 1024,  "cache_control": { "type": "ephemeral", "ttl": "1h" }}

Claude — OpenAI-совместимый Responses

Для модели anthropic/* на /v1/responses используйте то же верхнеуровневое расширение и beta-заголовок. Без поля действует автоматический cache на 5 минут. В OpenAI SDK используйте extra_body и extra_headers. Попадания видны в usage.input_tokens_details.cached_tokens.

JSON · Request
{  "model": "anthropic/claude-opus-4-8",  "instructions": "Long stable instructions…",  "input": "Short varying question",  "max_output_tokens": 1024,  "cache_control": { "type": "ephemeral", "ttl": "1h" }}

GPT — автоматически

Ничего включать не нужно: повторяющиеся префиксы кешируются на стороне сервера. usage.prompt_tokens_details.cached_tokens (Chat Completions) или input_tokens_details.cached_tokens (Responses) автоматически тарифицируются как 10% от цены ввода.

JSON · Response
{  "usage": {    "prompt_tokens": 5120,    "prompt_tokens_details": { "cached_tokens": 4096 },    "completion_tokens": 128  }}
10

Дальше

Всё, на что ссылается эта страница, в одном месте.