Обзор

Эндпоинты

Все эндпоинты находятся под одним базовым URL и обслуживаются по HTTPS.

https://api.shannon-ai.com

Три эндпоинта, производящие текст, обращаются к одним и тем же моделям. Выберите тот, чей формат уже использует ваш код.

Основы запросов

• Тело каждого POST — один JSON-объект, до 32 MiB.
• Поле, которое API не знает, не вызывает ошибки и ни на что не влияет. Запрос, написанный для другого провайдера, не падает из-за лишнего поля.
• На известное поле с неверным типом JSON или на отсутствие обязательного поля отвечают 422. На тело, не являющееся корректным JSON, отвечают 400.
• model — один из id на странице «Модели и цены». Регистр не имеет значения.

Ответ — это JSON или поток server-sent events, если в запросе stream равен true. Каждый эндпоинт отвечает в своем формате. В каждом ответе есть заголовок x-request-id.

Какие проверки проходит запрос

Запрос проверяется в строгом порядке до запуска модели. Отвечает первая непройденная проверка, поэтому 401 пока ничего не говорит о теле.

Структура ошибки

Ошибка — это JSON-объект с error, который содержит type и message. /v1/messages оборачивает его так, как ожидают SDK Anthropic; все остальные пути используют форму OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Читайте type и message. code и param присутствуют только в некоторых ошибках: считайте их необязательными. param всегда равен null.
• После начала потока статус уже 200. Тогда сбой приходит как фрейм ошибки внутри потока.
• Каждый ответ с ошибкой содержит заголовок x-request-id.

Обработка ошибок

Биллинг и баланс

• На аккаунт приходится один баланс, и чат с API делят его: сначала лимит плана на сегодня, затем купленные кредиты. Собственной квоты у API нет.
• Запрос резервирует свой бюджет вывода (max_tokens, по умолчанию 4,096), а затем с него списываются токены, которые он реально использовал, по цене модели.
• Каждый ответ сообщает число токенов в usage. Страница Keys & usage показывает баланс и стоимость каждого запроса.
• Все запросы обслуживаются одинаково. Единственное ограничение частоты запросов — защита от флуда: 120 запросов в минуту на аккаунт. Параллельно отправленные запросы ждут в очереди.

Лимиты и баланс Модели и цены Keys & usage

Поля, зависящие от модели

Все модели принимают один и тот же запрос. Несколько полей действуют только на некоторых моделях; таблица указывает, где именно. Страницы эндпоинтов перечисляют все поля.

Chat Completions

Если вы пришли из OpenAI SDK

• Задайте базовый URL https://api.shannon-ai.com/v1, а в качестве ключа — свой ключ Shannon. Вызовы Chat Completions и Responses тогда работают с SDK как есть.
• model должен быть id Shannon. На имя модели другого провайдера, например gpt-4o, отвечают 400 и unknown model.
• Рассуждения приходят в отдельном поле: reasoning_content рядом с content, в сообщении и в дельтах потока.
• Поток всегда передает usage в последнем чанке вместе с finish_reason.
• Вызов инструмента в потоке приходит одним чанком с полной строкой arguments.
• В ответе один вариант.
• На пути API OpenAI, которых нет в таблице выше, например /v1/embeddings, отвечают 404.

Если вы пришли из Anthropic SDK

• Задайте базовый URL https://api.shannon-ai.com, без /v1, а в качестве ключа — свой ключ Shannon. SDK отправит его как x-api-key.
• model должен быть id Shannon.
• max_tokens в этом API необязателен. Значение по умолчанию — 4,096.
• Ответ содержит блоки контента типов thinking, text и tool_use. Первый блок не всегда текст: выбирайте блоки по type.
• stop_reason равен end_turn или tool_use. Поток модели Shannon может также закончиться с max_tokens.
• anthropic-version и anthropic-beta принимаются, поэтому SDK работает без изменений. Запросу они не нужны.
• Ошибки на /v1/messages имеют форму Anthropic: {"type": "error", "error": {…}}.

Инструменты для кодинга, работающие с этими форматами, настраиваются так же: базовый URL, ключ и id Shannon в качестве модели. CLI-инструменты для кодинга