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

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

Доступность сервиса

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

Для существующего аккаунта с доступом к API нужны три вещи:

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

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

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

Эндпоинты

Стабильный публичный интерфейс описан ниже и в машиночитаемом документе OpenAPI 3.1. Не указанные здесь поля могут передаваться upstream-провайдеру, но автоматически не становятся частью гарантий совместимости SUB&SUB.

POST /v1/chat/completions

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

POST /v1/responses

OpenAI Responses API — новая форма запроса OpenAI (client.responses.create(...)). Работает со всеми моделями каталога: gpt-* изначально, claude-* через тот же мост совместимости, что и чат/дополнения. Использование измеряется одинаково — токены ввода/вывода по уровневой ставке модели.

Готовый к запуску пример Responses:

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

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 тоже работает, если ваш клиент её предпочитает).

Готовый к запуску пример Anthropic Messages:

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

Подсчитайте токены запроса в формате Anthropic перед отправкой. Используйте те же поля x-api-key, anthropic-version, model, system, messages и tools, что и для /v1/messages. Этот endpoint не тарифицируется. Суффикс :online удаляется, но результаты поиска не запрашиваются и не учитываются.

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

Перечислите модели, которые вы действительно можете использовать. Ретранслятор проверяет работоспособность обоих вышестоящих семейств и возвращает 16 проверенных общедоступных идентификаторов — тот же белый список, который используют конечные точки POST, поэтому обнаружение никогда не рекламирует модель, которая будет 400. Если восходящий каталог недоступен, конечная точка возвращает 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-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

Гарантии совместимости

Совместимость с OpenAI не означает, что каждое поле каждой upstream-модели гарантировано на каждом маршруте. Есть три уровня поддержки:

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

Две семьи вверх по течению. 7 моделей OpenAI направляются к общим учетным записям уровня ChatGPT; 9 моделей Claude обслуживаются официальными аккаунтами Anthropic. Ставки за токен зависят от уровня (см. Цены) — для обоих работает один и тот же ключ.

OpenAI

Anthropic

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

Каждая приведенная выше модель OpenAI является моделью рассуждения: серверная часть может потратить больше или меньше токенов «обдумывания», прежде чем выдать видимый результат. Установите reasoning_effort в теле запроса OpenAI /v1/chat/completions (или reasoning: {"effort": ...} в /v1/responses), чтобы контролировать бюджет. Для Claude используйте собственные поля Anthropic thinking и output_config.effort — см. раздел /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]

Готовый к запуску пример потоковой передачи на Python:

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

Веб-поиск

Добавьте :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-коды в обоих протоколах:

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

Ограничивайте число повторов. Relay использует общую upstream-ёмкость, а запросы генерации не являются идемпотентными.

• Повторять: ответы 429, 502, 503 и явно временные 500. Учитывайте retry-after; иначе используйте экспоненциальную задержку с jitter (например, 1 с, 2 с, 4 с; не более трёх попыток).
• Не повторять без изменений: 400, 401, 402 или 403. Сначала исправьте payload, ключ, баланс или состояние доступа.
• Риск дублирования: каждая успешная генерация — отдельный тарифицируемый запрос. Сейчас SUB&SUB не устраняет дубли POST генерации по idempotency key; храните ID операции в приложении и не повторяйте запрос после полного ответа.
• Streaming: прерванный SSE-поток нельзя продолжить. Повторное подключение запускает новую генерацию и может привести ко второму списанию.

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

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

Тарифы Fable и Ultra соответствуют опубликованным прейскурантным ценам Anthropic. В Sonnet 5 до 31 августа 2026 г. используется начальный тариф Anthropic 2/10 долларов США; его опубликованная стандартная цена после этой даты составляет 3 доллара США/15 долларов США. Цены на другие уровни ниже исходящих благодаря поддержке объединенной подписки.

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

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 и троттлинг на стороне провайдера; если вы в них упрётесь, релей вернёт 429 с заголовком retry-after. Лимиты RPM / TPM на ключ запланированы.

Статус и поддержка

• Авторизованные аккаунты с доступом к API могут видеть состояние провайдеров в разделе Консоль → Состояние сервиса, а объявления — в системных уведомлениях.
• По вопросам аккаунта, оплаты, конфиденциальности или безопасности пишите на [email protected].
• Сообщая об ошибке API, укажите время UTC, endpoint, модель, HTTP-статус и видимый префикс API-ключа. Никогда не отправляйте полный ключ или содержимое промпта, если поддержка явно не запросила отредактированный пример.
• Сервис предоставляется по принципу best effort и без SLA. Условия доступности и возвратов приведены в доступных только на английском Условиях использования, а обработка данных — в Политике конфиденциальности.

Документация проверена 14 июля 2026 года.