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 | Инструкции за модела: низ или масив от текстови блокове. Вижте Системен prompt по-долу. | Хоствани 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 върху блокове се приемат, за да работи съществуващият клиентски код без промяна. Те не променят отговора; кеширането на prompt-ове при хостваните open-weight модели е автоматично.
JSON отговор по схема се иска с response_format при Chat Completions и с text.format при Responses. Структурирани изходи
Заявка със системен prompt и мислене
Тази заявка изпраща системен prompt, бюджет за мислене, температура и стоп последователност. Използва хостван 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 отчита токените, прочетени от кеша на prompt-ове, отделно от останалите входни токени.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} Системен prompt
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"
}
}
] Изпълнете инструмента, след това изпратете заявката отново с извикването и блок 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"} | Моделът трябва да извика един от инструментите. | Хоствани 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 е частта от prompt-а, прочетена от кеша; 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"} | Аргументите на извикване на инструмент, пълни в една delta, за блок 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} Броенето има собствена страница, с текстовия ендпоинт и лимитите. Броене на токени