Справочник по API

SUB&SUB предоставляет мультипровайдерный релей по адресу https://api.subnsub.com/v1. OpenAI-клиенты обращаются к /v1/chat/completions; Anthropic-клиенты — к /v1/messages. Один и тот же ключ sk-cf-... маршрутизирует оба — выберите модель в теле запроса, и релей сам подберёт upstream.

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

Вам нужны три вещи:

1. Base URL: https://api.subnsub.com/v1 (OpenAI-клиенты) или https://api.subnsub.com (Anthropic-клиенты — SDK сам добавляет /v1/messages)
2. API-ключ: sk-cf-..., выданный в консоли
3. Модель: одна из 21 проверенной модели — например, gpt-5.4-mini или claude-haiku-4.5

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

Каждый запрос должен содержать заголовок Authorization: Bearer sk-cf-.... Ключи выдаются в консоли и хранятся в виде SHA-256-хешей — как только вы покинете экран создания, открытый текст исчезнет навсегда, поэтому сохраните его сразу.

Эндпоинты

POST /v1/chat/completions

Отправьте запрос на завершение чата. Структура запроса совпадает с OpenAI Chat Completions API — OpenAI SDK работают без изменений.

POST /v1/messages

Нативный эндпоинт Anthropic для моделей claude-* — Anthropic SDK (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) работают без изменений с этим путём. Укажите base URL https://api.subnsub.com и аутентифицируйтесь через заголовок x-api-key (форма Authorization-Bearer тоже работает, если ваш клиент её предпочитает).

GET /v1/models

Перечисляет модели, которые вы действительно можете вызывать. Релей объединяет каталоги OpenAI и Anthropic из sub2api и отфильтровывает их до 21 модели, которые мы протестировали end-to-end на текущем пуле аккаунтов — фантомные ID, которые отдают 503 при маршрутизации, или upstream-400 на первом токене, скрыты. Если каждый настроенный upstream недоступен, эндпоинт возвращает 502 models_unreachable, а не вводящий в заблуждение пустой список.

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-4.5", "type": "model", ... },
    { "id": "claude-haiku-4.5",  "type": "model", ... },
    ...
  ]
}

Доступные модели

Два upstream-семейства. 7 моделей OpenAI маршрутизируются на общие аккаунты уровня ChatGPT; 14 моделей Claude — через обратный прокси Kiro на AWS CodeWhisperer. Потокенные ставки зависят от тира (см. Тарифы) — один ключ работает для обоих.

OpenAI

Anthropic

Усилие рассуждения

Каждая из перечисленных выше моделей OpenAI — это модель с рассуждением: бэкенд может потратить больше или меньше токенов «на размышление» перед выдачей видимого ответа. Задайте reasoning_effort в теле запроса OpenAI /v1/chat/completions, чтобы управлять бюджетом. Для Claude используйте нативное поле запроса Anthropic thinking (или выберите вариант модели -thinking) — см. раздел /v1/messages. Модели OpenAI принимают одни и те же пять значений усилия:

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

Стриминг

Задайте "stream": true, чтобы получать Server-Sent Events. Финальный чанк несёт блок usage (мы принудительно передаём upstream stream_options.include_usage, чтобы счётчики токенов всегда выдавались), затем поток закрывает литерал data: [DONE].

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

Веб-поиск

Добавьте :online к любому ID модели, поддерживаемому эндпоинтом, и релей выполнит веб-поиск перед пересылкой модели, добавив результаты в начало диалога, чтобы ответ опирался на свежие данные. Суффикс работает на /v1/chat/completions и /v1/messages (последний по-прежнему требует базу claude-*); никаких специальных полей запроса для поиска не требуется.

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

Как это работает: релей убирает :online, берёт самое последнее сообщение пользователя в качестве запроса (с ограничением в 400 символов), вызывает Tavily для получения до 3 результатов с извлечённым текстом страниц, когда он доступен, плюс необязательную сводку, сгенерированную Tavily, а затем добавляет их в начало того же пользовательского хода в виде чётко выделенного блока <search_results> перед отправкой запроса upstream. У вызова поиска тайм-аут 8 секунд. Результаты намеренно внедряются в роль user — никогда в системный промпт — чтобы недоверенные фрагменты не могли быть повышены до инструкций системного приоритета.

Блок <search_results> выглядит так. Перед ним идёт однострочная инструкция, предписывающая модели рассматривать блок как недоверенные внешние данные и ссылаться на пронумерованные элементы внутри текста:

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

Когда использовать :online

Релей делает один вызов Tavily на запрос и внедряет результаты — это не агентный цикл поиска. Модель не решает выполнить повторный поиск на основе того, что видит, как это делают Perplexity Sonar или инструмент просмотра ChatGPT. Планируйте с учётом этого ограничения:

Сформулируйте последнее сообщение пользователя как самостоятельный поисковый запрос. Поиск выполняется по буквальному тексту вашего самого последнего пользовательского хода (с ограничением в 400 символов), поэтому разговорные уточнения вроде «а как насчёт последней версии?» превращаются в бесполезные запросы без контекста. В многоходовом чате повторно укажите тему, когда добавляете :online — например, «последняя версия Anthropic Python SDK» вместо «последнюю».

Для вопросов, требующих многошагового синтеза (сравнение, глубокое исследование), разбивайте их на несколько ходов и добавляйте :online к каждому. Модель прочитает свежие результаты каждого хода; следующий запрос вы направляете вручную. Учтите, что внедрённый блок <search_results> отправляется только upstream — он не возвращается вашему клиенту и не сохраняется в следующий запрос, поэтому, если более поздний ход зависит от деталей из ранних источников, попросите модель кратко изложить их в видимом ответе. Режим исследования за один проход не поддерживается.

Ошибки

Оболочка зависит от того, какой эндпоинт вы вызвали — релей возвращает ошибки в протоколе, соответствующем SDK вызывающей стороны, а upstream-ошибки передаются дословно.

Пути OpenAI (/v1/chat/completions, /v1/responses, /v1/models) — оболочка OpenAI:

{ "error": { "message": "...", "type": "...", "code": "..." } }

Пути Anthropic (/v1/messages, /v1/messages/count_tokens) — оболочка Anthropic:

{ "type": "error", "error": { "type": "...", "message": "..." } }

Оболочка Anthropic использует другую структуру — нет поля code, а дискриминатор type: "error" находится на верхнем уровне (внутреннее error.type задаёт категорию, например authentication_error, invalid_request_error, permission_error, api_error). Anthropic SDK уже разбирают эту структуру; обработчики ошибок обычного OpenAI SDK — нет, поэтому вызывайте /v1/messages через Anthropic SDK (или используйте чистый HTTP).

Коды статусов — канонические HTTP-коды в обоих протоколах:

Тарифы и оплата

Оплата по факту, тарификация по токенам в микродолларах (1 микро = $0.000001 = 1/10,000 цента), чтобы запросы дешевле цента учитывались точно. Ставки указаны за 1M токенов, по тирам — см. таблицу моделей, чтобы узнать, к какому тиру относится каждая модель.

Ставки тира Ultra совпадают с опубликованным прайс-листом Anthropic на Opus — прямая передача, без маржи. Остальные тиры идут ниже своих upstream-ставок благодаря объединённой подписочной базе.

Токены рассуждения (когда вы задаёте reasoning_effort в OpenAI или используете вариант Claude -thinking) засчитываются как output-токены по ставке тира модели — отдельной наценки за высокое усилие нет, но запрос с глубоким размышлением легко может выдать в 10–50× больше output-токенов, чем запрос без усилия, поэтому счёт в долларах растёт вместе с этим.

Prompt-кэширование Anthropic тарифицируется отдельной строкой: записи в кэш по 1.25×, а чтения из кэша по 0.10× от ставки input соответствующего тира. Так, попадание в кэш для haiku-4.5 стоит 0.20 × 0.10 = $0.02 per 1M tokens, а попадание в кэш для sonnet-4.5 — 0.75 × 0.10 = $0.075 per 1M tokens. Колонки кэша записываются в каждой строке списания, чтобы консоль могла показать разбивку.

Баланс списывается в реальном времени по мере возврата каждого запроса — для стриминговых запросов списание выполняется после прихода чанка [DONE]. Смотрите текущий баланс и списания по каждому запросу на /console#billing.

Лимиты запросов

Сегодня лимитов запросов на ключ нет. Действуют параллелизм пула upstream-аккаунтов и серверный троттлинг OpenAI; если вы в них упрётесь, релей вернёт 429 с заголовком retry-after. Лимиты RPM / TPM на ключ появятся после MVP.