Формат 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. Стовпець Застосовують називає моделі, на яких поле змінює відповідь. Хостовані open-weight моделі — це дванадцять 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 | Інструкції для моделі: рядок або масив текстових блоків. Див. нижче «Системний промпт». | Хостовані open-weight моделі, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Верхня межа відповіді в токенах. Необов'язкове на цьому ендпоінті; Anthropic SDK завжди його надсилає. Значення поза межами від 1 до 65,536 зводиться до цього діапазону. Це також сума, яку резервують на вашому балансі, поки виконується запит. | Хостовані open-weight моделі, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true надсилає відповідь як server-sent events. Див. нижче «Стрімінг». | Усі моделі |
temperature | number | Температура семплювання. На хостованих open-weight моделях значення утримуються між 0 і 2. | Хостовані open-weight моделі, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Nucleus-семплювання. | Хостовані open-weight моделі | |
stop_sequences | array | До 4 рядків. Відповідь закінчується перед першим із тих, що з'явилися. stop_reason залишається end_turn. | Хостовані open-weight моделі | |
tools | array | Інструменти, які модель може викликати, кожен як {"name", "description", "input_schema"}. Див. нижче «Інструменти». | Усі моделі | |
tool_choice | object | {"type": "auto"} дозволяє моделі вирішувати, {"type": "any"} змушує її викликати інструмент, {"type": "tool", "name": "…"} змушує викликати саме цей інструмент. | Хостовані open-weight моделі | |
thinking | object | Скільки модель міркує перед відповіддю. Див. нижче «Міркування». | Хостовані open-weight моделі | |
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 на блоках приймаються, щоб наявний клієнтський код працював без змін. Вони не змінюють відповідь; кешування запитів на хостованих open-weight моделях автоматичне.
JSON-відповідь за схемою запитується через response_format у Chat Completions і через text.format у Responses. Структуровані відповіді
Запит із системним промптом і міркуваннями
Цей запит надсилає системний промпт, бюджет міркувань, температуру та послідовність зупинки. Він використовує хостовану open-weight модель, яка застосовує все це.
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?"}]
}' На хостованих open-weight моделях usage повідомляє токени, прочитані з кешу запитів, окремо від решти вхідних токенів.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} Системний промпт
system — це рядок або масив текстових блоків у вигляді [{"type": "text", "text": "…"}]. Тексти блоків з'єднуються розривом рядка.
Його застосовують хостовані open-weight моделі, 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 і хостовані open-weight моделі, що підтримують вхідні зображення |
{"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. Розміри та ліміти описані на окремій сторінці. Зображення та файли
Міркування
Хостовані open-weight моделі зіставляють 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"} | Модель повинна викликати один з інструментів. | Хостовані open-weight моделі |
{"type": "tool", "name": "…"} | Модель повинна викликати названий інструмент. | Хостовані open-weight моделі |
Читаються лише інструменти з 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. | Хостовані open-weight моделі |
Блоки відповіді
| Блок | Опис |
|---|---|
{"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 секунд. |
| Хостовані open-weight моделі | Рядок-коментар : 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 | Зображення надіслано до хостованої open-weight моделі без підтримки вхідних зображень. |
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}: кількість вхідних токенів, яка буде стягнута за запит. Підрахунок працює для хостованих open-weight моделей, він безкоштовний і не враховується захистом від флуду.
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} Підрахунок має окрему сторінку з текстовим ендпоінтом і лімітами. Підрахунок токенів