דילוג לתוכן
Responses API

Responses API

חדש

POST /v1/responses מקבל הוראות ורשימת פריטי קלט ומחזיר אובייקט תשובה שמורכב מפריטי פלט, בפורמט OpenAI Responses. השתמשו בו עם ה-responses API של ה-SDK של OpenAI ועם כלים שנבנו עליו, כמו Codex CLI. ה-endpoint אינו שומר מצב: שלחו את כל השיחה בכל בקשה.

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

הבקשה הקטנה ביותר היא מזהה מודל וטקסט. התשובה אינה ב-streaming אלא אם תבקשו זאת.

from openai import OpenAI

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

response = client.responses.create(
    model="shannon-3",
    input="Say hello in one sentence.",
)

print(response.output_text)

התשובה היא אובייקט תשובה. ה-output שלו מכיל את ה-reasoning, כשהמודל נימק, ואת ההודעה:

200 JSON
{
  "id": "resp_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "response",
  "created_at": 1791625200,
  "model": "shannon-3",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "output": [
    {
      "id": "rs_8a2e6c1f4b7d4e03b9c5a1d70f3e2b64",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user wants a greeting in one sentence. Keep it short and friendly."
        }
      ]
    },
    {
      "id": "msg_1c7b9e3a5d2f4a86b0e4c8d19a6f7e25",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello, it is good to meet you.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46,
    "total_tokens": 1230
  }
}

שדות בקשה

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

שדה סוג ברירת מחדל תיאור מופעל על ידי
model string חובה. מזהה מרשימת המודלים. ההתאמה אינה תלויה באותיות גדולות או קטנות. מזהה חסר או שלא פורסם מחזיר 400 unknown model. כל המודלים
input string | array מחרוזת, שנקראת כהודעת משתמש אחת, או מערך של פריטי קלט. ראו פריטי קלט בהמשך. כל המודלים
instructions string הוראות למודל, ה-system prompt של הפורמט הזה. מודלי open-weight מתארחים, shannon-1.6-*, shannon-2-*, shannon-coder-1
stream boolean false true שולח את התשובה כ-server-sent events. ראו Streaming בהמשך. כל המודלים
max_output_tokens integer 4096 הגבול העליון של התשובה, בטוקנים. ערך מחוץ לטווח 1 עד 65,536 מועבר לתוך הטווח. זו גם הכמות שמופרשת מהיתרה שלכם בזמן שהבקשה רצה. ראו מגבלת פלט בהמשך. מודלי open-weight מתארחים, shannon-1.6-*, shannon-2-*, shannon-coder-1
temperature number טמפרטורת דגימה. במודלי ה-open-weight המתארחים הערכים נשמרים בין 0 ל-2. מודלי open-weight מתארחים; shannon-1.6-*, shannon-2-* ו-shannon-coder-1 בתשובות בלי streaming
top_p number דגימת Nucleus. הערכים נשמרים בין 0 ל-1. מודלי open-weight מתארחים
tools array הפונקציות שהמודל רשאי לקרוא להן, בצורה השטוחה של הפורמט הזה: {"type": "function", "name", "description", "parameters"}. ראו כלים בהמשך. כל המודלים
tool_choice string | object auto "auto" נותן למודל להחליט. "required" גורם לו לקרוא לכלי. {"type": "function", "name": "…"} גורם לו לקרוא לכלי הזה. מודלי open-weight מתארחים
reasoning object {"effort": "…"} עם off, low, medium או high. כל ערך אחר מחזיר 400. מודלי open-weight מתארחים
text object {"format": {…}} מבקש תשובת JSON. ראו פלט מובנה בהמשך. כל דרגות Shannon; מודלי open-weight מתארחים כפי שמפורט לכל מזהה

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ו-prompt_cache_key מתקבלים כדי שקוד לקוח קיים ירוץ ללא שינוי. הם אינם משנים את התשובה. מכיוון ששום שיחה אינה נשמרת, בקשת המשך נושאת את התורים הקודמים ב-input.

פריטי קלט

פריט קלט הוא או הודעה, עם role ו-content, או פריט מוקלד שנושא קריאה לכלי או את תוצאתה. content הוא מחרוזת או מערך של חלקים.

פריט תיאור מופעל על ידי
{"role": "user", "content": …} מה שאתם שואלים. content הוא מחרוזת, או חלקי input_text ו-input_image. כל המודלים
{"role": "assistant", "content": …} תשובה קודמת של המודל. content הוא מחרוזת, או חלקי output_text. כל המודלים
{"role": "system", "content": …}
{"role": "developer", "content": …}
הוראות בתוך השיחה. מודלי open-weight מתארחים
{"type": "function_call", "call_id": "…", "name": "…", "arguments": "…"} קריאה לכלי שהמודל ביצע בתשובה קודמת. arguments הוא מחרוזת JSON. כל המודלים
{"type": "function_call_output", "call_id": "…", "output": "…"} תוצאת הקריאה הזו. call_id הוא מזהה הקריאה ו-output התוצאה כמחרוזת. כל המודלים

שימו הוראות בשדה instructions. עם מזהה ממשפחת Shannon 3, שימו הוראות שחייבות להתקיים בהודעת ה-user.

אפשר להחזיר את הפריטים של output בתשובה ל-input כמות שהם: פריטי message ו-function_call נקראים, פריטי reasoning מדולגים.

חלקי תוכן

חלק תיאור זמין ב
{"type": "input_text", "text": "…"} טקסט של הודעת משתמש. כל המודלים
{"type": "output_text", "text": "…"} טקסט של הודעת assistant. כל המודלים
{"type": "input_image", "image_url": "…"} תמונה, כ-URL מסוג data: עם תוכן base64 או ככתובת http(s). משפחת Shannon 3, shannon-1.6-lite, shannon-1.6-pro, ומודלי ה-open-weight המתארחים שמציינים קלט תמונה
{"type": "input_file", "file_data": "data:application/pdf;base64,…"} מסמך (PDF, Word, PowerPoint או Excel): ב-file_data נמצא URL מסוג data:, או ב-file_url כתובת http(s). משפחת Shannon 3

בדרגות Shannon תמונות וקבצים נקראים מפריט ה-user האחרון ב-input. לגדלים ולמגבלות יש דף משלהם. תמונות וקבצים

בקשה עם הוראות ואפשרויות

הבקשה הזו שולחת הוראות, שיחה כפריטי קלט, מגבלת פלט, טמפרטורה ו-reasoning effort. היא משתמשת במודל open-weight מתארח, שמיישם את כולם.

from openai import OpenAI

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

response = client.responses.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    instructions="You are a physics teacher. Answer in two sentences.",
    input=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": "Air scatters blue light more than red light."},
        {"role": "user", "content": "And why are sunsets red?"},
    ],
    max_output_tokens=512,
    temperature=0.3,
    reasoning={"effort": "low"},
)

for item in response.output:
    if item.type == "reasoning":
        print("reasoning:", item.summary[0].text)
    elif item.type == "message":
        print("answer:", item.content[0].text)
print(response.usage)

לתשובה של מודל open-weight מתארח יש id, object, model, created_at, status, output ו-usage. ה-usage שלה מוסיף את הטוקנים שנקראו מהמטמון ואת הטוקנים שהושקעו ב-reasoning:

200 JSON
{
  "usage": {
    "input_tokens": 58,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 67,
    "output_tokens_details": {
      "reasoning_tokens": 19
    },
    "total_tokens": 125
  }
}

אובייקט התשובה

id, object, status, output ו-usage קיימים בכל תשובה. בנו את הקוד שלכם עליהם.

שדה סוג תיאור נשלח על ידי
id string resp_ ואחריו 32 תווים הקסדצימליים. כל המודלים
object string תמיד response. כל המודלים
status string completed. ב-stream הוא קודם in_progress, ו-failed באירוע response.failed. כל המודלים
output array פריטי הפלט בסדר שבו המודל הפיק אותם: reasoning, message, function_call. כל המודלים
usage object input_tokens, output_tokens ו-total_tokens. כל המודלים
usage.input_tokens_details object cached_tokens: טוקני הקלט שנקראו ממטמון הפרומפט. מודלי open-weight מתארחים
usage.output_tokens_details object reasoning_tokens: טוקני הפלט שהושקעו ב-reasoning. מודלי open-weight מתארחים
model string המזהה הקנוני של המודל שענה. משפחת Shannon 3, מודלי open-weight מתארחים
created_at integer זמן התשובה, בשניות Unix. משפחת Shannon 3, מודלי open-weight מתארחים
instructions, tools, temperature, … instructions, tools ו-temperature חוזרים על הבקשה. error ו-incomplete_details הם null, metadata הוא {}, parallel_tool_calls הוא true, tool_choice הוא auto ו-top_p הוא null. משפחת Shannon 3

פריטי פלט

פריט תיאור
{"id": "rs_…", "type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} ה-reasoning של המודל כחלק summary_text אחד. קיים רק כשהמודל נימק.
{"id": "msg_…", "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "…"}]} התשובה: חלק output_text אחד עם הטקסט.
{"id": "fc_…", "type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"} קריאה לכלי. arguments הוא מחרוזת JSON. שלחו את התוצאה בחזרה עם אותו call_id.

ה-SDK של OpenAI מחברים עבורכם את הטקסט של ההודעה ב-response.output_text.

Streaming

קבעו stream ל-true כדי לקבל server-sent events. לכל frame יש שורת event: עם שם האירוע ושורת data: עם אובייקט JSON; האובייקט חוזר על השם ב-type. התאימו deltas לפריט שלהם לפי output_index.

עם ה-SDK של OpenAI, קראו את האירועים לפי ה-type שלהם:

from openai import OpenAI

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

stream = client.responses.create(
    model="shannon-3",
    input="Explain server-sent events in three sentences.",
    stream=True,
)

for event in stream:
    kind = getattr(event, "type", "error")     # an event without a type is an error event
    if kind == "response.reasoning_summary_text.delta":
        pass                                   # a piece of reasoning: event.delta
    elif kind == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif kind == "response.output_item.done" and event.item.type == "function_call":
        print("\ntool call:", event.item.name, event.item.arguments)
    elif kind == "response.completed":
        print("\n", event.response.usage)
    elif kind in ("response.failed", "error"):
        raise RuntimeError("the stream failed, send the request again")

האירועים מגיעים בסדר הזה. הקבוצות של reasoning, ההודעה וקריאות הכלים מופיעות רק כשיש אותן בתשובה.

אירוע תוכן מתי
response.created response תמיד ראשון. response.status הוא in_progress ו-response.output ריק.
response.in_progress response תמיד שני, עם אותו אובייקט.
response.output_item.added output_index, item ה-reasoning מתחיל: פריט reasoning עם summary ריק.
response.reasoning_summary_text.delta output_index, summary_index, delta חתיכה מה-reasoning.
response.reasoning_summary_text.done output_index, summary_index, text ה-reasoning שלם: כל ה-text שלו.
response.output_item.done output_index, item פריט ה-reasoning שהסתיים.
response.output_item.added output_index, item התשובה מתחילה: פריט message בסטטוס in_progress וללא תוכן.
response.content_part.added output_index, content_index, part חלק output_text ריק נפתח.
response.output_text.delta output_index, content_index, delta חתיכה מהתשובה.
response.output_text.done output_index, content_index, text התשובה שלמה: כל ה-text שלה.
response.content_part.done output_index, content_index, part חלק ה-output_text שהסתיים.
response.output_item.done output_index, item פריט ה-message שהסתיים, בסטטוס completed.
response.output_item.added output_index, item קריאה לכלי מתחילה: פריט function_call עם call_id, name ו-arguments ריק.
response.function_call_arguments.delta output_index, delta הארגומנטים של הקריאה, שלמים ב-delta אחד.
response.function_call_arguments.done output_index, arguments אותם ארגומנטים, כ-arguments.
response.output_item.done output_index, item פריט ה-function_call שהסתיים.
response.completed response תמיד אחרון בהצלחה: אובייקט התשובה כולו עם output ו-usage.
200 text/event-stream
event: response.created
data: {"type":"response.created","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Server-sent"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" events let a server push text over one HTTP reply."}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Server-sent events let a server push text over one HTTP reply."}

event: response.content_part.done
data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_5f0c…","object":"response","status":"completed","output":[…],"usage":{"input_tokens":1190,"output_tokens":18,"total_tokens":1208}, …}}

stream שנכשל

בדרגות Shannon תשובה שנכשלה מסתיימת ב-response.failed במקום response.completed. ה-response.status שלה הוא failed ו-response.error מכיל code, rate_limit_exceeded או server_error, ו-message.

במודלי ה-open-weight המתארחים כשל הוא אירוע error עם code בערך api_error ו-message. response.completed עדיין בא אחריו.

התייחסו ל-stream ככושל כשהוא מכיל אירוע response.failed או error, ושלחו את הבקשה שוב.

כלים

כלי הוא פונקציה שהקוד שלכם מריץ. תארו אותו ב-tools; כשהמודל רוצה בו, התשובה מכילה פריט function_call במקום ההודעה או לצדה.

הגדרת כלי ב-tools:

tools
[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

ה-output של תשובה שקוראת לו:

200 output
[
  {
    "id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "arguments": "{\"city\":\"Paris\"}"
  }
]

הריצו את הפונקציה, ואז שלחו שוב את הבקשה כשהקריאה ותוצאתה מתווספות ל-input:

input
[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "type": "function_call",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "arguments": "{\"city\":\"Paris\"}"
  },
  {
    "type": "function_call_output",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "output": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
  }
]

רק כלים מסוג function נקראים. ב-shannon-1.6-*, ב-shannon-2-* וב-shannon-coder-1 הסכמה parameters מצטמצמת למילות המפתח המשותפות של JSON Schema: oneOf נקרא כ-anyOf, ומילות מפתח כמו $ref, additionalProperties, const, default ו-title אינן מועברות למודל.

הערכים required ופונקציה בשם של tool_choice מיושמים על ידי מודלי ה-open-weight המתארחים.

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

פלט מובנה

הפורמט הזה מאיית פלט מובנה כ-text.format. הסכמה יושבת ישירות ב-format, לצד name ו-strict, ולא תחת איבר json_schema כמו ב-Chat Completions.

  • {"type": "json_object"} מבקש כל אובייקט JSON.
  • {"type": "json_schema", "name", "schema", "strict"} מבקש JSON שעוקב אחרי הסכמה שלכם. strict הוא true כשמשמיטים אותו.
POST /v1/responses
{
  "model": "shannon-1.6-lite",
  "input": "Extract the city and the date: 'The conference opens in Lisbon on 12 May 2027.'",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "event",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "ISO 8601 date"
          }
        },
        "required": [
          "city",
          "date"
        ]
      }
    }
  }
}

ה-JSON מגיע כטקסט בחלק output_text של ההודעה; פענחו אותו בעצמכם. מודל open-weight מתארח בלי פלט מובנה מחזיר 400.

output_text
{"city": "Lisbon", "date": "2027-05-12"}

איזה מודל מקבל איזו צורה מפורט בדף משלה. פלט מובנה

Reasoning

מודל שמנמק מחזיר את ה-reasoning שלו כפריט פלט מסוג reasoning, לפני ההודעה. ב-stream הוא מגיע כאירועי response.reasoning_summary_text.delta.

מודלי ה-open-weight המתארחים מיישמים את reasoning.effort: off, low, medium או high, עם high כשאתם לא שולחים דבר. off אינו מחזיר פריט reasoning. שלחו אותו כאובייקט; מחרוזת פשוטה אינה נקראת ב-endpoint הזה.

ה-efforts מתוארים בדף משלהם. רמת מאמץ ה-reasoning

מגבלת פלט

max_output_tokens הוא 4,096 כשאתם לא שולחים אותו. זה מספר הטוקנים שמופרשים מהיתרה שלכם כשהבקשה מתחילה; כשהתשובה שלמה, הסכום הזה מוחלף במה שהבקשה השתמשה בו. ערך שאינו נכנס ביתרה שנותרה לכם מחזיר 429 Quota exceeded.

הוא מגביל את אורך התשובה ב-shannon-1.6-*, ב-shannon-2-* וב-shannon-coder-1, ואת אורך טקסט התשובה במודלי ה-open-weight המתארחים.

ב-endpoint הזה shannon-coder-1 מחויב בטוקנים מהיתרה שלכם, כמו כל מודל אחר.

גוף בקשה יכול להגיע עד 32 MiB. מגבלות ויתרה

שגיאות

שגיאות משתמשות בגוף השגיאה של OpenAI: אובייקט error עם type ו-message; בחלקן יש גם code ו-param עם הערך null. הטבלה מפרטת מה ה-endpoint הזה מחזיר לרוב. לרשימה המלאה, עם מה לנסות שוב, יש דף משלה. טיפול בשגיאות

סטטוס סוג הודעה מתי
401 authentication_error Missing authentication
Invalid API key
לא נשלח מפתח API, או שהמפתח לא מוכר או בוטל.
400 invalid_request_error unknown model: <id> model חסר או אינו מזהה שפורסם.
400 invalid_request_error No user message provided. דרגות Shannon: ב-input אין טקסט משתמש.
400 invalid_request_error <id> does not accept image input תמונה נשלחה למודל open-weight מתארח בלי קלט תמונה.
400 invalid_request_error <id> does not accept response_format text.format נשלח למודל open-weight מתארח בלי פלט מובנה.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high reasoning.effort מכיל ערך מחוץ לרשימה.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … הגוף הוא JSON תקין, אבל לשדה יש סוג שגוי.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_output_tokens גדול ממה שנשאר מהיתרה שלכם.
429 rate_limit_error Too many requests. Retry in <n>s. הגנת הצפה: יותר מ-120 בקשות בדקה אחת בחשבון שלכם.
500 api_error The model backend failed to answer. Please retry. המודל לא הפיק תשובה. שלחו את הבקשה שוב.
502 api_error The model backend failed to answer. Please retry. אותו דבר, במודלי ה-open-weight המתארחים.
504 api_error upstream timed out מודל open-weight מתארח לקח יותר זמן ממגבלת הזמן של תשובה בלי streaming. שלחו אותה עם stream שנקבע ל-true.