דילוג לתוכן
התחלה מהירה

התחלה מהירה

בצעו בקשה ראשונה: קבלו מפתח, שלחו הודעה אחת וקראו את התשובה. ה-API מדבר בפורמטים של OpenAI ושל Anthropic, ולכן ה-SDK שאתם כבר משתמשים בו עובד אחרי שתחליפו את ה-base URL ואת המפתח שלו.

1. קבלו את המפתח

לכל חשבון יש מפתח API אחד. היכנסו, פתחו את מפתחות ושימוש והעתיקו אותו. המפתח עובד בכל endpoint ובכל מודל. מפתחות ושימוש

2. כוונו את הלקוח ל-API

כל ה-endpoints נמצאים תחת base URL אחד. SDK של OpenAI לוקח אותו עם /v1 בסוף; SDK של Anthropic לוקח אותו בלי, כי הוא מוסיף /v1/messages בעצמו.

לקוח Base URL
SDK של OpenAI ולקוחות תואמי OpenAI https://api.shannon-ai.com/v1
SDK של Anthropic https://api.shannon-ai.com

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

Endpoint פורמט
POST /v1/chat/completions OpenAI Chat Completions
POST /v1/messages Anthropic Messages
POST /v1/responses OpenAI Responses

3. שלחו בקשה ראשונה

שלחו הודעת user אחת ל-shannon-3 ב-endpoint של Chat Completions. החליפו את YOUR_API_KEY במפתח שלכם.

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024
)

print(response.choices[0].message.content)
שדה סוג ברירת מחדל תיאור
model string מזהה המודל שעונה. המזהים מפורטים בדף מודלים ותמחור.
messages array השיחה עד כה: אובייקטים עם role ו-content. הודעת ה-user האחרונה היא הפרומפט. חובה.
max_tokens integer 4096 תקציב הפלט של הבקשה, מ-1 עד 65,536. הבקשה מפרישה סכום זה מהיתרה שלכם ומחויבת על מה שהשתמשה בו בפועל.
stream boolean false true שולח את התשובה חתיכה אחר חתיכה בזמן שהיא נכתבת.

גוף הבקשה הוא JSON וצריך את הכותרת Content-Type: application/json. הרשימה המלאה של השדות נמצאת בדף ה-endpoint. Chat Completions

התשובה

קריאה בלי stream מחזירה אובייקט JSON אחד כשהתשובה שלמה. הטקסטים והמספרים שלהלן הם דוגמאות.

200 JSON
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}
שדה סוג תיאור
id string chatcmpl- ואחריו 32 תווים הקסדצימליים.
object string תמיד chat.completion.
created integer זמן התשובה בשניות Unix.
model string המזהה שפורסם של המודל שענה, גם כששלחתם כינוי או איות אחר.
choices array תמיד פריט אחד, עם index 0.
choices[0].message.role string תמיד assistant.
choices[0].message.content string | null התשובה. היא יכולה להיות null כשהתשובה נושאת tool_calls.
choices[0].message.reasoning_content string | null ה-reasoning של המודל לפני התשובה, או null כשאין.
choices[0].message.tool_calls array קיים רק כשהמודל קורא לאחד הכלים שהצהרתם עליהם.
choices[0].finish_reason string stop לתשובה, tool_calls כשהמודל קורא לכלי.
usage.prompt_tokens integer הטוקנים שהמודל קרא לצורך התשובה הזו. ב-shannon-2-* ובמשפחת Shannon 3 זה יכול להיות יותר מהטקסט ששלחתם.
usage.completion_tokens integer הטוקנים שהמודל כתב.
usage.total_tokens integer הסך הכול. החיוב של מודל Shannon מחושב ממספר זה.
  • usage מכיל ספירות טוקנים, לא כסף. מה שהקריאה לקחה מהיתרה שלכם מוצג לכל בקשה בדף מפתחות ושימוש; איך זה מחושב נמצא בדף מגבלות ויתרה. מגבלות ויתרה
  • בכל תשובה, גם שגיאה ו-stream, יש את הכותרת x-request-id. אם הבקשה שלכם נושאת כותרת x-request-id, הערך שלה חוזר; אחרת הערך הוא 12 תווים הקסדצימליים. שמרו אותו בלוגים שלכם: הוא מזהה את הבקשה הזו בלבד.

אותה קריאה כ-stream

קבעו stream ל-true כדי לקרוא את התשובה בזמן שהיא נכתבת. כל השאר בבקשה נשאר כשהיה.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

כל frame של ה-stream הוא שורה אחת שמתחילה ב-data: ומכילה אובייקט JSON. Frame אחד, מודפס בכמה שורות:

Frame אחד
{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}
Frames, לפי הסדר delta finish_reason
בזמן שהמודל מנמק. אפס frames או יותר. {"reasoning_content": "…"} null
התשובה, חתיכה אחר חתיכה. אפס frames או יותר. {"content": "…"} null
ה-frame האחרון של JSON. הוא נושא גם usage; אין צורך לבקש אותו. {} "stop"
סוף ה-stream: השורה data: [DONE].
  • לתשובה יש סטטוס 200 ו-content-type: text/event-stream. כל frame הוא שורה data: <json> ואחריה שורה ריקה.
  • שורה : ping מגיעה כל 15 שניות. זו הערה ששומרת את החיבור פתוח; לקוחות SSE מדלגים עליה.
  • כשל אחרי שה-stream נפתח מגיע כ-frame בצורה data: {"error": {…}}. הסטטוס נשאר 200, ולכן בדקו את ה-frames.

הזרמה

אם הקריאה נכשלת

שגיאה היא אובייקט JSON עם error שמכיל type ו-message. אלה התשובות שקריאה ראשונה פוגשת לרוב.

סטטוס סוג הודעה מה זה אומר
401 authentication_error Missing authentication אף מפתח לא הגיע ל-API. שלחו Authorization: Bearer ואחריו המפתח שלכם.
401 authentication_error Invalid API key המפתח אינו המפתח הנוכחי של חשבון. העתיקו אותו שוב מדף מפתחות ושימוש.
400 invalid_request_error unknown model: <id> model אינו מזהה שפורסם. השתמשו במזהה מדף מודלים ותמחור.
422 invalid_request_error Failed to deserialize the JSON body into the target type… שדה מכיל סוג JSON שגוי, או ש-messages חסר.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan תקציב הפלט של הבקשה אינו נכנס ביתרה שלכם.

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

לאן ללכת הלאה