Формат 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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await client.messages.create({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
for (const block of message.content) {
if (block.type === "text") console.log(block.text);
} curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Say hello in one sentence."}]
}' Ответ — это сообщение, у которого content является списком блоков. Находите блоки по их type: если модель рассуждала, первый блок — thinking, а текст идет после него.
{
"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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await 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 (const block of message.content) {
if (block.type === "thinking") console.log("reasoning:", block.thinking);
if (block.type === "text") console.log("answer:", block.text);
}
console.log(message.usage); curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"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?"}]
}' На размещенных моделях с открытыми весами usage показывает токены, прочитанные из кэша промптов, отдельно от остальных входных токенов.
{
"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:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] content ответа, который вызывает инструмент:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Выполните инструмент, затем отправьте запрос снова, добавив в messages вызов и блок tool_result:
[
{
"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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const stream = client.messages.stream({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Explain server-sent events in three sentences." }],
});
stream.on("text", (text) => process.stdout.write(text));
const message = await stream.finalMessage();
console.log("\n", message.stop_reason, message.usage); curl -N https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Explain server-sent events in three sentences."}]
}' События в порядке их поступления:
| Событие | Данные | Когда |
|---|---|---|
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.
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. В таблице перечислено то, что этот эндпоинт возвращает чаще всего. Полный список с указанием, что повторять, находится на отдельной странице. Обработка ошибок
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Статус | Тип | Сообщение | Когда |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid 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) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const count = await client.messages.countTokens({
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?" }],
});
console.log(count.input_tokens); curl https://api.shannon-ai.com/v1/messages/count_tokens \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"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?"}]
}'
# {"input_tokens": 31} Подсчету посвящена отдельная страница, с текстовым эндпоинтом и лимитами. Подсчет токенов