דילוג לתוכן
סקירה

סקירה

מפת ה-API: כל endpoint, איך נראות בקשה ושגיאה, איך משלמים על קריאות, ומה כדאי לדעת כשבאים מ-SDK של OpenAI או של Anthropic.

Endpoints

כל endpoint נמצא תחת base URL אחד ומוגש ב-HTTPS.

Base URL 
https://api.shannon-ai.com
Endpoint פורמט למה זה משמש
POST /v1/chat/completions OpenAI Chat Completions שלחו שיחה, קבלו את התשובה הבאה. עם streaming או בלעדיו.
POST /v1/messages Anthropic Messages אותו דבר, בצורות הבקשה והתשובה של ה-SDK של Anthropic.
POST /v1/responses OpenAI Responses אותו דבר, בצורות של Responses. ה-endpoint אינו שומר מצב: שלחו את השיחה בכל בקשה.
GET /v1/models רשימת מודלים של OpenAI רשימת המודלים עם חלון הקשר, מחירים ויכולות. אינו צריך מפתח.
POST /v1/tokenize Shannon API ספירת הטוקנים של טקסט או של בקשת צ'אט עבור מודל open-weight מתארח. חינם.
POST /v1/messages/count_tokens ספירת טוקנים של Anthropic ספירת טוקני הקלט של בקשת Messages עבור מודל open-weight מתארח. חינם.

שלושת ה-endpoints שמפיקים טקסט מגיעים לאותם מודלים. בחרו את זה שהפורמט שלו כבר בשימוש בקוד שלכם.

יסודות הבקשה

כותרת תיאור
Authorization: Bearer <key> מפתח ה-API שלכם. חובה בכל endpoint חוץ מ-GET /v1/models, אלא אם אתם שולחים x-api-key.
x-api-key: <key> אותו מפתח בכותרת ש-SDK של Anthropic שולחים. נקרא בכל endpoint.
Content-Type: application/json חובה בכל POST. בלעדיה התשובה היא 415.
x-request-id: <your id> אופציונלי. מזהה משלכם לבקשה; הוא חוזר בכותרת התשובה x-request-id. בלעדיו ה-API יוצר מזהה של 12 תווים הקסדצימליים.
  • הגוף של כל POST הוא אובייקט JSON אחד, עד 32 MiB.
  • שדה שה-API אינו מכיר אינו גורם לשגיאה ואין לו השפעה. בקשה שנכתבה לספק אחר אינה נכשלת בגלל שדה נוסף.
  • שדה מוכר עם סוג JSON שגוי, או שדה חובה חסר, נענה ב-422. גוף שאינו JSON תקין נענה ב-400.
  • model הוא אחד המזהים בדף מודלים ותמחור. אותיות גדולות וקטנות אינן משנות.

תשובה היא JSON, או stream של server-sent events כשהבקשה קובעת stream ל-true. כל endpoint עונה בפורמט שלו. בכל תשובה יש את הכותרת x-request-id.

מה בקשה עוברת

בקשה נבדקת בסדר קבוע לפני שמודל רץ. הבדיקה הראשונה שנכשלת היא שעונה, ולכן 401 עדיין אינו אומר דבר על הגוף.

נבדק, בסדר הזה סטטוס בכשל
מפתח API 401
גוף: גודל, content type, JSON, סוגי שדות 413 · 415 · 400 · 422
מזהה מודל 400
הגנת הצפה: 120 בקשות בדקה לחשבון 429
יתרה: תקציב הפלט של הבקשה חייב להיכנס 429

צורת שגיאה

שגיאה היא אובייקט JSON עם error שמכיל type ו-message. /v1/messages עוטף אותה כמו ש-SDK של Anthropic מצפים; כל נתיב אחר משתמש בצורת OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}
  • קראו את type ואת message. code ו-param קיימים רק בחלק מהשגיאות: התייחסו אליהם כאופציונליים. param הוא תמיד null.
  • אחרי שה-stream התחיל, הסטטוס כבר 200. כשל מגיע אז כ-error frame בתוך ה-stream.
  • כל תשובת שגיאה נושאת את הכותרת x-request-id.
סטטוס סוג מתי
400 invalid_request_error הגוף אינו JSON תקין, מזהה המודל לא מוכר, או שהמודל אינו מקבל סוג קלט ששלחתם.
401 authentication_error המפתח חסר או אינו תקין.
404 not_found_error הנתיב אינו קיים.
405 api_error הנתיב קיים, השיטה שגויה.
413 invalid_request_error הגוף גדול מ-32 MiB.
415 invalid_request_error Content-Type אינו application/json.
422 invalid_request_error שדה מכיל סוג JSON שגוי או שדה חובה חסר.
429 rate_limit_error היתרה אינה מכסה את הבקשה, יותר מ-120 בקשות הגיעו בדקה, קריאות Shannon Coder של החלון נוצלו, או שהמודל עסוק. ההודעה אומרת איזה מהם.
5xx api_error סטטוס 500, 502, 503 או 504: הבקשה הייתה תקינה ולא ניתן היה לענות עליה. שלחו אותה שוב. 500 יכול לשאת את הסוג server_error.

טיפול בשגיאות

חיוב ויתרה

  • יש יתרה אחת לכל חשבון, והצ'אט וה-API חולקים אותה: קודם מכסת התוכנית להיום, אחר כך קרדיט שנרכש. ל-API אין מכסה משלו.
  • בקשה מפרישה את תקציב הפלט שלה (max_tokens, ברירת מחדל 4,096) ואחר כך מחויבת על הטוקנים ששימשו בפועל, במחיר המודל.
  • כל תשובה מדווחת על ספירות הטוקנים שלה ב-usage. הדף מפתחות ושימוש מראה את היתרה ומה עלתה כל בקשה.
  • כל בקשה מטופלת באופן שווה. המגבלה היחידה על קצב הבקשות היא הגנת הצפה: 120 בקשות בדקה לחשבון. בקשות שנשלחות במקביל ממתינות בתור.

מגבלות ויתרה מודלים ותמחור מפתחות ושימוש

שדות שתלויים במודל

כל מודל מקבל את אותה בקשה. כמה שדות משפיעים רק בחלק מהמודלים; הטבלה נוקבת היכן. דפי ה-endpoints מפרטים כל שדה.

שדה תיאור מופעל על ידי
system הוראות למודל: הודעת system ב-Chat Completions, system ב-Messages, instructions ב-Responses. מודלי open-weight מתארחים, shannon-1.6-*, shannon-2-*, shannon-coder-1
temperature טמפרטורת דגימה. מודלי open-weight מתארחים, shannon-1.6-*, shannon-coder-1
top_p דגימת Nucleus. מודלי open-weight מתארחים
seed זרע קבוע לדגימה. מודלי open-weight מתארחים
stop עד 4 רצפי עצירה. מודלי open-weight מתארחים
reasoning_effort כמה המודל מנמק לפני שהוא עונה. reasoning.effort ב-Responses, thinking ב-Messages. מודלי open-weight מתארחים
web_search true מאפשר למודל לחפש ברשת עבור הבקשה הזו. שדה של ה-API הזה, ב-Chat Completions וב-Messages. מודלי Shannon חוץ מ-shannon-coder-1
max_tokens תקציב הפלט. בכל מודל הוא קובע את הסכום שמופרש מהיתרה שלכם. כמגבלה על אורך התשובה: מודלי open-weight מתארחים, shannon-1.6-*, shannon-coder-1

Chat Completions

אם אתם באים מ-SDK של OpenAI

  • קבעו את ה-base URL ל-https://api.shannon-ai.com/v1 ואת המפתח למפתח Shannon שלכם. קריאות Chat Completions ו-Responses עובדות אז עם ה-SDK כפי שהוא.
  • model חייב להיות מזהה Shannon. שם מודל של ספק אחר, כמו gpt-4o, נענה ב-400 וב-unknown model.
  • ה-reasoning מגיע בשדה משלו: reasoning_content לצד content, בהודעה ובדלתות ה-stream.
  • stream נושא תמיד usage ב-chunk האחרון שלו, יחד עם finish_reason.
  • קריאה לכלי ב-stream מגיעה כ-chunk אחד עם מחרוזת arguments שלמה.
  • בתשובה יש choice אחד.
  • נתיבים של ה-API של OpenAI שאינם בטבלה שלמעלה, כמו /v1/embeddings, נענים ב-404.

אם אתם באים מ-SDK של Anthropic

  • קבעו את ה-base URL ל-https://api.shannon-ai.com, בלי /v1, ואת המפתח למפתח Shannon שלכם. ה-SDK שולח אותו כ-x-api-key.
  • model חייב להיות מזהה Shannon.
  • max_tokens הוא אופציונלי ב-API הזה. ברירת המחדל שלו היא 4,096.
  • תשובה מכילה בלוקי תוכן מהסוגים thinking, text ו-tool_use. הבלוק הראשון אינו תמיד הטקסט: בחרו בלוקים לפי type.
  • stop_reason הוא end_turn או tool_use. stream של מודל Shannon יכול להסתיים גם ב-max_tokens.
  • anthropic-version ו-anthropic-beta מתקבלים, כך שה-SDK עובד ללא שינוי. בקשה אינה צריכה אותם.
  • שגיאות ב-/v1/messages הן בצורת Anthropic: {"type": "error", "error": {…}}.

כלי קידוד שמדברים בפורמטים האלה מוגדרים באותו אופן: base URL, מפתח, ומזהה Shannon כמודל. כלי קידוד ב-CLI