منځپانګې ته ټوپ ووهئ
Responses API

Responses API

نوی

POST /v1/responses لارښوونې او د input توکو لیست اخلي او د OpenAI Responses په بڼه د output توکو څخه جوړ شوی response څیز بیرته ورکوي. دا د OpenAI SDK د responses API سره او هغو tools سره وکاروئ چې پر دې جوړ شوي، لکه Codex CLI. endpoint هیڅ حالت نه ساتي: ټوله ګفتګه له هرې غوښتنې سره ولیږئ.

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

تر ټولو کوچنۍ غوښتنه د ماډل id او یو متن دی. ځواب stream نه وي مګر دا چې تاسو یې وغواړئ.

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)

ځواب د response څیز دی. د هغه output reasoning لري، کله چې ماډل reasoning کړی وي، او message:

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 ماډلونه د ماډل لیست دولس id ګانې دي؛ د Shannon 3 کورنۍ shannon-3، shannon-3-pro، shannon-3.1 او shannon-3.1-pro ده. ماډلونه او بیې

ساحه ډول تلواله تشریح پلي کوونکی
model string اړین. د ماډل لیست id. سمون د توري د کوچنۍ یا لویې کیدو پروا نه کوي. هغه id چې نشته یا خپور شوی نه وي 400 unknown model بیرته ورکوي. ټول ماډلونه
input string | array یو string، چې د یو user message په توګه لوستل کیږي، یا د input توکو لړۍ. لاندې Input items وګورئ. ټول ماډلونه
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 بهر ارزښت ددې لړۍ دننه کیږي. دا هم هغه مقدار دی چې غوښتنې د چلیدو پر مهال ستاسو له بیلانس څخه ساتل کیږي. لاندې Output limit وګورئ. کوربه شوي open-weight ماډلونه، shannon-1.6-*، shannon-2-*، shannon-coder-1
temperature number د sampling temperature. په کوربه شوو open-weight ماډلونو کې ارزښتونه د 0 او 2 ترمنځ ساتل کیږي. کوربه شوي open-weight ماډلونه؛ shannon-1.6-*، shannon-2-* او shannon-coder-1 په هغو ځوابونو کې چې stream نه وي
top_p number Nucleus sampling. ارزښتونه د 0 او 1 ترمنځ ساتل کیږي. کوربه شوي open-weight ماډلونه
tools array هغه functions چې ماډل یې غوښتلی شي، د دې بڼې په ساده شکل کې: {"type": "function", "name", "description", "parameters"}. لاندې Tools وګورئ. ټول ماډلونه
tool_choice string | object auto "auto" ماډل ته پریکړه پریږدي. "required" ماډل مجبوروي چې tool وغواړي. {"type": "function", "name": "…"} یې مجبوروي چې همغه tool وغواړي. کوربه شوي open-weight ماډلونه
reasoning object {"effort": "…"} د off، low، medium یا high سره. هر بل ارزښت 400 بیرته ورکوي. کوربه شوي open-weight ماډلونه
text object {"format": {…}} د JSON ځواب غواړي. لاندې Structured output وګورئ. د Shannon ټولې کچې؛ کوربه شوي open-weight ماډلونه لکه د هر id په اړه لیست شوي

previous_response_id، store، metadata، parallel_tool_calls، truncation، include، user او prompt_cache_key منل کیږي ترڅو شته client کوډ بې بدلون چلیږي. دوی ځواب نه بدلوي. ځکه چې هیڅ ګفتګه نه ساتل کیږي، راتلونکې غوښتنه پخواني turns په input کې لیږدوي.

د input توکي

د input توکی یا message دی، د role او content سره، یا ډول لرونکی توکی چې tool call یا د هغه پایله لیږدوي. content یو string یا د برخو لړۍ ده.

توکی تشریح پلي کوونکی
{"role": "user", "content": …} هغه څه چې تاسو یې پوښتئ. content یو string دی، یا input_text او input_image برخې. ټول ماډلونه
{"role": "assistant", "content": …} د ماډل پخوانی ځواب. content یو string دی، یا output_text برخې. ټول ماډلونه
{"role": "system", "content": …}
{"role": "developer", "content": …}
په ګفتګه دننه لارښوونې. کوربه شوي open-weight ماډلونه
{"type": "function_call", "call_id": "…", "name": "…", "arguments": "…"} د tool call چې ماډل په پخواني ځواب کې وکړ. arguments د JSON string دی. ټول ماډلونه
{"type": "function_call_output", "call_id": "…", "output": "…"} د هغه call پایله. call_id د call id دی او output پایله د string په توګه. ټول ماډلونه

لارښوونې د instructions په ساحه کې ږدئ. د Shannon 3 کورنۍ id سره، هغه لارښوونې چې باید وساتل شي user message کې ولیکئ.

د ځواب د output توکي کولی شي هماغسې بیرته input ته لاړ شي: message او function_call توکي لوستل کیږي، reasoning توکي پرېښودل کیږي.

د منځپانګې برخې

برخه تشریح شتون لري په
{"type": "input_text", "text": "…"} د کاروونکي د پیغام متن. ټول ماډلونه
{"type": "output_text", "text": "…"} د assistant د پیغام متن. ټول ماډلونه
{"type": "input_image", "image_url": "…"} یو انځور، د data: URL په توګه د base64 منځپانګې سره یا د http(s) URL په توګه. د Shannon 3 کورنۍ، shannon-1.6-lite، shannon-1.6-pro، او کوربه شوي open-weight ماډلونه چې انځور input لیست کوي
{"type": "input_file", "file_data": "data:application/pdf;base64,…"} سند (PDF، Word، PowerPoint یا Excel): په file_data کې data: URL ځای لري، یا په file_url کې http(s) URL. د Shannon 3 کورنۍ

د Shannon په کچو کې انځورونه او فایلونه د input له وروستي user توکي لوستل کیږي. اندازې او حدونه خپله جلا پاڼه لري. انځورونه او فایلونه

غوښتنه د لارښوونو او اختیارونو سره

دا غوښتنه لارښوونې، ګفتګه د input توکو په توګه، د output حد، temperature او 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 له cache څخه لوستل شوي ټوکنونه او هغه ټوکنونه زیاتوي چې په 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 وي، او په response.failed رخداد کې failed. ټول ماډلونه
output array د output توکي په هماغه ترتیب چې ماډل جوړ کړي: reasoning، message، function_call. ټول ماډلونه
usage object input_tokens، output_tokens او total_tokens. ټول ماډلونه
usage.input_tokens_details object cached_tokens: هغه input ټوکنونه چې د prompt cache څخه لوستل شوي. کوربه شوي open-weight ماډلونه
usage.output_tokens_details object reasoning_tokens: هغه output ټوکنونه چې په reasoning لګیدلي. کوربه شوي open-weight ماډلونه
model string د هغه ماډل canonical id چې ځواب یې ورکړ. د 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 کورنۍ

د output توکي

توکی تشریح
{"id": "rs_…", "type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} د ماډل reasoning د یوې summary_text برخې په توګه. یوازې هغه وخت شتون لري کله چې ماډل reasoning کړی وي.
{"id": "msg_…", "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "…"}]} ځواب: یوه output_text برخه د متن سره.
{"id": "fc_…", "type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"} Tool call. arguments د JSON string دی. پایله د همدې call_id سره بیرته ولیږئ.

OpenAI SDKs د message متن ستاسو لپاره په response.output_text کې یوځای کوي.

Streaming

د server-sent events لپاره stream په true وټاکئ. هر frame د رخداد نوم سره یوه event: کرښه او د JSON څیز سره یوه data: کرښه لري؛ څیز نوم په type کې تکراروي. Deltas د output_index په واسطه د هغوی له توکي سره سمون ورکړئ.

د OpenAI SDK سره، رخدادونه د هغوی د 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، message او tool calls ګروپونه یوازې هغه وخت ښکاري کله چې ځواب یې لري.

رخداد Payload کله
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 Tool call پیلیږي: function_call توکی د call_id، name او خالي arguments سره.
response.function_call_arguments.delta output_index, delta د call آرګومنټونه، په یوه delta کې بشپړ.
response.function_call_arguments.done output_index, arguments همدا آرګومنټونه، د arguments په توګه.
response.output_item.done output_index, item بشپړ شوی function_call توکی.
response.completed response په بریا کې تل وروستی: ټول 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.completed پر ځای په response.failed پای ته رسیږي. د هغه 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

Tool یوه function ده چې ستاسو کوډ یې چلوي. دا په tools کې بیان کړئ؛ کله چې ماډل یې غواړي، ځواب د message پر ځای، یا ورسره، function_call توکی لري.

په tools کې د tool تعریف:

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

د هغه ځواب output چې tool غواړي:

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

function وچلوئ، بیا غوښتنه بیا ولیږئ او call او د هغه پایله 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 tools لوستل کیږي. په shannon-1.6-*، shannon-2-* او shannon-coder-1 کې parameters schema عامو JSON Schema کلیدي کلمو ته کم کیږي: oneOf د anyOf په توګه لوستل کیږي، او کلیدي کلمې لکه $ref، additionalProperties، const، default او title ماډل ته نه لیږدول کیږي.

د tool_choice ارزښتونه required او نومول شوې function د کوربه شوو open-weight ماډلونو لخوا پلي کیږي.

د tool loop بشپړ تشریح په خپله جلا پاڼه کې دی. فنکشن زنګ وهل

جوړښت لرونکی output

دا بڼه جوړښت لرونکی output د text.format په توګه لیکي. Schema مستقیماً په format کې ده، د name او strict تر څنګ، نه د json_schema غړي لاندې لکه په Chat Completions کې.

  • {"type": "json_object"} هر JSON څیز غواړي.
  • {"type": "json_schema", "name", "schema", "strict"} هغه JSON غواړي چې ستاسو schema تعقیبوي. 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 د message د output_text برخې په متن کې رارسیږي؛ پخپله یې parse کړئ. هغه کوربه شوی open-weight ماډل چې جوړښت لرونکی output نه لري 400 بیرته ورکوي.

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

کوم ماډل کومه بڼه مني په خپله جلا پاڼه کې لیست شوي. جوړښت شوي محصولات

Reasoning

ماډل چې reasoning کوي خپل reasoning د ډول reasoning د output توکي په توګه، مخکې له message، بیرته ورکوي. په stream کې دا د response.reasoning_summary_text.delta رخدادونو په توګه رارسیږي.

کوربه شوي open-weight ماډلونه reasoning.effort پلي کوي: off، low، medium یا high، او کله چې هیڅ نه لیږئ high. off د reasoning توکی نه ورکوي. دا د څیز په توګه ولیږئ؛ ساده string پدې endpoint کې نه لوستل کیږي.

efforts په خپل جلا پاڼه کې بیان شوي. د reasoning effort

د output حد

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 نشته یا خپور شوی id نه دی.
400 invalid_request_error No user message provided. د Shannon کچې: input د کاروونکي متن نه لري.
400 invalid_request_error <id> does not accept image input انځور هغه کوربه شوي open-weight ماډل ته ولیږل شو چې انځور input نه لري.
400 invalid_request_error <id> does not accept response_format text.format هغه کوربه شوي open-weight ماډل ته ولیږل شو چې جوړښت لرونکی output نه لري.
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. Flood protection: ستاسو په حساب په یوه دقیقه کې له 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 ماډل د هغه ځواب د وخت حد څخه ډیر وخت واخیست چې stream نه و. دا د stream سره چې په true ټاکل شوی ولیږئ.