Sari la conținut
Format Anthropic

Format Anthropic

POST /v1/messages primește o cerere în formatul Anthropic Messages și răspunde în același format, cu streaming sau fără. Folosește-l cu SDK-ul Anthropic și cu instrumentele construite pe el, precum Claude Code: setează URL-ul de bază, folosește cheia ta Shannon API și indică un id de model Shannon.

POST https://api.shannon-ai.com/v1/messages

Îndreaptă SDK-ul Anthropic spre URL-ul de bază Shannon. SDK-ul adaugă /v1/messages și trimite cheia ta în header-ul 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)

Răspunsul este un mesaj al cărui content este o listă de blocuri. Găsește blocurile după type: când modelul a raționat, primul bloc este thinking, iar textul vine după el.

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

Headere

Header Valoare Descriere
x-api-key YOUR_API_KEY Cheia ta API. Authorization: Bearer YOUR_API_KEY este acceptat în locul ei.
content-type application/json Obligatoriu.
anthropic-version 2023-06-01 Acceptat, nu este obligatoriu. SDK-ul Anthropic trimite 2023-06-01; răspunsul are același format indiferent de valoare.
anthropic-beta Acceptat, nu este obligatoriu.
x-request-id Opțional. Propriul tău id pentru cerere. Se întoarce neschimbat în răspuns; fără el, răspunsul conține un id de 12 caractere hexazecimale.

Câmpuri de cerere

Doar messages este obligatoriu. Coloana Aplicat de indică modelele pe care un câmp modifică răspunsul. Modelele open-weight găzduite sunt cele douăsprezece id-uri din lista de modele; familia Shannon 3 este shannon-3, shannon-3-pro, shannon-3.1 și shannon-3.1-pro. Modele și prețuri

Câmp Tip Implicit Descriere Aplicat de
model string shannon-1.6-lite Un id de model Shannon din lista de modele. Trimite-l la fiecare cerere. Potrivirea nu ține cont de majuscule. Orice alt nume returnează 400 unknown model, deci un instrument care trimite propriile nume de modele trebuie setat pe un id Shannon. Toate modelele
messages array Obligatoriu. Conversația, cu cel mai vechi mesaj primul, cu rolurile user și assistant. Vezi Mesaje și blocuri de conținut mai jos. Toate modelele
system string | array Instrucțiuni pentru model: un șir de caractere sau o matrice de blocuri de text. Vezi System prompt mai jos. Modele open-weight găzduite, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Limita superioară a răspunsului, în token-uri. Opțional pe acest endpoint; SDK-ul Anthropic îl trimite întotdeauna. O valoare în afara intervalului 1 – 65,536 este mutată în acel interval. Este și cantitatea rezervată din soldul tău cât timp rulează cererea. Modele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true trimite răspunsul ca server-sent events. Vezi Streaming mai jos. Toate modelele
temperature number Temperatura de eșantionare. Pe modelele open-weight găzduite, valorile sunt păstrate între 0 și 2. Modele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Eșantionare nucleus. Modele open-weight găzduite
stop_sequences array Până la 4 șiruri. Răspunsul se încheie înainte de primul care apare. stop_reason rămâne end_turn. Modele open-weight găzduite
tools array Instrumentele pe care modelul le poate apela, fiecare sub forma {"name", "description", "input_schema"}. Vezi Instrumente mai jos. Toate modelele
tool_choice object {"type": "auto"} lasă modelul să decidă, {"type": "any"} îl obligă să apeleze un instrument, {"type": "tool", "name": "…"} îl obligă să apeleze acel instrument. Modele open-weight găzduite
thinking object Cât raționează modelul înainte să răspundă. Vezi Gândire mai jos. Modele open-weight găzduite
web_search boolean false Un adaos Shannon la format: true permite modelului să caute pe web înainte de a răspunde. shannon-1.6-*, shannon-2-*, familia Shannon 3

Fără max_tokens, valoarea este 4,096, iar pe shannon-coder-1 este 65,536.

Markerii metadata, top_k, service_tier și cache_control de pe blocuri sunt acceptați, astfel încât codul client existent să ruleze neschimbat. Ei nu modifică răspunsul; caching-ul de prompt pe modelele open-weight găzduite este automat.

Un răspuns JSON conform unei scheme se cere cu response_format la Chat Completions și cu text.format la Responses. Rezultate structurate

O cerere cu system prompt și gândire

Această cerere trimite un system prompt, un buget de gândire, o temperatură și o secvență de oprire. Folosește un model open-weight găzduit, care le aplică pe toate.

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)

Pe modelele open-weight găzduite, usage raportează token-urile citite din cache-ul de prompt separat de celelalte token-uri de intrare.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

System prompt

system este un șir de caractere sau o matrice de blocuri de text de forma [{"type": "text", "text": "…"}]. Textele blocurilor sunt unite printr-o linie nouă.

Este aplicat de modelele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro și shannon-coder-1. Cu un id din familia Shannon 3, pune instrucțiunile care trebuie respectate în mesajul utilizatorului.

Mesaje și blocuri de conținut

Un mesaj are un role, user sau assistant, și un content. content este un șir de caractere sau o matrice de blocuri.

Bloc Descriere Disponibil pe
{"type": "text", "text": "…"} Text. Toate modelele
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
O imagine într-un mesaj user, ca base64 sau prin URL. Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro și modelele open-weight găzduite care acceptă imagini la intrare
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Un document (PDF, Word, PowerPoint sau Excel) într-un mesaj user, ca base64 sau prin URL. Familia Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Într-un mesaj assistant: un apel de instrument făcut de model într-un răspuns anterior. Toate modelele
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} Într-un mesaj user: rezultatul acelui apel. content este un șir de caractere sau o listă de blocuri de text. Toate modelele

Poți trimite înapoi content al unui răspuns anterior exact așa cum este: blocurile text și tool_use sunt citite, blocurile thinking sunt ignorate.

Pe nivelurile Shannon, imaginile și documentele se citesc din ultimul mesaj user. Dimensiunile și limitele au propria pagină. Imagini și fișiere

Gândire

Modelele open-weight găzduite asociază thinking cu un efort de raționament. Fără acest câmp, efortul este ridicat.

Formă budget_tokens Efect
{"type": "disabled"} Fără raționament. Răspunsul nu are bloc thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Efort scăzut.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Efort mediu.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Efort ridicat.

Un model care raționează returnează raționamentul ca bloc {"type": "thinking", "thinking": "…"} înaintea textului. Nivelurile Shannon care raționează îl trimit și ele.

Nivelurile de efort sunt descrise pe propria pagină. Efort de raționament

Instrumente

Un instrument este o funcție pe care o rulează codul tău. Descrie fiecare instrument cu un name, o description și un input_schema. Când modelul dorește un instrument, răspunsul conține un bloc tool_use, iar stop_reason este tool_use.

O definiție de instrument în tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

content al unui răspuns care îl apelează:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

Rulează instrumentul, apoi trimite din nou cererea cu apelul și cu un bloc tool_result adăugate în messages:

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

Formă Efect Aplicat de
{"type": "auto"} Modelul decide dacă apelează un instrument. Aceasta este valoarea implicită. Toate modelele
{"type": "any"} Modelul trebuie să apeleze unul dintre instrumente. Modele open-weight găzduite
{"type": "tool", "name": "…"} Modelul trebuie să apeleze instrumentul indicat. Modele open-weight găzduite

Sunt citite doar instrumentele cu un input_schema. Căutarea web nu este un instrument pe acest endpoint: setează câmpul web_search.

Bucla instrumentelor este descrisă complet pe propria pagină. Apelare funcții

Răspunsul

Câmp Tip Descriere Trimis de
id string msg_ urmat de 32 de caractere hexazecimale. Toate modelele
type string Întotdeauna message. Toate modelele
role string Întotdeauna assistant. Toate modelele
model string Id-ul canonic al modelului care a răspuns. Toate modelele
content array Blocurile răspunsului, în această ordine: thinking când modelul a raționat, text, apoi câte un tool_use pentru fiecare apel de instrument. Toate modelele
stop_reason string Motivul pentru care s-a încheiat răspunsul. Vezi valorile de mai jos. Toate modelele
usage object input_tokens și output_tokens. Toate modelele
sources array Doar la o cerere cu web_search: true a cărei căutare a găsit ceva: rezultatele date modelului, fiecare cu index, title și url. [1] din răspuns este intrarea cu index 1. Într-un stream vine cu evenimentul message_delta. shannon-1.6-*, shannon-2-*, familia Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens este partea din prompt citită din cache; input_tokens este restul. cache_creation_input_tokens este întotdeauna 0. Modele open-weight găzduite

Blocurile răspunsului

Bloc Descriere
{"type": "thinking", "thinking": "…"} Raționamentul modelului. Nu există membrul signature.
{"type": "text", "text": "…"} Textul răspunsului. Poate fi gol atunci când răspunsul este un apel de instrument.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Un apel de instrument. input este un obiect JSON. Trimite rezultatul înapoi cu același id.

stop_reason

stop_reason Descriere Trimis de
end_turn Modelul și-a încheiat răspunsul sau a apărut una dintre stop_sequences ale tale. Toate modelele
tool_use Răspunsul conține unul sau mai multe apeluri de instrument. Toate modelele
max_tokens Răspunsul a fost tăiat la limita de ieșire. Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, în stream-uri

Streaming

Setează stream la true pentru server-sent events. Fiecare cadru are o linie event: cu numele evenimentului și o linie data: cu un obiect JSON care repetă numele în type. Funcțiile helper de stream ale SDK-ului Anthropic citesc aceste evenimente pentru tine:

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)

Evenimentele, în ordinea în care sosesc:

Eveniment Date Când
message_start message Întotdeauna primul. message conține id-ul, rolul, modelul, un content gol și un usage care pornește de la zero.
content_block_start index, content_block Se deschide un bloc. content_block este un bloc text sau thinking gol ori un bloc tool_use cu id și name.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} O bucată din raționament, pentru un bloc thinking.
content_block_delta index, delta {"type": "text_delta", "text"} O bucată din răspuns, pentru un bloc text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Argumentele unui apel de instrument, complete într-un singur delta, pentru un bloc tool_use.
content_block_stop index Blocul cu acest index este complet.
message_delta delta {stop_reason, stop_sequence}, usage Sfârșitul răspunsului: delta.stop_reason și usage al cererii.
message_stop Întotdeauna ultimul.

Blocurile sunt numerotate prin index în ordinea în care se deschid, iar un bloc este complet înainte să se deschidă următorul. Citește fiecare bloc după tipul lui, nu după număr: un stream poate deschide mai întâi un bloc text gol, apoi blocul thinking, și poate livra răspunsul într-un bloc text ulterior.

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

Trimis de Descriere
Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Un eveniment ping cu datele {"type": "ping"}, la fiecare 15 secunde.
Modele open-weight găzduite O linie de comentariu : keepalive, la fiecare 15 secunde cât timp lucrează modelul.

Un stream care eșuează

O eroare după ce stream-ul a început este un eveniment error cu același corp ca un răspuns de eroare: {"type": "error", "error": {"type", "message"}}. Evenimentele de încheiere, message_delta și message_stop, urmează totuși. Tratează răspunsul ca eșuat și trimite cererea din nou.

Erori

Erorile folosesc corpul de eroare Anthropic: type este error, iar obiectul error conține un type și un message. Tabelul listează ce returnează cel mai des acest endpoint. Lista completă, cu ce merită reîncercat, are propria pagină. Gestionare erori

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Stare Tip Mesaj Când
401 authentication_error Missing authentication
Invalid API key
Nu a fost trimisă nicio cheie API sau cheia este necunoscută ori revocată.
400 invalid_request_error unknown model: <id> model nu este un id de model Shannon.
400 invalid_request_error No user message provided Niveluri Shannon: cererea nu are text de la utilizator și nici tools.
400 invalid_request_error <id> does not accept image input O imagine a fost trimisă unui model open-weight găzduit care nu acceptă imagini la intrare.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages lipsește sau un câmp are tipul JSON greșit.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens este mai mare decât ce a rămas din soldul tău.
429 rate_limit_error Too many requests. Retry in <n>s. Protecție anti-flood: mai mult de 120 de cereri într-un minut pe contul tău.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: apelurile Shannon Coder ale planului tău pentru fereastra curentă de 4 ore au fost consumate.
500 server_error The model backend failed to answer. Please retry. Modelul nu a produs un răspuns. Trimite cererea din nou.
502 api_error The model backend failed to answer. Please retry. Modelul nu a produs un răspuns. Trimite cererea din nou.

Numărarea token-urilor

POST /v1/messages/count_tokens primește același corp ca o cerere de mesaj (model, system, messages, tools) și returnează {"input_tokens": n}: numărul de token-uri de intrare care ar fi taxate pentru cerere. Funcționează pentru modelele open-weight găzduite, este gratuit și nu este numărat de protecția anti-flood.

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)

Numărarea are propria pagină, cu endpoint-ul pentru text simplu și limitele. Numărarea token-urilor