Tsarin Anthropic
POST /v1/messages yana karɓar request a tsarin Anthropic Messages kuma yana amsawa a tsari ɗaya, da streaming ko ba tare da shi ba. Ku yi amfani da shi da Anthropic SDK da kayan da aka gina a kansa, kamar Claude Code: ku saita base URL, ku yi amfani da maɓallin API ɗinku na Shannon, ku rubuta model id na Shannon.
POST https://api.shannon-ai.com/v1/messages
Ku nuna Anthropic SDK zuwa base URL na Shannon. SDK yana ƙara /v1/messages kuma yana aika maɓallinku a header na 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."}]
}' Amsar saƙo ce wadda content ɗinta jerin blocks ne. Ku nemo blocks ta type ɗinsu: idan model ya yi reasoning, block na farko shi ne thinking kuma rubutun yana bayansa.
{
"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
}
} Headers
| Header | Ƙima | Bayani |
|---|---|---|
x-api-key | YOUR_API_KEY | Maɓallin API ɗinku. Ana karɓar Authorization: Bearer YOUR_API_KEY a madadinsa. |
content-type | application/json | Wajibi. |
anthropic-version | 2023-06-01 | Ana karɓa, ba wajibi ba. Anthropic SDK yana aika 2023-06-01; amsar tana da tsari iri ɗaya komai ƙimar. |
anthropic-beta | Ana karɓa, ba wajibi ba. | |
x-request-id | Zaɓi. Id ɗinku na request ɗin. Yana dawowa kamar yadda yake a amsar; idan babu shi amsar tana ɗauke da id na haruffan hexadecimal 12. |
Fields na request
messages kaɗai ake buƙata. Ginshiƙin Wanda ke aiwatarwa yana sunayen models da field ke canza amsa a kansu. Hosted open-weight models su ne ids goma sha biyu na jerin models; iyalin Shannon 3 su ne shannon-3, shannon-3-pro, shannon-3.1 da shannon-3.1-pro. Models & farashi
| Field | Nau'i | Na asali | Bayani | Wanda ke aiwatarwa |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Model id na Shannon daga jerin models. Ku aika shi a kowace request. Ba a bambanta manyan haruffa da ƙanana. Duk wani suna yana mayar da 400 unknown model, don haka tool da ke aika sunayen models nasa dole a saita shi zuwa id na Shannon. | Duk models |
messages | array | Wajibi. Tattaunawar, saƙon mafi tsufa da farko, da roles user da assistant. Duba Saƙonni da content blocks a ƙasa. | Duk models | |
system | string | array | Umarni ga model: string, ko array na text blocks. Duba System prompt a ƙasa. | Hosted open-weight models, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Iyakar amsa, a tokens. Zaɓi ne a wannan endpoint; Anthropic SDK koyaushe yana aikawa da shi. Ƙimar da ta wuce 1 zuwa 65,536 ana mayar da ita cikin wannan kewayon. Hakanan shi ne adadin da ake ware daga balance ɗinku yayin da request yake gudana. | Hosted open-weight models, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true yana aika amsar a matsayin server-sent events. Duba Streaming a ƙasa. | Duk models |
temperature | number | Sampling temperature. A kan hosted open-weight models ana riƙe ƙimomi tsakanin 0 da 2. | Hosted open-weight models, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Nucleus sampling. | Hosted open-weight models | |
stop_sequences | array | Har zuwa strings 4. Amsar tana ƙarewa kafin na farko da ya bayyana. stop_reason yana nan end_turn. | Hosted open-weight models | |
tools | array | Tools da model zai iya kira, kowanne a matsayin {"name", "description", "input_schema"}. Duba Tools a ƙasa. | Duk models | |
tool_choice | object | {"type": "auto"} yana barin model ya yanke shawara, {"type": "any"} yana tilasta masa kiran tool, {"type": "tool", "name": "…"} yana tilasta masa kiran wannan tool ɗin. | Hosted open-weight models | |
thinking | object | Yawan reasoning da model ke yi kafin ya amsa. Duba Thinking a ƙasa. | Hosted open-weight models | |
web_search | boolean | false | Ƙari na Shannon ga tsarin: true yana barin model ya bincika yanar gizo kafin ya amsa. | shannon-1.6-*, shannon-2-*, iyalin Shannon 3 |
Idan babu max_tokens ƙimar ita ce 4,096, kuma 65,536 a kan shannon-coder-1.
Ana karɓar metadata, top_k, service_tier da alamomin cache_control a kan blocks don code na client da ke akwai ya yi aiki ba tare da canji ba. Ba sa canza amsar; adana prompt a kan hosted open-weight models yana faruwa ta atomatik.
Ana neman amsar JSON bisa schema da response_format a Chat Completions da text.format a Responses. Abubuwan da aka Tsara
Request mai system prompt da thinking
Wannan request yana aika system prompt, thinking budget, temperature da stop sequence. Yana amfani da hosted open-weight model, wanda ke aiwatar da dukansu.
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?"}]
}' A kan hosted open-weight models usage yana bayyana tokens da aka karanta daga prompt cache daban da sauran input tokens.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} System prompt
system string ne, ko array na text blocks a tsarin [{"type": "text", "text": "…"}]. Ana haɗa rubutun blocks da karya layi.
Hosted open-weight models, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro da shannon-coder-1 ne ke aiwatar da shi. Da id na iyalin Shannon 3, ku saka umarnin da dole ya yi aiki a cikin saƙon mai amfani.
Saƙonni da content blocks
Saƙo yana da role, wato user ko assistant, da content. content string ne, ko array na blocks.
| Block | Bayani | Akwai a |
|---|---|---|
{"type": "text", "text": "…"} | Rubutu. | Duk models |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | Hoto a cikin saƙon user, a matsayin base64 ko ta URL. | Iyalin Shannon 3, shannon-1.6-lite, shannon-1.6-pro, da hosted open-weight models da ke da image input |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Takarda (PDF, Word, PowerPoint ko Excel) a cikin saƙon user, a matsayin base64 ko ta URL. | Iyalin Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | A cikin saƙon assistant: kiran tool da model ya yi a amsa ta baya. | Duk models |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | A cikin saƙon user: sakamakon wannan kira. content string ne, ko jerin text blocks. | Duk models |
Kuna iya mayar da content na amsa ta farko yadda yake: ana karanta blocks na text da tool_use, ana tsallake blocks na thinking.
A matakan Shannon ana karanta hotuna da takardu daga saƙon user na ƙarshe. Girma da iyakoki suna da shafinsu. Hotuna da fayiloli
Thinking
Hosted open-weight models suna fassara thinking zuwa reasoning effort. Idan babu field ɗin, effort yana high.
| Siffa | budget_tokens | Tasiri |
|---|---|---|
{"type": "disabled"} | Babu reasoning. Amsar ba ta da block na thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Effort kaɗan. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Effort matsakaici. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Effort mai yawa. |
Model da ke yin reasoning yana mayar da reasoning ɗinsa a matsayin block {"type": "thinking", "thinking": "…"} a gaban rubutun. Matakan Shannon da ke yin reasoning suna aikawa da shi ma.
An bayyana efforts a shafinsu. Reasoning effort
Tools
Tool function ne da code ɗinku ke gudanarwa. Ku bayyana kowanne da name, description da input_schema. Idan model yana son tool, amsar tana ɗauke da block na tool_use kuma stop_reason shi ne tool_use.
Ma'anar tool a cikin tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] content na amsar da ke kiransa:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Ku gudanar da tool, sannan ku sake aika request tare da kiran da block na tool_result da aka ƙara a 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
| Siffa | Tasiri | Wanda ke aiwatarwa |
|---|---|---|
{"type": "auto"} | Model ne ke yanke shawarar kiran tool. Wannan shi ne na asali. | Duk models |
{"type": "any"} | Dole model ya kira ɗaya daga cikin tools. | Hosted open-weight models |
{"type": "tool", "name": "…"} | Dole model ya kira tool mai sunan da aka ambata. | Hosted open-weight models |
Ana karanta tools masu input_schema kaɗai. Binciken yanar gizo ba tool ba ne a wannan endpoint: ku saita field ɗin web_search.
An bayyana tool loop cikakke a shafinsa. Kiran Aiki
Amsar
| Field | Nau'i | Bayani | Wanda ya aika |
|---|---|---|---|
id | string | msg_ da ke biye da haruffan hexadecimal 32. | Duk models |
type | string | Koyaushe message. | Duk models |
role | string | Koyaushe assistant. | Duk models |
model | string | Id na asali na model da ya amsa. | Duk models |
content | array | Blocks na amsar, a wannan tsari: thinking idan model ya yi reasoning, text, sannan tool_use ɗaya ga kowane kiran tool. | Duk models |
stop_reason | string | Dalilin ƙarewar amsar. Duba ƙimomin a ƙasa. | Duk models |
usage | object | input_tokens da output_tokens. | Duk models |
sources | array | Kawai a kan request mai web_search: true wanda binciken sa ya sami wani abu: sakamakon da aka ba model, kowanne tare da index, title da url. [1] a cikin amsar shi ne shigarwar da ke da index 1. A cikin stream yana zuwa da event ɗin message_delta. | shannon-1.6-*, shannon-2-*, iyalin Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens shi ne ɓangaren prompt da aka karanta daga cache; input_tokens shi ne sauran. cache_creation_input_tokens koyaushe 0 ne. | Hosted open-weight models |
Blocks na amsa
| Block | Bayani |
|---|---|
{"type": "thinking", "thinking": "…"} | Reasoning na model. Babu member na signature. |
{"type": "text", "text": "…"} | Rubutun amsar. Yana iya zama babu komai idan amsar kiran tool ce. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Kiran tool. input JSON object ne. Ku mayar da sakamakon da id iri ɗaya. |
stop_reason
| stop_reason | Bayani | Wanda ya aika |
|---|---|---|
end_turn | Model ya gama amsarsa, ko kuma ɗaya daga cikin stop_sequences ɗinku ya bayyana. | Duk models |
tool_use | Amsar tana ɗauke da kiran tool ɗaya ko fiye. | Duk models |
max_tokens | An yanke amsar a iyakar output. | Iyalin Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, a cikin streams |
Streaming
Ku saita stream zuwa true don server-sent events. Kowane frame yana da layin event: mai sunan event da layin data: mai JSON object wanda ke maimaita sunan a type. Stream helpers na Anthropic SDK suna karanta waɗannan events a madadinku:
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."}]
}' Events, bisa tsarin zuwansu:
| Event | Bayanai | Lokaci |
|---|---|---|
message_start | message | Koyaushe na farko. message yana ɗauke da id, role, model, content mara komai da usage da ke farawa daga sifili. |
content_block_start | index, content_block | Block yana buɗewa. content_block block ne na text ko thinking mara komai, ko block na tool_use tare da id da name ɗinsa. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | Ɗan guntun reasoning, don block na thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | Ɗan guntun amsa, don block na text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Arguments na kiran tool, cikakke a delta ɗaya, don block na tool_use. |
content_block_stop | index | Block mai wannan index ya kammala. |
message_delta | delta {stop_reason, stop_sequence}, usage | Ƙarshen amsar: delta.stop_reason, da usage na request ɗin. |
message_stop | Koyaushe na ƙarshe. |
Ana lamba blocks ta index bisa tsarin buɗewarsu, kuma block ɗaya yana kammala kafin na gaba ya buɗe. Ku karanta kowane block ta nau'insa, ba ta lambarsa ba: stream na iya buɗe block na text mara komai da farko, sannan block na thinking, kuma ya kawo amsar a block na text na gaba.
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
| Wanda ya aika | Bayani |
|---|---|
Iyalin Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Event na ping mai data {"type": "ping"}, kowane daƙiƙa 15. |
| Hosted open-weight models | Layin sharhi : keepalive, kowane daƙiƙa 15 yayin da model yake aiki. |
Stream da ya gaza
Gazawa bayan stream ya fara event ne na error mai jiki iri ɗaya da amsar kuskure: {"type": "error", "error": {"type", "message"}}. Events na rufewa, message_delta da message_stop, har yanzu suna biye. Ku ɗauki amsar a matsayin wadda ta gaza, ku sake aika request ɗin.
Kurakurai
Kurakurai suna amfani da jikin kuskure na Anthropic: type shi ne error, kuma object ɗin error yana ɗauke da type da message. Teburin yana lissafa abin da wannan endpoint ya fi mayarwa. Cikakken jerin, tare da abin da za a sake gwadawa, yana da shafinsa. Kuskuren Gudanarwa
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Matsayi | Nau'i | Saƙo | Lokaci |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Ba a aika maɓallin API ba, ko kuma maɓallin ba a san shi ba ko an soke shi. |
400 | invalid_request_error | unknown model: <id> | model ba model id na Shannon ba ne. |
400 | invalid_request_error | No user message provided | Matakan Shannon: request ɗin ba shi da rubutun mai amfani kuma ba shi da tools. |
400 | invalid_request_error | <id> does not accept image input | An aika hoto zuwa hosted open-weight model wanda ba shi da image input. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages ya ɓace, ko kuma wani field yana da nau'in JSON mara kyau. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens ya fi abin da ya rage a balance ɗinku girma. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood protection: fiye da requests 120 a cikin minti ɗaya a asusunku. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: an yi amfani da kiran Shannon Coder na plan ɗinku na taga ta awa 4 ta yanzu. |
500 | server_error | The model backend failed to answer. Please retry. | Model bai samar da amsa ba. Ku sake aika request ɗin. |
502 | api_error | The model backend failed to answer. Please retry. | Model bai samar da amsa ba. Ku sake aika request ɗin. |
Ƙirga tokens
POST /v1/messages/count_tokens yana karɓar jiki iri ɗaya da request na saƙo (model, system, messages, tools) kuma yana mayar da {"input_tokens": n}: adadin input tokens da za a caje wa request ɗin. Yana aiki ga hosted open-weight models, kyauta ne kuma flood protection ba ya ƙirga shi.
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} Ƙirga yana da shafinsa, tare da endpoint na rubutu a sarari da iyakoki. Ƙidayar tokens