התחלה מהירה
בצעו בקשה ראשונה: קבלו מפתח, שלחו הודעה אחת וקראו את התשובה. ה-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) import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com/v1'
});
const response = await client.chat.completions.create({
model: 'shannon-3',
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
],
max_tokens: 1024
});
console.log(response.choices[0].message.content); package main
import (
"context"
"fmt"
openai "github.com/sashabaranov/go-openai"
)
func main() {
config := openai.DefaultConfig("YOUR_API_KEY")
config.BaseURL = "https://api.shannon-ai.com/v1"
client := openai.NewClientWithConfig(config)
resp, err := client.CreateChatCompletion(
context.Background(),
openai.ChatCompletionRequest{
Model: "shannon-3",
Messages: []openai.ChatCompletionMessage{
{Role: "user", Content: "Hello, Shannon!"},
},
MaxTokens: 1024,
},
)
if err != nil {
panic(err)
}
fmt.Println(resp.Choices[0].Message.Content)
} curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
],
"max_tokens": 1024
}' | שדה | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
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 אחד כשהתשובה שלמה. הטקסטים והמספרים שלהלן הם דוגמאות.
{
"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) import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.shannon-ai.com/v1'
});
const stream = await client.chat.completions.create({
model: 'shannon-3',
messages: [
{ role: 'user', content: 'Hello, Shannon!' }
],
max_tokens: 1024,
stream: true
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
} curl -N -X POST "https://api.shannon-ai.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [
{"role": "user", "content": "Hello, Shannon!"}
],
"max_tokens": 1024,
"stream": true
}' כל frame של ה-stream הוא שורה אחת שמתחילה ב-data: ומכילה אובייקט JSON. 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 | תקציב הפלט של הבקשה אינו נכנס ביתרה שלכם. |
לאן ללכת הלאה
- מודלים ותמחור — בחרו מודל: מזהים, חלונות הקשר ומחירים.
- Chat Completions — כל שדה בקשה, שדה תשובה ואירוע stream של ה-endpoint שקראתם לו.
- הזרמה — ה-frames של stream, שורות keep-alive ושגיאות בתוך stream.
- קריאת פונקציות — תנו למודל לקרוא לפונקציות שלכם.
- מגבלות ויתרה — מה בקשה מפרישה ומה היא עולה, וכמה בקשות מותר לשלוח.
- מגרש משחקים API — נסו בקשות בדפדפן עם המפתח שלכם.