Kalo te përmbajtja
Formati Anthropic

Formati Anthropic

POST /v1/messages merr një kërkesë në formatin Anthropic Messages dhe përgjigjet në të njëjtin format, me streaming ose pa të. Përdoreni me SDK-në Anthropic dhe me mjetet e ndërtuara mbi të, si Claude Code: vendosni URL-në bazë, përdorni çelësin tuaj API të Shannon dhe emërtoni një id modeli Shannon.

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

Drejtojeni SDK-në Anthropic te URL-ja bazë e Shannon. SDK-ja shton /v1/messages dhe e dërgon çelësin tuaj në header-in 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)

Përgjigjja është një mesazh me content që është një listë blloqesh. Gjejini blloqet sipas type: kur modeli ka arsyetuar, blloku i parë është thinking dhe teksti vjen pas tij.

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

Header-at

Header Vlera Përshkrimi
x-api-key YOUR_API_KEY Çelësi juaj API. Authorization: Bearer YOUR_API_KEY pranohet në vend të tij.
content-type application/json I detyrueshëm.
anthropic-version 2023-06-01 Pranohet, nuk kërkohet. SDK-ja Anthropic dërgon 2023-06-01; përgjigjja ka të njëjtin format cilado qoftë vlera.
anthropic-beta Pranohet, nuk kërkohet.
x-request-id Opsional. Id-ja juaj për kërkesën. Kthehet e pandryshuar në përgjigje; pa të, përgjigjja mban një id me 12 karaktere heksadecimale.

Fushat e kërkesës

Vetëm messages është i detyrueshëm. Kolona Zbatohet nga emërton modelet te të cilat një fushë ndryshon përgjigjen. Modelet open-weight të hostuara janë dymbëdhjetë id-të e listës së modeleve; familja Shannon 3 është shannon-3, shannon-3-pro, shannon-3.1 dhe shannon-3.1-pro. Modelet dhe çmimet

Fusha Lloji Parazgjedhja Përshkrimi Zbatohet nga
model string shannon-1.6-lite Një id modeli Shannon nga lista e modeleve. Dërgojeni me çdo kërkesë. Përputhja nuk është e ndjeshme ndaj shkronjave të mëdha. Çdo emër tjetër kthen 400 unknown model, kështu që një mjet që dërgon emrat e vet të modeleve duhet vendosur me një id Shannon. Të gjitha modelet
messages array E detyrueshme. Biseda, me mesazhin më të vjetër së pari, me rolet user dhe assistant. Shihni Mesazhet dhe blloqet e përmbajtjes më poshtë. Të gjitha modelet
system string | array Udhëzime për modelin: një string ose një varg blloqesh teksti. Shihni System prompt më poshtë. Modele open-weight të hostuara, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Kufiri i sipërm i përgjigjes, në tokens. Opsional në këtë endpoint; SDK-ja Anthropic e dërgon gjithmonë. Një vlerë jashtë intervalit 1 deri 65,536 zhvendoset brenda tij. Është edhe sasia që rezervohet nga bilanci juaj gjatë ekzekutimit të kërkesës. Modele open-weight të hostuara, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true e dërgon përgjigjen si server-sent events. Shihni Streaming më poshtë. Të gjitha modelet
temperature number Temperatura e kampionimit. Te modelet open-weight të hostuara vlerat mbahen mes 0 dhe 2. Modele open-weight të hostuara, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Kampionim nucleus. Modele open-weight të hostuara
stop_sequences array Deri në 4 stringje. Përgjigja mbaron para të parit që shfaqet. stop_reason mbetet end_turn. Modele open-weight të hostuara
tools array Mjetet që modeli mund t'i thërrasë, secili si {"name", "description", "input_schema"}. Shihni Mjetet më poshtë. Të gjitha modelet
tool_choice object {"type": "auto"} e lë modelin të vendosë, {"type": "any"} e detyron të thërrasë një mjet, {"type": "tool", "name": "…"} e detyron të thërrasë atë mjet. Modele open-weight të hostuara
thinking object Sa arsyeton modeli para se të përgjigjet. Shihni Thinking më poshtë. Modele open-weight të hostuara
web_search boolean false Shtesë e Shannon te formati: true e lë modelin të kërkojë në ueb para se të përgjigjet. shannon-1.6-*, shannon-2-*, familja Shannon 3

Pa max_tokens vlera është 4,096, dhe 65,536 te shannon-coder-1.

metadata, top_k, service_tier dhe shenjat cache_control në blloqe pranohen që kodi ekzistues i klientit të punojë pa ndryshime. Ato nuk ndryshojnë përgjigjen; caching-u i prompt-it te modelet open-weight të hostuara është automatik.

Një përgjigje JSON sipas një skeme kërkohet me response_format te Chat Completions dhe me text.format te Responses. Dalje të strukturuara

Një kërkesë me system prompt dhe thinking

Kjo kërkesë dërgon një system prompt, një buxhet thinking, një temperaturë dhe një stop sequence. Përdor një model open-weight të hostuar, i cili i zbaton të gjitha.

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)

Te modelet open-weight të hostuara usage raporton veçmas tokens-at e lexuara nga cache-i i prompt-it dhe tokens-at e tjerë të hyrjes.

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

System prompt

system është një string, ose një varg blloqesh teksti në formën [{"type": "text", "text": "…"}]. Tekstet e blloqeve bashkohen me një ndarje rreshti.

Zbatohet nga modelet open-weight të hostuara, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dhe shannon-coder-1. Me një id të familjes Shannon 3, vendosini udhëzimet që duhet të mbahen në mesazhin e përdoruesit.

Mesazhet dhe blloqet e përmbajtjes

Një mesazh ka një role, user ose assistant, dhe një content. content është një string ose një varg blloqesh.

Blloku Përshkrimi I disponueshëm në
{"type": "text", "text": "…"} Tekst. Të gjitha modelet
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Një imazh në një mesazh user, si base64 ose me URL. Familja Shannon 3, shannon-1.6-lite, shannon-1.6-pro, dhe modelet open-weight të hostuara që listojnë hyrje imazhi
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Një dokument (PDF, Word, PowerPoint ose Excel) në një mesazh user, si base64 ose me URL. Familja Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Në një mesazh assistant: një thirrje mjeti që modeli bëri në një përgjigje të mëparshme. Të gjitha modelet
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} Në një mesazh user: rezultati i asaj thirrjeje. content është një string ose një listë blloqesh teksti. Të gjitha modelet

Mund ta dërgoni content e një përgjigjeje të mëparshme siç është: blloqet text dhe tool_use lexohen, blloqet thinking kapërcehen.

Te nivelet Shannon, imazhet dhe dokumentet lexohen nga mesazhi i fundit user. Madhësitë dhe kufijtë kanë faqen e tyre. Imazhet dhe skedarët

Thinking

Modelet open-weight të hostuara e lidhin thinking me një përpjekje arsyetimi. Pa këtë fushë përpjekja është e lartë.

Forma budget_tokens Efekti
{"type": "disabled"} Pa arsyetim. Përgjigjja nuk ka bllok thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Përpjekje e ulët.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Përpjekje mesatare.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Përpjekje e lartë.

Një model që arsyeton e kthen arsyetimin si bllok {"type": "thinking", "thinking": "…"} para tekstit. Nivelet Shannon që arsyetojnë e dërgojnë gjithashtu.

Përpjekjet përshkruhen në faqen e tyre. Përpjekja e arsyetimit

Mjetet

Një mjet është një funksion që e ekzekuton kodi juaj. Përshkruajeni secilin me një name, një description dhe një input_schema. Kur modeli dëshiron një mjet, përgjigjja përmban një bllok tool_use dhe stop_reason është tool_use.

Një përkufizim mjeti te tools:

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

content e një përgjigjeje që e thërret:

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

Ekzekutojeni mjetin, pastaj dërgojeni kërkesën përsëri me thirrjen dhe një bllok tool_result të shtuar te 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

Forma Efekti Zbatohet nga
{"type": "auto"} Modeli vendos nëse do të thërrasë një mjet. Kjo është parazgjedhja. Të gjitha modelet
{"type": "any"} Modeli duhet të thërrasë një nga mjetet. Modele open-weight të hostuara
{"type": "tool", "name": "…"} Modeli duhet të thërrasë mjetin e emërtuar. Modele open-weight të hostuara

Lexohen vetëm mjetet me një input_schema. Kërkimi në ueb nuk është mjet në këtë endpoint: vendosni fushën web_search.

Cikli i mjeteve përshkruhet i plotë në faqen e vet. Thirrje funksionesh

Përgjigjja

Fusha Lloji Përshkrimi Dërguar nga
id string msg_ e ndjekur nga 32 karaktere heksadecimale. Të gjitha modelet
type string Gjithmonë message. Të gjitha modelet
role string Gjithmonë assistant. Të gjitha modelet
model string Id-ja kanonike e modelit që u përgjigj. Të gjitha modelet
content array Blloqet e përgjigjes, në këtë renditje: thinking kur modeli ka arsyetuar, text, pastaj një tool_use për çdo thirrje mjeti. Të gjitha modelet
stop_reason string Pse mbaroi përgjigjja. Shihni vlerat më poshtë. Të gjitha modelet
usage object input_tokens dhe output_tokens. Të gjitha modelet
sources array Vetëm te një kërkesë me web_search: true kërkimi i së cilës gjeti diçka: rezultatet që iu dhanë modelit, secili me index, title dhe url. [1] në përgjigje është hyrja me index 1. Në një stream vjen me ngjarjen message_delta. shannon-1.6-*, shannon-2-*, familja Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens është pjesa e prompt-it e lexuar nga cache-i; input_tokens është pjesa tjetër. cache_creation_input_tokens është gjithmonë 0. Modele open-weight të hostuara

Blloqet e përgjigjes

Blloku Përshkrimi
{"type": "thinking", "thinking": "…"} Arsyetimi i modelit. Nuk ka anëtar signature.
{"type": "text", "text": "…"} Teksti i përgjigjes. Mund të jetë bosh kur përgjigjja është një thirrje mjeti.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Një thirrje mjeti. input është një objekt JSON. Dërgojeni rezultatin mbrapsht me të njëjtën id.

stop_reason

stop_reason Përshkrimi Dërguar nga
end_turn Modeli e mbaroi përgjigjen, ose u shfaq një nga stop_sequences tuaja. Të gjitha modelet
tool_use Përgjigjja përmban një ose më shumë thirrje mjetesh. Të gjitha modelet
max_tokens Përgjigjja u ndërpre te kufiri i daljes. Familja Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, në stream-e

Streaming

Vendosni stream në true për server-sent events. Çdo frame ka një rresht event: me emrin e ngjarjes dhe një rresht data: me një objekt JSON që e përsërit emrin te type. Ndihmësit e stream-it të SDK-së Anthropic i lexojnë këto ngjarje për ju:

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)

Ngjarjet, në radhën që arrijnë:

Ngjarja Të dhënat Kur
message_start message Gjithmonë i pari. message përmban id-në, rolin, modelin, një content bosh dhe një usage që fillon në zero.
content_block_start index, content_block Hapet një bllok. content_block është një bllok text ose thinking bosh, ose një bllok tool_use me id dhe name.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Një copë e arsyetimit, për një bllok thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Një copë e përgjigjes, për një bllok text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Argumentet e një thirrjeje mjeti, të plota në një delta, për një bllok tool_use.
content_block_stop index Blloku me këtë index ka mbaruar.
message_delta delta {stop_reason, stop_sequence}, usage Fundi i përgjigjes: delta.stop_reason, dhe usage i kërkesës.
message_stop Gjithmonë i fundit.

Blloqet numërohen sipas index në radhën e hapjes, dhe një bllok mbaron para se të hapet tjetri. Lexojeni çdo bllok sipas llojit, jo sipas numrit: një stream mund të hapë së pari një bllok text bosh, pastaj bllokun thinking, dhe ta japë përgjigjen në një bllok text më të vonshëm.

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

Dërguar nga Përshkrimi
Familja Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Një ngjarje ping me të dhënat {"type": "ping"}, çdo 15 sekonda.
Modele open-weight të hostuara Një rresht komenti : keepalive, çdo 15 sekonda ndërkohë që modeli punon.

Një stream që dështon

Një dështim pasi stream-i ka nisur është një ngjarje error me të njëjtin trup si një përgjigje gabimi: {"type": "error", "error": {"type", "message"}}. Ngjarjet mbyllëse, message_delta dhe message_stop, vijnë prapë pas saj. Trajtojeni përgjigjen si të dështuar dhe dërgoni kërkesën përsëri.

Gabimet

Gabimet përdorin trupin e gabimit të Anthropic: type është error, dhe objekti error përmban një type dhe një message. Tabela liston ato që ky endpoint kthen më shpesh. Lista e plotë, me atë që duhet provuar përsëri, ka faqen e vet. Trajtimi i gabimeve

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Statusi Lloji Mesazhi Kur
401 authentication_error Missing authentication
Invalid API key
Nuk u dërgua çelës API, ose çelësi është i panjohur ose i shfuqizuar.
400 invalid_request_error unknown model: <id> model nuk është id modeli Shannon.
400 invalid_request_error No user message provided Nivelet Shannon: kërkesa nuk ka tekst përdoruesi dhe nuk ka tools.
400 invalid_request_error <id> does not accept image input Një imazh iu dërgua një modeli open-weight të hostuar pa hyrje imazhi.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages mungon, ose një fushë ka lloj JSON të gabuar.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens është më i madh se ç'ka mbetur nga bilanci juaj.
429 rate_limit_error Too many requests. Retry in <n>s. Mbrojtja nga vërshimi i kërkesave: më shumë se 120 kërkesa në një minutë në llogarinë tuaj.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: thirrjet Shannon Coder të planit tuaj për dritaren aktuale 4-orëshe janë shfrytëzuar.
500 server_error The model backend failed to answer. Please retry. Modeli nuk prodhoi përgjigje. Dërgoni kërkesën përsëri.
502 api_error The model backend failed to answer. Please retry. Modeli nuk prodhoi përgjigje. Dërgoni kërkesën përsëri.

Numërimi i tokens-ave

POST /v1/messages/count_tokens merr të njëjtin trup si një kërkesë mesazhi (model, system, messages, tools) dhe kthen {"input_tokens": n}: numrin e tokens-ave të hyrjes që do t'i faturoheshin kërkesës. Vlen për modelet open-weight të hostuara, është falas dhe nuk numërohet nga mbrojtja nga vërshimi i kërkesave.

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ërimi ka faqen e vet, me endpoint-in për tekst të thjeshtë dhe kufijtë. Numërimi i tokens-ave