Към съдържанието
Anthropic формат

Anthropic формат

POST /v1/messages приема заявка във формата Anthropic Messages и отговаря в същия формат, със стрийминг или без. Използвайте го с Anthropic SDK и с инструменти, изградени върху него, като Claude Code: задайте базовия URL, използвайте своя API ключ на Shannon и посочете id на модел на Shannon.

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

Насочете Anthropic SDK към базовия URL на Shannon. 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 на заявката. Връща се непроменен в отговора; без него отговорът носи id от 12 шестнадесетични знака.

Полета на заявката

Задължително е само messages. Колоната Прилага се от посочва моделите, при които полето променя отговора. Хостваните open-weight модели са дванадесетте id-та от списъка с модели; семейство Shannon 3 са shannon-3, shannon-3-pro, shannon-3.1 и shannon-3.1-pro. Модели и цени

Поле Тип По подразбиране Описание Прилага се от
model string shannon-1.6-lite Id на модел на Shannon от списъка с модели. Изпращайте го с всяка заявка. Съпоставянето не зависи от регистъра. Всяко друго име връща 400 unknown model, така че инструмент, който изпраща собствени имена на модели, трябва да бъде настроен на id на Shannon. Всички модели
messages array Задължително. Разговорът, първо най-старото съобщение, с роли user и assistant. Вижте Съобщения и съдържателни блокове по-долу. Всички модели
system string | array Инструкции за модела: низ или масив от текстови блокове. Вижте Системен prompt по-долу. Хоствани open-weight модели, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Горна граница на отговора, в токени. Незадължително при този ендпоинт; Anthropic SDK винаги го изпраща. Стойност извън 1 до 65,536 се привежда в този диапазон. Това е и сумата, заделена от баланса ви, докато заявката се изпълнява. Хоствани open-weight модели, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true изпраща отговора като server-sent events. Вижте Стрийминг по-долу. Всички модели
temperature number Температура на семплиране. При хостваните open-weight модели стойностите се държат между 0 и 2. Хоствани open-weight модели, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Nucleus семплиране. Хоствани open-weight модели
stop_sequences array До 4 низа. Отговорът свършва преди първия от тях, който се появи. stop_reason остава end_turn. Хоствани open-weight модели
tools array Инструментите, които моделът може да извика, всеки като {"name", "description", "input_schema"}. Вижте Инструменти по-долу. Всички модели
tool_choice object {"type": "auto"} оставя модела да реши, {"type": "any"} го кара да извика инструмент, {"type": "tool", "name": "…"} го кара да извика този инструмент. Хоствани open-weight модели
thinking object Колко разсъждава моделът, преди да отговори. Вижте Мислене по-долу. Хоствани 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 върху блокове се приемат, за да работи съществуващият клиентски код без промяна. Те не променят отговора; кеширането на prompt-ове при хостваните open-weight модели е автоматично.

JSON отговор по схема се иска с response_format при Chat Completions и с text.format при Responses. Структурирани изходи

Заявка със системен prompt и мислене

Тази заявка изпраща системен prompt, бюджет за мислене, температура и стоп последователност. Използва хостван 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)

При хостваните open-weight модели usage отчита токените, прочетени от кеша на prompt-ове, отделно от останалите входни токени.

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

Системен prompt

system е низ или масив от текстови блокове във вида [{"type": "text", "text": "…"}]. Текстовете на блоковете се свързват с нов ред.

Прилага се от хостваните open-weight модели, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro и shannon-coder-1. При id от семейство Shannon 3 поставяйте инструкциите, които трябва да важат, в потребителското съобщение.

Съобщения и съдържателни блокове

Съобщението има 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 и хостваните open-weight модели, които поддържат вход с изображения
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Документ (PDF, Word, PowerPoint или Excel) в съобщение user, като 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. Размерите и лимитите имат собствена страница. Изображения и файлове

Мислене

Хостваните 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"} Моделът трябва да извика един от инструментите. Хоствани open-weight модели
{"type": "tool", "name": "…"} Моделът трябва да извика посочения инструмент. Хоствани open-weight модели

Четат се само инструменти с input_schema. Уеб търсенето не е инструмент при този ендпоинт: задайте полето 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 е частта от prompt-а, прочетена от кеша; input_tokens е останалото. cache_creation_input_tokens винаги е 0. Хоствани 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, при стрийминг

Стрийминг

Задайте stream на true за server-sent events. Всеки кадър има ред event: с името на събитието и ред data: с JSON обект, който повтаря името в type. Помощниците за стрийминг на 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, или блок tool_use с неговите id и name.
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"} Аргументите на извикване на инструмент, пълни в една delta, за блок 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 Събитие ping с данни {"type": "ping"}, на всеки 15 секунди.
Хоствани open-weight модели Коментарен ред : keepalive, на всеки 15 секунди, докато моделът работи.

Стрийм, който се проваля

Неуспех, след като стриймът е започнал, е събитие error със същото тяло като отговор с грешка: {"type": "error", "error": {"type", "message"}}. Заключителните събития, message_delta и message_stop, пак следват. Считайте отговора за неуспешен и изпратете заявката отново.

Грешки

Грешките използват тялото на грешка на Anthropic: type е error, а обектът error съдържа type и message. Таблицата изброява какво най-често връща този ендпоинт. Пълният списък, с указание кога да опитате отново, има собствена страница. Обработка на грешки

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 не е id на модел на Shannon.
400 invalid_request_error No user message provided Нива на Shannon: заявката няма потребителски текст и няма tools.
400 invalid_request_error <id> does not accept image input Изображение е изпратено към хостван 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. Защита от наводняване: повече от 120 заявки в минута за вашия акаунт.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: извикванията на Shannon Coder по вашия план за текущия 4-часов прозорец са изразходвани.
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}: броя входни токени, които заявката би таксувала. Брои се за хостваните open-weight модели, безплатно е и не се отчита от защитата от наводняване.

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)

Броенето има собствена страница, с текстовия ендпоинт и лимитите. Броене на токени