Tsallake zuwa abun ciki
Tsarin Anthropic

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)

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.

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

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)

A kan hosted open-weight models usage yana bayyana tokens da aka karanta daga prompt cache daban da sauran input tokens.

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

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:

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

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)

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.

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

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

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Matsayi Nau'i Saƙo Lokaci
401 authentication_error Missing authentication
Invalid 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)

Ƙirga yana da shafinsa, tare da endpoint na rubutu a sarari da iyakoki. Ƙidayar tokens