דילוג לתוכן
פורמט Anthropic

פורמט Anthropic

POST /v1/messages מקבל בקשה בפורמט Anthropic Messages ועונה באותו פורמט, ב-streaming או בלעדיו. השתמשו בו עם ה-Anthropic SDK ועם כלים שנבנו עליו, כמו Claude Code: הגדירו את כתובת הבסיס, השתמשו במפתח ה-API של Shannon וציינו מזהה מודל של Shannon.

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

כוונו את ה-Anthropic SDK לכתובת הבסיס של 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 אופציונלי. המזהה שלכם לבקשה. הוא חוזר ללא שינוי בתשובה; בלעדיו התשובה נושאת מזהה של 12 תווים הקסדצימליים.

שדות בקשה

רק messages הוא חובה. העמודה מופעל על ידי מציינת את המודלים שבהם שדה משנה את התשובה. מודלי ה-open-weight המתארחים הם שנים-עשר המזהים ברשימת המודלים; משפחת Shannon 3 היא shannon-3, shannon-3-pro, shannon-3.1 ו-shannon-3.1-pro. מודלים ותמחור

שדה סוג ברירת מחדל תיאור מופעל על ידי
model string shannon-1.6-lite מזהה מודל של Shannon מרשימת המודלים. שלחו אותו בכל בקשה. ההתאמה אינה תלויה באותיות גדולות או קטנות. כל שם אחר מחזיר 400 unknown model, ולכן כלי ששולח שמות מודלים משלו חייב להיות מוגדר למזהה של Shannon. כל המודלים
messages array חובה. השיחה, ההודעה הישנה ביותר ראשונה, עם התפקידים user ו-assistant. ראו הודעות ובלוקי תוכן בהמשך. כל המודלים
system string | array הוראות למודל: מחרוזת או מערך של בלוקי טקסט. ראו System prompt בהמשך. מודלי open-weight מתארחים, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 הגבול העליון של התשובה, בטוקנים. אופציונלי ב-endpoint הזה; ה-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. ראו Streaming בהמשך. כל המודלים
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"}. ראו Tools בהמשך. כל המודלים
tool_choice object {"type": "auto"} נותן למודל להחליט, {"type": "any"} מחייב אותו לקרוא לכלי, {"type": "tool", "name": "…"} מחייב אותו לקרוא לכלי הזה. מודלי open-weight מתארחים
thinking object כמה המודל מנמק לפני שהוא עונה. ראו Thinking בהמשך. מודלי 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. פלט מובנה

בקשה עם הנחיית מערכת וחשיבה (thinking)

הבקשה הזו שולחת system prompt, תקציב thinking, טמפרטורה ו-stop sequence. היא משתמשת במודל 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 prompt

system הוא מחרוזת, או מערך של בלוקי טקסט בצורה [{"type": "text", "text": "…"}]. טקסטי הבלוקים מחוברים בירידת שורה.

הוא מיושם על ידי מודלי ה-open-weight המתארחים, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ו-shannon-coder-1. עם מזהה ממשפחת 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 האחרונה. לגדלים ולמגבלות יש דף משלהם. תמונות וקבצים

Thinking

מודלי ה-open-weight המתארחים ממפים את thinking לרמת מאמץ של reasoning. בלי השדה רמת המאמץ גבוהה.

צורה budget_tokens השפעה
{"type": "disabled"} בלי reasoning. בתשובה אין בלוק thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 מאמץ נמוך.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 מאמץ בינוני.
{"type": "enabled", "budget_tokens": 16000} > 8,192 מאמץ גבוה.

מודל שמנמק מחזיר את ה-reasoning שלו כבלוק {"type": "thinking", "thinking": "…"} לפני הטקסט. דרגי Shannon שמנמקים שולחים אותו גם כן.

רמות המאמץ מתוארות בדף משלהן. רמת מאמץ ה-reasoning

Tools

כלי הוא פונקציה שהקוד שלכם מריץ. תארו כל אחד עם 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 נקראים. חיפוש ברשת אינו כלי ב-endpoint הזה: הגדירו את השדה web_search.

לולאת הכלים מתוארת במלואה בדף משלה. קריאת פונקציות

התשובה

שדה סוג תיאור נשלח על ידי
id string msg_ ואחריו 32 תווים הקסדצימליים. כל המודלים
type string תמיד message. כל המודלים
role string תמיד assistant. כל המודלים
model string המזהה הקנוני של המודל שענה. כל המודלים
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. ב-stream הוא מגיע עם האירוע 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": "…"} ה-reasoning של המודל. אין בו שדה 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, ב-streams

Streaming

הגדירו את stream ל-true כדי לקבל server-sent events. בכל frame יש שורת event: עם שם האירוע ושורת data: עם אובייקט JSON שחוזר על השם ב-type. עוזרי ה-stream של ה-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 מכיל את המזהה, התפקיד, המודל, 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"} חלק מה-reasoning, עבור בלוק 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 בסדר פתיחתם, ובלוק אחד מושלם לפני שהבא נפתח. קראו כל בלוק לפי הסוג שלו, לא לפי המספר: stream יכול לפתוח קודם בלוק 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 שניות בזמן שהמודל עובד.

stream שנכשל

כשל אחרי תחילת ה-stream הוא אירוע 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.
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)

לספירה יש דף משלה, עם ה-endpoint לטקסט פשוט והמגבלות. ספירת טוקנים