Перейти до вмісту
Формат 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 Інструкції для моделі: рядок або масив текстових блоків. Див. нижче «Системний промпт». Хостовані 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 на блоках приймаються, щоб наявний клієнтський код працював без змін. Вони не змінюють відповідь; кешування запитів на хостованих open-weight моделях автоматичне.

JSON-відповідь за схемою запитується через response_format у Chat Completions і через text.format у Responses. Структуровані відповіді

Запит із системним промптом і міркуваннями

Цей запит надсилає системний промпт, бюджет міркувань, температуру та послідовність зупинки. Він використовує хостовану 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 повідомляє токени, прочитані з кешу запитів, окремо від решти вхідних токенів.

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

Системний промпт

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

Виконайте інструмент, потім надішліть запит знову, додавши до messages виклик і блок tool_result:

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 — частина промпту, прочитана з кешу; 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"} Аргументи виклику інструмента, повністю в одній дельті, для блоку 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)

Підрахунок має окрему сторінку з текстовим ендпоінтом і лімітами. Підрахунок токенів