Przejdź do treści
Format Anthropic

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)

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.

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
  }
}

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)

W hostowanych modelach open-weight usage raportuje tokeny odczytane z cache promptów osobno od pozostałych tokenów wejściowych.

200 JSON
{
  "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:

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:

200 content
[
  {
    "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:

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

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)

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.

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

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

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Status Typ Komunikat Kiedy
401 authentication_error Missing authentication
Invalid 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)

Liczenie ma własną stronę, z endpointem dla zwykłego tekstu i limitami. Liczenie tokenów