Format Anthropic
POST /v1/messages przyjmuje zapytanie w formacie Anthropic Messages i odpowiada w tym samym formacie, w streamingu lub bez. Używaj go z SDK Anthropic i z narzędziami na nim zbudowanymi, takimi jak Claude Code: ustaw bazowy URL, użyj swojego klucza Shannon API i podaj id modelu Shannon.
POST https://api.shannon-ai.com/v1/messages
Skieruj SDK Anthropic na bazowy URL Shannon. SDK dodaje /v1/messages i wysyła Twój klucz w nagłówku 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."}]
}' Odpowiedzią jest wiadomość, której content to lista bloków. Bloki znajdziesz po ich type: gdy model wnioskował, pierwszym blokiem jest thinking, a tekst następuje po nim.
{
"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
}
} Nagłówki
| Nagłówek | Wartość | Opis |
|---|---|---|
x-api-key | YOUR_API_KEY | Twój klucz API. Zamiast niego akceptowany jest Authorization: Bearer YOUR_API_KEY. |
content-type | application/json | Wymagany. |
anthropic-version | 2023-06-01 | Akceptowany, niewymagany. SDK Anthropic wysyła 2023-06-01; odpowiedź ma ten sam format niezależnie od wartości. |
anthropic-beta | Akceptowany, niewymagany. | |
x-request-id | Opcjonalny. Twój własny id zapytania. Wraca bez zmian w odpowiedzi; bez niego odpowiedź zawiera id z 12 znaków szesnastkowych. |
Pola zapytania
Wymagane jest tylko messages. Kolumna Stosowane przez podaje modele, w których pole zmienia odpowiedź. Hostowane modele open-weight to dwanaście id z listy modeli; rodzina Shannon 3 to shannon-3, shannon-3-pro, shannon-3.1 i shannon-3.1-pro. Modele i ceny
| Pole | Typ | Domyślnie | Opis | Stosowane przez |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Id modelu Shannon z listy modeli. Wysyłaj go z każdym zapytaniem. Wielkość liter nie ma znaczenia. Każda inna nazwa zwraca 400 unknown model, więc narzędzie, które wysyła własne nazwy modeli, trzeba ustawić na id Shannon. | Wszystkie modele |
messages | array | Wymagane. Rozmowa, od najstarszej wiadomości, z rolami user i assistant. Zobacz niżej Wiadomości i bloki treści. | Wszystkie modele | |
system | string | array | Instrukcje dla modelu: ciąg znaków lub tablica bloków tekstowych. Zobacz niżej Prompt systemowy. | Hostowane modele open-weight, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Górny limit odpowiedzi, w tokenach. Opcjonalne w tym endpoincie; SDK Anthropic zawsze je wysyła. Wartość spoza zakresu od 1 do 65,536 jest przesuwana do tego zakresu. To także kwota odłożona z Twojego salda na czas trwania zapytania. | Hostowane modele open-weight, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true wysyła odpowiedź jako server-sent events. Zobacz niżej Streaming. | Wszystkie modele |
temperature | number | Temperatura próbkowania. W hostowanych modelach open-weight wartości są utrzymywane między 0 a 2. | Hostowane modele open-weight, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Próbkowanie jądrowe (nucleus sampling). | Hostowane modele open-weight | |
stop_sequences | array | Do 4 ciągów znaków. Odpowiedź kończy się przed pierwszym z nich, który się pojawi. stop_reason pozostaje end_turn. | Hostowane modele open-weight | |
tools | array | Narzędzia, które model może wywołać, każde jako {"name", "description", "input_schema"}. Zobacz niżej Narzędzia. | Wszystkie modele | |
tool_choice | object | {"type": "auto"} pozwala modelowi zdecydować, {"type": "any"} zmusza go do wywołania narzędzia, {"type": "tool", "name": "…"} zmusza go do wywołania tego narzędzia. | Hostowane modele open-weight | |
thinking | object | Jak dużo model wnioskuje, zanim odpowie. Zobacz niżej Myślenie. | Hostowane modele open-weight | |
web_search | boolean | false | Dodatek Shannon do formatu: true pozwala modelowi przeszukać sieć, zanim odpowie. | shannon-1.6-*, shannon-2-*, rodzina Shannon 3 |
Bez max_tokens wartość wynosi 4,096, a w shannon-coder-1 65,536.
metadata, top_k, service_tier i znaczniki cache_control w blokach są akceptowane, aby istniejący kod klienta działał bez zmian. Nie zmieniają odpowiedzi; prompt caching w hostowanych modelach open-weight jest automatyczny.
Odpowiedź JSON zgodną ze schematem zamawia się przez response_format w Chat Completions i przez text.format w Responses. Ustrukturyzowane odpowiedzi
Zapytanie z promptem systemowym i myśleniem
To zapytanie wysyła prompt systemowy, budżet myślenia, temperaturę i sekwencję stop. Używa hostowanego modelu open-weight, który stosuje je wszystkie.
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?"}]
}' W hostowanych modelach open-weight usage raportuje tokeny odczytane z cache promptów osobno od pozostałych tokenów wejściowych.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} Prompt systemowy
system to ciąg znaków albo tablica bloków tekstowych w postaci [{"type": "text", "text": "…"}]. Teksty bloków są łączone znakiem nowej linii.
Stosują go hostowane modele open-weight, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro i shannon-coder-1. Przy id z rodziny Shannon 3 umieść instrukcje, które muszą obowiązywać, w wiadomości użytkownika.
Wiadomości i bloki treści
Wiadomość ma role, czyli user lub assistant, oraz content. content to ciąg znaków albo tablica bloków.
| Blok | Opis | Dostępne w |
|---|---|---|
{"type": "text", "text": "…"} | Tekst. | Wszystkie modele |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | Obraz w wiadomości user, jako base64 lub przez URL. | Rodzina Shannon 3, shannon-1.6-lite, shannon-1.6-pro oraz hostowane modele open-weight, które obsługują obraz na wejściu |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Dokument (PDF, Word, PowerPoint lub Excel) w wiadomości user, jako base64 lub przez URL. | Rodzina Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | W wiadomości assistant: wywołanie narzędzia, które model wykonał we wcześniejszej odpowiedzi. | Wszystkie modele |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | W wiadomości user: wynik tego wywołania. content to ciąg znaków albo lista bloków tekstowych. | Wszystkie modele |
Możesz odesłać content wcześniejszej odpowiedzi bez zmian: bloki text i tool_use są odczytywane, bloki thinking są pomijane.
W poziomach Shannon obrazy i dokumenty są odczytywane z ostatniej wiadomości user. Rozmiary i limity mają własną stronę. Obrazy i pliki
Myślenie
Hostowane modele open-weight mapują thinking na wysiłek rozumowania. Bez tego pola wysiłek jest wysoki.
| Postać | budget_tokens | Efekt |
|---|---|---|
{"type": "disabled"} | Bez wnioskowania. Odpowiedź nie ma bloku thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Niski wysiłek. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Średni wysiłek. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Wysoki wysiłek. |
Model, który wnioskuje, zwraca swoje wnioskowanie jako blok {"type": "thinking", "thinking": "…"} przed tekstem. Poziomy Shannon, które wnioskują, też go wysyłają.
Poziomy wysiłku opisuje ich własna strona. Wysiłek rozumowania
Narzędzia
Narzędzie to funkcja uruchamiana przez Twój kod. Opisz każde za pomocą name, description i input_schema. Gdy model chce użyć narzędzia, odpowiedź zawiera blok tool_use, a stop_reason ma wartość tool_use.
Definicja narzędzia w tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] content odpowiedzi, która je wywołuje:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Uruchom narzędzie, a potem wyślij zapytanie ponownie, dodając do messages wywołanie i blok 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
| Postać | Efekt | Stosowane przez |
|---|---|---|
{"type": "auto"} | Model sam decyduje, czy wywołać narzędzie. To ustawienie domyślne. | Wszystkie modele |
{"type": "any"} | Model musi wywołać jedno z narzędzi. | Hostowane modele open-weight |
{"type": "tool", "name": "…"} | Model musi wywołać wskazane narzędzie. | Hostowane modele open-weight |
Odczytywane są tylko narzędzia z input_schema. Wyszukiwanie w sieci nie jest w tym endpoincie narzędziem: ustaw pole web_search.
Pętla narzędzi jest w pełni opisana na jej własnej stronie. Wywołanie funkcji
Odpowiedź
| Pole | Typ | Opis | Wysyła |
|---|---|---|---|
id | string | msg_ i 32 znaki szesnastkowe. | Wszystkie modele |
type | string | Zawsze message. | Wszystkie modele |
role | string | Zawsze assistant. | Wszystkie modele |
model | string | Kanoniczny id modelu, który odpowiedział. | Wszystkie modele |
content | array | Bloki odpowiedzi, w tej kolejności: thinking, gdy model wnioskował, text, a potem po jednym tool_use na każde wywołanie narzędzia. | Wszystkie modele |
stop_reason | string | Dlaczego odpowiedź się zakończyła. Zobacz wartości poniżej. | Wszystkie modele |
usage | object | input_tokens i output_tokens. | Wszystkie modele |
sources | array | Tylko w zapytaniu z web_search: true, którego wyszukiwanie coś znalazło: wyniki przekazane modelowi, każdy z index, title i url. [1] w odpowiedzi to wpis z index 1. W streamie przychodzi ze zdarzeniem message_delta. | shannon-1.6-*, shannon-2-*, rodzina Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens to część promptu odczytana z cache; input_tokens to reszta. cache_creation_input_tokens zawsze wynosi 0. | Hostowane modele open-weight |
Bloki odpowiedzi
| Blok | Opis |
|---|---|
{"type": "thinking", "thinking": "…"} | Wnioskowanie modelu. Nie ma pola signature. |
{"type": "text", "text": "…"} | Tekst odpowiedzi. Może być pusty, gdy odpowiedzią jest wywołanie narzędzia. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Wywołanie narzędzia. input jest obiektem JSON. Odeślij wynik z tym samym id. |
stop_reason
| stop_reason | Opis | Wysyła |
|---|---|---|
end_turn | Model zakończył odpowiedź albo pojawiła się jedna z Twoich stop_sequences. | Wszystkie modele |
tool_use | Odpowiedź zawiera jedno lub więcej wywołań narzędzi. | Wszystkie modele |
max_tokens | Odpowiedź została ucięta na limicie wyjścia. | Rodzina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, w strumieniach |
Streaming
Ustaw stream na true, aby otrzymać server-sent events. Każda ramka ma linię event: z nazwą zdarzenia i linię data: z obiektem JSON, który powtarza nazwę w type. Pomocniki strumieni w SDK Anthropic odczytują te zdarzenia za Ciebie:
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."}]
}' Zdarzenia w kolejności, w jakiej przychodzą:
| Zdarzenie | Dane | Kiedy |
|---|---|---|
message_start | message | Zawsze pierwsze. message zawiera id, rolę, model, pusty content i usage zaczynające od zera. |
content_block_start | index, content_block | Blok się otwiera. content_block to pusty blok text lub thinking albo blok tool_use z jego id i name. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | Fragment wnioskowania, dla bloku thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | Fragment odpowiedzi, dla bloku text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Argumenty wywołania narzędzia, kompletne w jednej delcie, dla bloku tool_use. |
content_block_stop | index | Blok o tym index jest kompletny. |
message_delta | delta {stop_reason, stop_sequence}, usage | Koniec odpowiedzi: delta.stop_reason oraz usage zapytania. |
message_stop | Zawsze ostatnie. |
Bloki są numerowane przez index w kolejności otwierania, a jeden blok jest kompletny, zanim otworzy się następny. Czytaj każdy blok według jego typu, nie numeru: strumień może najpierw otworzyć pusty blok text, potem blok thinking, a odpowiedź dostarczyć w późniejszym bloku 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
| Wysyła | Opis |
|---|---|
Rodzina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Zdarzenie ping z danymi {"type": "ping"}, co 15 sekund. |
| Hostowane modele open-weight | Linia komentarza : keepalive, co 15 sekund, gdy model pracuje. |
Strumień, który kończy się błędem
Awaria po rozpoczęciu strumienia to zdarzenie error z taką samą treścią jak odpowiedź z błędem: {"type": "error", "error": {"type", "message"}}. Zdarzenia kończące, message_delta i message_stop, nadal następują. Potraktuj odpowiedź jako nieudaną i wyślij zapytanie ponownie.
Błędy
Błędy używają formatu błędu Anthropic: type ma wartość error, a obiekt error zawiera type i message. Tabela pokazuje, co ten endpoint zwraca najczęściej. Pełna lista, razem z informacją, co ponawiać, ma własną stronę. Obsługa błędów
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Status | Typ | Komunikat | Kiedy |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Nie wysłano klucza API albo klucz jest nieznany lub unieważniony. |
400 | invalid_request_error | unknown model: <id> | model nie jest id modelu Shannon. |
400 | invalid_request_error | No user message provided | Poziomy Shannon: zapytanie nie ma tekstu użytkownika ani tools. |
400 | invalid_request_error | <id> does not accept image input | Obraz wysłano do hostowanego modelu open-weight bez obsługi obrazu na wejściu. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Brakuje messages albo pole ma zły typ JSON. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens jest większe niż to, co zostało z Twojego salda. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Ochrona przed floodem: ponad 120 zapytań w ciągu jednej minuty na Twoim koncie. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: wywołania Shannon Coder w Twoim planie na bieżące 4-godzinne okno zostały wykorzystane. |
500 | server_error | The model backend failed to answer. Please retry. | Model nie wygenerował odpowiedzi. Wyślij zapytanie ponownie. |
502 | api_error | The model backend failed to answer. Please retry. | Model nie wygenerował odpowiedzi. Wyślij zapytanie ponownie. |
Liczenie tokenów
POST /v1/messages/count_tokens przyjmuje to samo ciało co zapytanie o wiadomość (model, system, messages, tools) i zwraca {"input_tokens": n}: liczbę tokenów wejściowych, którą naliczono by za to zapytanie. Liczy dla hostowanych modeli open-weight, jest darmowe i nie wlicza się do ochrony przed floodem.
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} Liczenie ma własną stronę, z endpointem dla zwykłego tekstu i limitami. Liczenie tokenów