Перейти к содержимому
Формат Anthropic

Формат Anthropic

POST /v1/messages принимает запрос в формате Anthropic Messages и отвечает в том же формате, потоково или целиком. Используйте его с Anthropic SDK и с построенными на нем инструментами, например Claude Code: задайте базовый URL, используйте свой API-ключ Shannon и укажите id модели Shannon.

POST https://api.shannon-ai.com/v1/messages

Направьте Anthropic SDK на базовый URL Shannon. SDK добавляет /v1/messages и отправляет ваш ключ в заголовке x-api-key.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Ответ — это сообщение, у которого content является списком блоков. Находите блоки по их type: если модель рассуждала, первый блок — thinking, а текст идет после него.

200 JSON
{
  "id": "msg_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "type": "message",
  "role": "assistant",
  "model": "shannon-3",
  "content": [
    {
      "type": "thinking",
      "thinking": "The user wants a greeting in one sentence. Keep it short and friendly."
    },
    {
      "type": "text",
      "text": "Hello, it is good to meet you."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46
  }
}

Заголовки

Заголовок Значение Описание
x-api-key YOUR_API_KEY Ваш API-ключ. Вместо него принимается Authorization: Bearer YOUR_API_KEY.
content-type application/json Обязателен.
anthropic-version 2023-06-01 Принимается, не обязателен. Anthropic SDK отправляет 2023-06-01; формат ответа одинаков при любом значении.
anthropic-beta Принимается, не обязателен.
x-request-id Необязателен. Ваш собственный id запроса. Он возвращается в ответе без изменений; без него в ответе будет id из 12 шестнадцатеричных символов.

Поля запроса

Обязательно только messages. В столбце Применяется на указаны модели, на которых поле влияет на ответ. Размещенные модели с открытыми весами — это двенадцать id из списка моделей; семейство Shannon 3 — это shannon-3, shannon-3-pro, shannon-3.1 и shannon-3.1-pro. Модели и цены

Поле Тип По умолчанию Описание Применяется на
model string shannon-1.6-lite Id модели Shannon из списка моделей. Отправляйте его с каждым запросом. Регистр не учитывается. Любое другое имя возвращает 400 unknown model, поэтому инструмент, отправляющий собственные имена моделей, нужно настроить на id Shannon. Все модели
messages array Обязательно. Разговор, начиная с самого старого сообщения, с ролями user и assistant. См. ниже «Сообщения и блоки контента». Все модели
system string | array Инструкции для модели: строка или массив текстовых блоков. См. ниже «Системный промпт». Размещенные модели с открытыми весами, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Верхний предел ответа в токенах. На этом эндпоинте необязательно; Anthropic SDK всегда его отправляет. Значение вне диапазона от 1 до 65,536 приводится к этому диапазону. Это также объем, который резервируется на вашем балансе на время выполнения запроса. Размещенные модели с открытыми весами, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true отправляет ответ в виде server-sent events. См. ниже «Стриминг». Все модели
temperature number Температура сэмплирования. На размещенных моделях с открытыми весами значения ограничиваются диапазоном от 0 до 2. Размещенные модели с открытыми весами, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Ядерное сэмплирование (nucleus sampling). Размещенные модели с открытыми весами
stop_sequences array До 4 строк. Ответ заканчивается перед первой из них, которая встретится. stop_reason остается end_turn. Размещенные модели с открытыми весами
tools array Инструменты, которые модель может вызывать, каждый в виде {"name", "description", "input_schema"}. См. ниже «Инструменты». Все модели
tool_choice object {"type": "auto"} позволяет модели решать самой, {"type": "any"} заставляет вызвать инструмент, {"type": "tool", "name": "…"} заставляет вызвать именно этот инструмент. Размещенные модели с открытыми весами
thinking object Сколько модель рассуждает перед ответом. См. ниже «Размышление». Размещенные модели с открытыми весами
web_search boolean false Дополнение Shannon к формату: true позволяет модели искать в интернете перед ответом. shannon-1.6-*, shannon-2-*, семейство Shannon 3

Без max_tokens значение равно 4,096, а на shannon-coder-1 — 65,536.

Метки metadata, top_k, service_tier и cache_control на блоках принимаются, чтобы существующий клиентский код работал без изменений. Они не меняют ответ; кэширование промптов на размещенных моделях с открытыми весами автоматическое.

JSON-ответ по схеме запрашивается через response_format в Chat Completions и через text.format в Responses. Структурированные ответы

Запрос с системным промптом и размышлением

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

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    max_tokens=4096,
    system="You are a physics teacher. Answer in two sentences.",
    thinking={"type": "enabled", "budget_tokens": 2048},
    temperature=0.3,
    stop_sequences=["\n\n"],
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

for block in message.content:
    if block.type == "thinking":
        print("reasoning:", block.thinking)
    elif block.type == "text":
        print("answer:", block.text)
print(message.usage)

На размещенных моделях с открытыми весами usage показывает токены, прочитанные из кэша промптов, отдельно от остальных входных токенов.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

Системный промпт

system — это строка или массив текстовых блоков вида [{"type": "text", "text": "…"}]. Тексты блоков объединяются через перевод строки.

Его применяют размещенные модели с открытыми весами, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro и shannon-coder-1. С id семейства Shannon 3 помещайте обязательные инструкции в сообщение пользователя.

Сообщения и блоки контента

У сообщения есть role, user или assistant, и content. content — это строка или массив блоков.

Блок Описание Доступно на
{"type": "text", "text": "…"} Текст. Все модели
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Изображение в сообщении user, в виде base64 или по URL. Семейство Shannon 3, shannon-1.6-lite, shannon-1.6-pro и размещенные модели с открытыми весами, поддерживающие ввод изображений
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Документ (PDF, Word, PowerPoint или Excel) в сообщении user, в виде base64 или по URL. Семейство Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} В сообщении assistant: вызов инструмента, который модель сделала в предыдущем ответе. Все модели
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} В сообщении user: результат этого вызова. content — это строка или список текстовых блоков. Все модели

Вы можете отправить content предыдущего ответа обратно как есть: блоки text и tool_use читаются, блоки thinking пропускаются.

На уровнях Shannon изображения и документы читаются из последнего сообщения user. Размеры и лимиты описаны на отдельной странице. Изображения и файлы

Размышление

Размещенные модели с открытыми весами сопоставляют thinking с усилием рассуждения. Без этого поля усилие высокое.

Форма budget_tokens Эффект
{"type": "disabled"} Без рассуждений. В ответе нет блока thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Низкое усилие.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Среднее усилие.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Высокое усилие.

Модель, которая рассуждает, возвращает рассуждения как блок {"type": "thinking", "thinking": "…"} перед текстом. Уровни Shannon, которые рассуждают, тоже отправляют его.

Уровни усилия описаны на отдельной странице. Усилие рассуждения

Инструменты

Инструмент — это функция, которую выполняет ваш код. Опишите каждый через name, description и input_schema. Когда модели нужен инструмент, ответ содержит блок tool_use, а stop_reason равен tool_use.

Определение инструмента в tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

content ответа, который вызывает инструмент:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

Выполните инструмент, затем отправьте запрос снова, добавив в messages вызов и блок tool_result:

messages
[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "content": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
      }
    ]
  }
]

tool_choice

Форма Эффект Применяется на
{"type": "auto"} Модель сама решает, вызывать ли инструмент. Это значение по умолчанию. Все модели
{"type": "any"} Модель обязана вызвать один из инструментов. Размещенные модели с открытыми весами
{"type": "tool", "name": "…"} Модель обязана вызвать указанный инструмент. Размещенные модели с открытыми весами

Читаются только инструменты с input_schema. Веб-поиск не является инструментом на этом эндпоинте: задайте поле web_search.

Цикл вызова инструментов подробно описан на отдельной странице. Вызов функций

Ответ

Поле Тип Описание Отправляет
id string msg_, за которым следуют 32 шестнадцатеричных символа. Все модели
type string Всегда message. Все модели
role string Всегда assistant. Все модели
model string Каноничный id модели, давшей ответ. Все модели
content array Блоки ответа в таком порядке: thinking, если модель рассуждала, text, затем по одному tool_use на каждый вызов инструмента. Все модели
stop_reason string Почему ответ закончился. См. значения ниже. Все модели
usage object input_tokens и output_tokens. Все модели
sources array Только в запросе с web_search: true, поиск которого что-то нашел: результаты, переданные модели, каждый с index, title и url. [1] в ответе — это запись с index 1. В потоке он приходит с событием message_delta. shannon-1.6-*, shannon-2-*, семейство Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens — часть промпта, прочитанная из кэша; input_tokens — остальное. cache_creation_input_tokens всегда равно 0. Размещенные модели с открытыми весами

Блоки ответа

Блок Описание
{"type": "thinking", "thinking": "…"} Рассуждения модели. Поля signature нет.
{"type": "text", "text": "…"} Текст ответа. Он может быть пустым, если ответ является вызовом инструмента.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Вызов инструмента. input — это JSON-объект. Отправьте результат обратно с тем же id.

stop_reason

stop_reason Описание Отправляет
end_turn Модель закончила ответ, либо встретилась одна из ваших stop_sequences. Все модели
tool_use Ответ содержит один или несколько вызовов инструментов. Все модели
max_tokens Ответ был обрезан по лимиту вывода. Семейство Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, в потоках

Стриминг

Установите stream в true, чтобы получать server-sent events. Каждый фрейм содержит строку event: с именем события и строку data: с JSON-объектом, который повторяет имя в type. Потоковые помощники Anthropic SDK читают эти события за вас:

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

with client.messages.stream(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    message = stream.get_final_message()

print()
print(message.stop_reason, message.usage)

События в порядке их поступления:

Событие Данные Когда
message_start message Всегда первое. message содержит id, роль, модель, пустой content и usage, который начинается с нуля.
content_block_start index, content_block Блок открывается. content_block — это пустой блок text или thinking либо блок tool_use с его id и name.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Фрагмент рассуждений, для блока thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Фрагмент ответа, для блока text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Аргументы вызова инструмента, целиком в одной дельте, для блока tool_use.
content_block_stop index Блок с этим index завершен.
message_delta delta {stop_reason, stop_sequence}, usage Конец ответа: delta.stop_reason и usage запроса.
message_stop Всегда последнее.

Блоки нумеруются по index в порядке открытия, и каждый блок завершается до открытия следующего. Читайте каждый блок по его типу, а не по номеру: поток может сначала открыть пустой блок text, затем блок thinking, а ответ передать в более позднем блоке text.

200 text/event-stream
event: message_start
data: {"type":"message_start","message":{"id":"msg_5f0c…","type":"message","role":"assistant","model":"shannon-3","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Three sentences: what it is, how it is framed, why it is used."}}

event: ping
data: {"type": "ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Server-sent events let a server push text over one HTTP reply."}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1190,"output_tokens":84}}

event: message_stop
data: {"type":"message_stop"}

Keep-alive

Отправляет Описание
Семейство Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Событие ping с данными {"type": "ping"} каждые 15 секунд.
Размещенные модели с открытыми весами Строка-комментарий : keepalive каждые 15 секунд, пока модель работает.

Поток, завершившийся сбоем

Сбой после начала потока приходит как событие error с тем же телом, что и ответ с ошибкой: {"type": "error", "error": {"type", "message"}}. Завершающие события message_delta и message_stop все равно следуют. Считайте ответ неудачным и отправьте запрос снова.

Ошибки

Ошибки используют тело ошибки Anthropic: type равно error, а объект error содержит type и message. В таблице перечислено то, что этот эндпоинт возвращает чаще всего. Полный список с указанием, что повторять, находится на отдельной странице. Обработка ошибок

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Статус Тип Сообщение Когда
401 authentication_error Missing authentication
Invalid API key
API-ключ не был отправлен либо ключ неизвестен или отозван.
400 invalid_request_error unknown model: <id> model не является id модели Shannon.
400 invalid_request_error No user message provided Уровни Shannon: в запросе нет пользовательского текста и нет tools.
400 invalid_request_error <id> does not accept image input Изображение было отправлено размещенной модели с открытыми весами, не поддерживающей ввод изображений.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages отсутствует или у поля неверный тип JSON.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens больше, чем остаток вашего баланса.
429 rate_limit_error Too many requests. Retry in <n>s. Защита от флуда: более 120 запросов в минуту с вашего аккаунта.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: вызовы Shannon Coder по вашему плану в текущем 4-часовом окне исчерпаны.
500 server_error The model backend failed to answer. Please retry. Модель не сформировала ответ. Отправьте запрос еще раз.
502 api_error The model backend failed to answer. Please retry. Модель не сформировала ответ. Отправьте запрос еще раз.

Подсчет токенов

POST /v1/messages/count_tokens принимает то же тело, что и запрос сообщения (model, system, messages, tools), и возвращает {"input_tokens": n}: число входных токенов, которое было бы списано за запрос. Подсчет работает для размещенных моделей с открытыми весами, он бесплатный и не учитывается защитой от флуда.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

count = client.messages.count_tokens(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    system="You are a physics teacher. Answer in two sentences.",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(count.input_tokens)

Подсчету посвящена отдельная страница, с текстовым эндпоинтом и лимитами. Подсчет токенов