Мазмұнға өту
Anthropic форматы

Anthropic форматы

POST /v1/messages Anthropic Messages форматындағы сұрауды қабылдап, сол форматта жауап береді, стримдеп немесе стримсіз. Оны Anthropic SDK-мен және соның негізіндегі Claude Code сияқты құралдармен қолданыңыз: базалық URL-ді орнатыңыз, Shannon API кілтіңізді қолданыңыз және Shannon модель id-ін көрсетіңіз.

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

Anthropic SDK-ны Shannon базалық URL-іне бағыттаңыз. SDK /v1/messages қосады және кілтіңізді 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)

Жауап — content өрісі блоктар тізімі болатын хабарлама. Блоктарды type бойынша табыңыз: модель пайымдаса, бірінші блок thinking болады, мәтін одан кейін келеді.

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

Тақырыптар

Тақырып Мәні Сипаттама
x-api-key YOUR_API_KEY API кілтіңіз. Оның орнына Authorization: Bearer YOUR_API_KEY қабылданады.
content-type application/json Міндетті.
anthropic-version 2023-06-01 Қабылданады, міндетті емес. Anthropic SDK 2023-06-01 жібереді; мән қандай болса да, жауап форматы бірдей.
anthropic-beta Қабылданады, міндетті емес.
x-request-id Міндетті емес. Сұрау үшін өз id-ңіз. Ол жауапта өзгеріссіз қайтады; онсыз жауапта 12 оналтылық таңбадан тұратын id болады.

Сұрау өрістері

Тек messages міндетті. Қолданады бағанында өріс жауапты өзгертетін модельдер аталған. Hosted open-weight модельдер — модельдер тізіміндегі он екі id; Shannon 3 отбасы — shannon-3, shannon-3-pro, shannon-3.1 және shannon-3.1-pro. Модельдер және бағалар

Өріс Түрі Әдепкі Сипаттама Қолданады
model string shannon-1.6-lite Модельдер тізіміндегі Shannon модель id-і. Оны әр сұраумен жіберіңіз. Сәйкестендіруде регистр ескерілмейді. Кез келген басқа атау 400 unknown model қайтарады, сондықтан өз модель атауларын жіберетін құралды Shannon id-ге баптау керек. Барлық модельдер
messages array Міндетті. Әңгіме, ең ескі хабарлама бірінші, user және assistant рөлдерімен. Төмендегі «Хабарламалар және мазмұн блоктары» бөлімін қараңыз. Барлық модельдер
system string | array Модельге нұсқаулар: жол немесе мәтін блоктарының массиві. Төмендегі «System prompt» бөлімін қараңыз. Hosted open-weight модельдер, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Жауаптың жоғарғы шегі, токенмен. Бұл endpoint-те міндетті емес; Anthropic SDK оны әрқашан жібереді. 1-ден 65,536-ға дейінгі аралықтан тыс мән сол аралыққа түзетіледі. Сондай-ақ сұрау орындалып жатқанда балансыңыздан бөлек сақталатын сома осы. Hosted open-weight модельдер, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true жауапты server-sent events ретінде жібереді. Төмендегі «Streaming» бөлімін қараңыз. Барлық модельдер
temperature number Сэмплинг температурасы. Hosted open-weight модельдерде мәндер 0 мен 2 арасында ұсталады. Hosted open-weight модельдер, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Nucleus sampling. Hosted open-weight модельдер
stop_sequences array 4 жолға дейін. Жауап пайда болған біріншісінің алдында аяқталады. stop_reason мәні end_turn болып қалады. Hosted open-weight модельдер
tools array Модель шақыра алатын құралдар, әрқайсысы {"name", "description", "input_schema"} түрінде. Төмендегі «Құралдар» бөлімін қараңыз. Барлық модельдер
tool_choice object {"type": "auto"} модельге өзі шешуге мүмкіндік береді, {"type": "any"} құралды шақыруға мәжбүр етеді, {"type": "tool", "name": "…"} нақты сол құралды шақыртады. Hosted open-weight модельдер
thinking object Модель жауап бермес бұрын қаншалықты пайымдайды. Төмендегі «Thinking» бөлімін қараңыз. Hosted open-weight модельдер
web_search boolean false Форматқа Shannon қосымшасы: true модельге жауап бермес бұрын вебте іздеуге мүмкіндік береді. shannon-1.6-*, shannon-2-*, Shannon 3 отбасы

max_tokens болмаса мән 4,096, ал shannon-coder-1 үшін 65,536.

Блоктардағы metadata, top_k, service_tier және cache_control белгілері бар клиент коды өзгеріссіз жұмыс істеуі үшін қабылданады. Олар жауапты өзгертпейді; hosted open-weight модельдерде промпт кэштеу автоматты.

Схемаға сай JSON жауабы Chat Completions-те response_format арқылы, ал Responses-те text.format арқылы сұралады. Құрылымдалған нәтижелер

System prompt және thinking бар сұрау

Бұл сұрау system prompt, thinking бюджетін, температураны және тоқтату тізбегін жібереді. Ол барлығын қолданатын hosted open-weight модельді пайдаланады.

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)

Hosted open-weight модельдерде usage промпт кэшінен оқылған токендерді басқа кіріс токендерінен бөлек көрсетеді.

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

System prompt

system — жол, немесе [{"type": "text", "text": "…"}] түріндегі мәтін блоктарының массиві. Блок мәтіндері жол үзілімімен біріктіріледі.

Оны hosted open-weight модельдер, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro және shannon-coder-1 қолданады. Shannon 3 отбасының id-імен орындалуы міндетті нұсқауларды пайдаланушы хабарламасына қойыңыз.

Хабарламалар және мазмұн блоктары

Хабарламаның role (user немесе assistant) және content өрістері бар. content — жол немесе блоктар массиві.

Блок Сипаттама Қолжетімді
{"type": "text", "text": "…"} Мәтін. Барлық модельдер
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
user хабарламасындағы сурет, base64 түрінде немесе URL арқылы. Shannon 3 отбасы, shannon-1.6-lite, shannon-1.6-pro және сурет кірісі көрсетілген hosted open-weight модельдер
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} user хабарламасындағы құжат (PDF, Word, PowerPoint немесе Excel), base64 түрінде немесе URL арқылы. Shannon 3 отбасы
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} assistant хабарламасында: модель алдыңғы жауапта жасаған құрал шақыруы. Барлық модельдер
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} user хабарламасында: сол шақырудың нәтижесі. content — жол немесе мәтін блоктарының тізімі. Барлық модельдер

Алдыңғы жауаптың content мәнін өзгеріссіз кері жіберуге болады: text және tool_use блоктары оқылады, thinking блоктары өткізіледі.

Shannon деңгейлерінде суреттер мен құжаттар соңғы user хабарламасынан оқылады. Өлшемдер мен шектеулердің өз беті бар. Суреттер және файлдар

Thinking

Hosted open-weight модельдер thinking мәнін пайымдау күшіне сәйкестендіреді. Өріс болмаса, күш жоғары болады.

Түрі budget_tokens Әсері
{"type": "disabled"} Пайымдау жоқ. Жауапта thinking блогы болмайды.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Төмен күш.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Орта күш.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Жоғары күш.

Пайымдайтын модель пайымдауын мәтіннің алдында {"type": "thinking", "thinking": "…"} блогы ретінде қайтарады. Пайымдайтын Shannon деңгейлері де оны жібереді.

Күш деңгейлері өз бетінде сипатталған. Пайымдау күші

Құралдар

Құрал — сіздің кодыңыз орындайтын функция. Әрқайсысын name, description және input_schema арқылы сипаттаңыз. Модель құралды қажет етсе, жауапта tool_use блогы болады және stop_reason мәні tool_use болады.

tools ішіндегі құрал анықтамасы:

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

Оны шақыратын жауаптың content өрісі:

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

Құралды орындаңыз, содан кейін шақыруды және tool_result блогын 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

Түрі Әсері Қолданады
{"type": "auto"} Құралды шақыру-шақырмауды модель шешеді. Бұл әдепкі мән. Барлық модельдер
{"type": "any"} Модель құралдардың бірін шақыруы керек. Hosted open-weight модельдер
{"type": "tool", "name": "…"} Модель аталған құралды шақыруы керек. Hosted open-weight модельдер

Тек input_schema бар құралдар оқылады. Веб іздеу бұл endpoint-те құрал емес: web_search өрісін орнатыңыз.

Құрал циклі өз бетінде толық сипатталған. Функция шақыру

Жауап

Өріс Түрі Сипаттама Жіберетін
id string msg_ және одан кейін 32 оналтылық таңба. Барлық модельдер
type string Әрқашан message. Барлық модельдер
role string Әрқашан assistant. Барлық модельдер
model string Жауап берген модельдің каноникалық id-і. Барлық модельдер
content array Жауап блоктары мына ретпен: модель пайымдаса thinking, text, содан кейін әр құрал шақыруына бір tool_use. Барлық модельдер
stop_reason string Жауап неге аяқталды. Төмендегі мәндерді қараңыз. Барлық модельдер
usage object input_tokens және output_tokens. Барлық модельдер
sources array Тек іздеуі бірдеңе тапқан web_search: true бар сұрауда: модельге берілген нәтижелер, әрқайсысында index, title және url бар. Жауаптағы [1] — index мәні 1 болатын жазба. Стримде ол message_delta оқиғасымен бірге келеді. shannon-1.6-*, shannon-2-*, Shannon 3 отбасы
usage.cache_read_input_tokens integer cache_read_input_tokens — промптың кэштен оқылған бөлігі; input_tokens — қалғаны. cache_creation_input_tokens әрқашан 0. Hosted open-weight модельдер

Жауап блоктары

Блок Сипаттама
{"type": "thinking", "thinking": "…"} Модельдің пайымдауы. signature мүшесі жоқ.
{"type": "text", "text": "…"} Жауап мәтіні. Жауап құрал шақыруы болса, ол бос болуы мүмкін.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Құрал шақыруы. input — JSON нысаны. Нәтижені сол id-мен қайта жіберіңіз.

stop_reason

stop_reason Сипаттама Жіберетін
end_turn Модель жауабын аяқтады, немесе stop_sequences мәндерінің бірі пайда болды. Барлық модельдер
tool_use Жауапта бір немесе бірнеше құрал шақыруы бар. Барлық модельдер
max_tokens Жауап шығыс шегінде үзілді. Shannon 3 отбасы, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, стримдерде

Streaming

Server-sent events алу үшін stream мәнін true етіп орнатыңыз. Әр кадрда оқиға атауы бар event: жолы және атауды type ішінде қайталайтын JSON нысаны бар data: жолы болады. Anthropic SDK стрим көмекшілері бұл оқиғаларды сіз үшін оқиды:

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)

Оқиғалар келу ретімен:

Оқиға Деректер Қашан
message_start message Әрқашан бірінші. message ішінде id, рөл, модель, бос content және нөлден басталатын usage бар.
content_block_start index, content_block Блок ашылады. content_block — бос text немесе thinking блогы, не id және name өрістері бар tool_use блогы.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} thinking блогы үшін пайымдаудың бір бөлігі.
content_block_delta index, delta {"type": "text_delta", "text"} text блогы үшін жауаптың бір бөлігі.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} tool_use блогы үшін құрал шақыруының аргументтері, бір дельтада толық.
content_block_stop index Осы index бар блок аяқталды.
message_delta delta {stop_reason, stop_sequence}, usage Жауаптың соңы: delta.stop_reason және сұраудың usage мәні.
message_stop Әрқашан соңғы.

Блоктар ашылу ретімен index бойынша нөмірленеді, әр блок келесісі ашылмай тұрып аяқталады. Әр блокты нөмірімен емес, түрімен оқыңыз: стрим алдымен бос text блогын, содан кейін thinking блогын ашып, жауапты кейінгі 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

Жіберетін Сипаттама
Shannon 3 отбасы, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Деректері {"type": "ping"} болатын ping оқиғасы, әр 15 секунд сайын.
Hosted open-weight модельдер : keepalive түсініктеме жолы, модель жұмыс істеп жатқанда әр 15 секунд сайын.

Сәтсіз аяқталған стрим

Стрим басталғаннан кейінгі ақау — қате жауабындағы денемен бірдей error оқиғасы: {"type": "error", "error": {"type", "message"}}. Жабушы оқиғалар message_delta және message_stop бәрібір артынан келеді. Жауапты сәтсіз деп санап, сұрауды қайта жіберіңіз.

Қателер

Қателер Anthropic қате денесін қолданады: type мәні error, ал error нысанында type және message бар. Кестеде осы endpoint ең жиі қайтаратындар берілген. Толық тізімнің, нені қайталау керегімен бірге, өз беті бар. Қателерді өңдеу

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Мәртебе Түрі Хабарлама Қашан
401 authentication_error Missing authentication
Invalid API key
API кілті жіберілмеген, немесе кілт белгісіз не күші жойылған.
400 invalid_request_error unknown model: <id> model Shannon модель id-і емес.
400 invalid_request_error No user message provided Shannon деңгейлері: сұраудың пайдаланушы мәтіні де, tools та жоқ.
400 invalid_request_error <id> does not accept image input Сурет кірісі жоқ hosted open-weight модельге сурет жіберілді.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages жоқ, немесе өрістің JSON түрі қате.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens балансыңыздың қалдығынан үлкен.
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection: аккаунтыңызда бір минутта 120-дан астам сұрау.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: жоспарыңыздың ағымдағы 4 сағаттық терезедегі Shannon Coder сұраулары таусылды.
500 server_error The model backend failed to answer. Please retry. Модель жауап бермеді. Сұрауды қайта жіберіңіз.
502 api_error The model backend failed to answer. Please retry. Модель жауап бермеді. Сұрауды қайта жіберіңіз.

Токендерді есептеу

POST /v1/messages/count_tokens хабарлама сұрауымен бірдей денені (model, system, messages, tools) қабылдайды және {"input_tokens": n} қайтарады: сұрау үшін алынатын кіріс токендерінің саны. Ол hosted open-weight модельдер үшін есептейді, тегін және flood protection есебіне кірмейді.

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)

Есептеудің өз беті бар, онда жай мәтін endpoint-і мен шектеулер сипатталған. Токендерді санау