Gafee gaa n'ọdịnaya
Responses API

Responses API

Ọhụrụ

POST /v1/responses na-anara ntụziaka na ndepụta input items ma na-eweghachi response object e mere site na output items, n'OpenAI Responses format. Jiri ya na responses API nke OpenAI SDK na tools e wuru na ya, dị ka Codex CLI. Endpoint anaghị edebe state: zipụ mkparịta ụka dum na request ọ bụla.

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

Request kacha obere bụ model id na text. Azịza abụghị stream belụsọ ị rịọ ya.

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)

Azịza bụ response object. output ya nwere reasoning, mgbe model chere echiche, na 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
  }
}

Request fields

model na input bụ ihe request chọrọ. Kọlụm Applied by na-akpọ models ebe field na-agbanwe azịza. Hosted open-weight models bụ ids iri na abụọ nke model list; Shannon 3 family bụ shannon-3, shannon-3-pro, shannon-3.1 na shannon-3.1-pro. Models & ọnụahịa

Field Ụdị Default Nkọwa Na-etinye ya
model string Achọrọ. Id si na model list. Nhọrọ anaghị eche mkpụrụedemede nta ma ọ bụ nnukwu. Id adịghị ma ọ bụ e bipụtaghị na-eweghachi 400 unknown model. Models niile
input string | array String, nke a na-agụ dị ka otu user message, ma ọ bụ array nke input items. Lee Input items n'okpuru. Models niile
instructions string Ntụziaka maka model, system prompt nke format a. Hosted open-weight models, shannon-1.6-*, shannon-2-*, shannon-coder-1
stream boolean false true na-ezipu azịza dị ka server-sent events. Lee Streaming n'okpuru. Models niile
max_output_tokens integer 4096 Oke elu nke azịza, na tokens. A na-akwaga uru dị n'èzí 1 ruo 65,536 n'oke ahụ. Ọ bụkwa ego edebere site na balance gị mgbe request na-agba. Lee Output limit n'okpuru. Hosted open-weight models, shannon-1.6-*, shannon-2-*, shannon-coder-1
temperature number Sampling temperature. Na hosted open-weight models a na-edebe uru n'agbata 0 na 2. Hosted open-weight models; shannon-1.6-*, shannon-2-* na shannon-coder-1 n'azịza ndị abụghị stream
top_p number Nucleus sampling. A na-edebe uru n'agbata 0 na 1. Hosted open-weight models
tools array Functions model nwere ike ịkpọ, n'ụdị flat nke format a: {"type": "function", "name", "description", "parameters"}. Lee Tools n'okpuru. Models niile
tool_choice string | object auto "auto" na-ahapụ model ka ọ kpebie. "required" na-eme ka ọ kpọọ tool. {"type": "function", "name": "…"} na-eme ka ọ kpọọ tool ahụ. Hosted open-weight models
reasoning object {"effort": "…"} nwere off, low, medium ma ọ bụ high. Uru ọ bụla ọzọ na-eweghachi 400. Hosted open-weight models
text object {"format": {…}} na-arịọ azịza JSON. Lee Structured output n'okpuru. Shannon tiers niile; hosted open-weight models dị ka edepụtara kwa id

A na-anabata previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user na prompt_cache_key ka koodu client dị adị na-agba na-enweghị mgbanwe. Ha anaghị agbanwe azịza. N'ihi na a naghị echekwa mkparịta ụka, request na-eso na-ebu turns gara aga na input.

Input items

Input item bụ ma message, nwere role na content, ma ọ bụ typed item na-ebu tool call ma ọ bụ result ya. content bụ string ma ọ bụ array nke parts.

Item Nkọwa Na-etinye ya
{"role": "user", "content": …} Ihe ị na-ajụ. content bụ string, ma ọ bụ input_text na input_image parts. Models niile
{"role": "assistant", "content": …} Azịza gara aga nke model. content bụ string, ma ọ bụ output_text parts. Models niile
{"role": "system", "content": …}
{"role": "developer", "content": …}
Ntụziaka n'ime mkparịta ụka. Hosted open-weight models
{"type": "function_call", "call_id": "…", "name": "…", "arguments": "…"} Tool call model mere n'azịza gara aga. arguments bụ JSON string. Models niile
{"type": "function_call_output", "call_id": "…", "output": "…"} Result nke call ahụ. call_id bụ id nke call ahụ, output bụ result dị ka string. Models niile

Tinye ntụziaka na field instructions. Site na Shannon 3 family id, tinye ntụziaka ga-adịgide na user message.

Items nke output nke azịza nwere ike ịlaghachi n'ime input dị ka ha dị: a na-agụ message na function_call items, a na-agafe reasoning items.

Content parts

Part Nkọwa Dị na
{"type": "input_text", "text": "…"} Text nke user message. Models niile
{"type": "output_text", "text": "…"} Text nke assistant message. Models niile
{"type": "input_image", "image_url": "…"} Image, dị ka data: URL nwere base64 content ma ọ bụ dị ka http(s) URL. Shannon 3 family, shannon-1.6-lite, shannon-1.6-pro, na hosted open-weight models depụtara image input
{"type": "input_file", "file_data": "data:application/pdf;base64,…"} Akwụkwọ (PDF, Word, PowerPoint ma ọ bụ Excel): file_data nwere data: URL, ma ọ bụ file_url nwere http(s) URL. Shannon 3 family

Na Shannon tiers a na-agụ images na files site na user item ikpeazụ nke input. Nha na limits nwere peeji nke ha. Images na files

Request nwere instructions na options

Request a na-ezipu ntụziaka, mkparịta ụka dị ka input items, output limit, temperature na reasoning effort. Ọ na-eji hosted open-weight model, nke na-etinye ha niile.

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)

Azịza nke hosted open-weight model nwere id, object, model, created_at, status, output na usage. usage ya na-agbakwunye tokens e sitere na cache gụọ na tokens ejiri maka 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
  }
}

Response object

id, object, status, output na usage dị na azịza ọ bụla. Wuo koodu gị n'elu ha.

Field Ụdị Nkọwa Onye zipụrụ
id string resp_ sochiri mkpụrụedemede hexadecimal 32. Models niile
object string Mgbe niile response. Models niile
status string completed. Na stream ọ bụ in_progress buru ụzọ, na failed n'event response.failed. Models niile
output array Output items n'usoro model mepụtara ha: reasoning, message, function_call. Models niile
usage object input_tokens, output_tokens na total_tokens. Models niile
usage.input_tokens_details object cached_tokens: input tokens e sitere na prompt cache gụọ. Hosted open-weight models
usage.output_tokens_details object reasoning_tokens: output tokens ejiri maka reasoning. Hosted open-weight models
model string Canonical id nke model zara. Shannon 3 family na hosted open-weight models
created_at integer Oge azịza, na Unix seconds. Shannon 3 family na hosted open-weight models
instructions, tools, temperature, … instructions, tools na temperature na-ekwughachi request. error na incomplete_details bụ null, metadata bụ {}, parallel_tool_calls bụ true, tool_choice bụ auto ma top_p bụ null. Shannon 3 family

Output items

Item Nkọwa
{"id": "rs_…", "type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} Reasoning nke model dị ka otu summary_text part. Dị naanị mgbe model chere echiche.
{"id": "msg_…", "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "…"}]} Azịza ahụ: otu output_text part nwere text.
{"id": "fc_…", "type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"} Tool call. arguments bụ JSON string. Zighachi result na otu call_id.

OpenAI SDKs na-ejikọta text nke message maka gị na response.output_text.

Streaming

Tọọ stream na true maka server-sent events. Frame ọ bụla nwere ahịrị event: nwere aha event na ahịrị data: nwere JSON object; object ahụ na-ekwughachi aha na type. Jikọta deltas na item ha site na output_index.

Site na OpenAI SDK, gụọ events site na type ha:

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")

Events na-abịa n'usoro a. Otu maka reasoning, message na tool calls pụtara naanị mgbe azịza nwere ha.

Event Payload Mgbe
response.created response Mgbe niile nke mbụ. response.status bụ in_progress ma response.output bụ efu.
response.in_progress response Mgbe niile nke abụọ, na otu object ahụ.
response.output_item.added output_index, item Reasoning na-amalite: reasoning item nwere summary efu.
response.reasoning_summary_text.delta output_index, summary_index, delta Otu akụkụ nke reasoning.
response.reasoning_summary_text.done output_index, summary_index, text Reasoning zuru ezu: text ya dum.
response.output_item.done output_index, item reasoning item gwụchara.
response.output_item.added output_index, item Azịza na-amalite: message item nwere status in_progress na enweghị content.
response.content_part.added output_index, content_index, part output_text part efu na-emepe.
response.output_text.delta output_index, content_index, delta Otu akụkụ nke azịza.
response.output_text.done output_index, content_index, text Azịza zuru ezu: text ya dum.
response.content_part.done output_index, content_index, part output_text part gwụchara.
response.output_item.done output_index, item message item gwụchara, nwere status completed.
response.output_item.added output_index, item Tool call na-amalite: function_call item nwere call_id, name na arguments efu.
response.function_call_arguments.delta output_index, delta Arguments nke call ahụ, zuru ezu n'otu delta.
response.function_call_arguments.done output_index, arguments Otu arguments ahụ, dị ka arguments.
response.output_item.done output_index, item function_call item gwụchara.
response.completed response Mgbe niile nke ikpeazụ mgbe ọ gara nke ọma: response object dum nwere output na 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 na-ada

Na Shannon tiers azịza dara na-agwụ na response.failed kama response.completed. response.status ya bụ failed ma response.error nwere code, rate_limit_exceeded ma ọ bụ server_error, na message.

Na hosted open-weight models ọdịda bụ error event nwere code api_error na message. response.completed ka na-eso ya.

Lee stream dị ka nke dara mgbe ọ nwere response.failed ma ọ bụ error event, ma zighachi request ahụ.

Tools

Tool bụ function koodu gị na-agba. Kọwaa ya na tools; mgbe model chọrọ ya, azịza nwere function_call item n'ọnọdụ ma ọ bụ n'akụkụ message.

Tool definition na tools:

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

output nke azịza na-akpọ ya:

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

Gbaa function ahụ, wee zighachi request ahụ na call na result ya agbakwunyere n'ime 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\"}"
  }
]

A na-agụ naanị tools nke ụdị function. Na shannon-1.6-*, shannon-2-* na shannon-coder-1 a na-ebelata schema parameters ruo JSON Schema keywords nkịtị: a na-agụ oneOf dị ka anyOf, a naghịkwa ebuga keywords dị ka $ref, additionalProperties, const, default na title gaa na model.

Hosted open-weight models na-etinye uru tool_choice required na function akpọrọ aha.

A kọwara tool loop n'ụzọ zuru ezu na peeji nke ya. Oku ọrụ

Structured output

Format a na-ede structured output dị ka text.format. Schema dị ozugbo na format, n'akụkụ name na strict, ọ bụghị n'okpuru member json_schema dị ka na Chat Completions.

  • {"type": "json_object"} na-arịọ JSON object ọ bụla.
  • {"type": "json_schema", "name", "schema", "strict"} na-arịọ JSON na-eso schema gị. strict bụ true mgbe ị hapụrụ ya.
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 na-abịa dị ka text n'ime output_text part nke message; parse ya n'onwe gị. Hosted open-weight model na-enweghị structured output na-eweghachi 400.

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

Model nke na-anara ụdị nke dị depụtara na peeji nke ya. Mmepụta ahaziri

Reasoning

Model na-eche echiche na-eweghachi reasoning ya dị ka output item nke ụdị reasoning, tupu message. Na stream ọ na-abịa dị ka response.reasoning_summary_text.delta events.

Hosted open-weight models na-etinye reasoning.effort: off, low, medium ma ọ bụ high, na high mgbe ị zipụghị ihe ọ bụla. off anaghị eweghachi reasoning item. Zipụ ya dị ka object; a naghị agụ string efu na endpoint a.

A kọwara efforts na peeji nke ha. Reasoning effort

Output limit

max_output_tokens bụ 4,096 mgbe ị zipụghị ya. Ọ bụ ọnụọgụ tokens edebere site na balance gị mgbe request malitere; mgbe azịza zuru ezu, ego ahụ na-anọchi ihe request jiri. Uru na-abaghị n'ime balance gị fọdụrụ na-eweghachi 429 Quota exceeded.

Ọ na-ejedebe ogologo azịza na shannon-1.6-*, shannon-2-* na shannon-coder-1, na ogologo ederede azịza na hosted open-weight models.

Na endpoint a a na-akwụ ụgwọ shannon-coder-1 na tokens site na balance gị, dị ka model ọ bụla ọzọ.

Request body nwere ike ịbụ ruo 32 MiB. Limits na balance

Njehie

Njehie na-eji OpenAI error body: object error nwere type na message; ụfọdụ na-ebukwa code na param nwere uru null. Tebụl na-depụta ihe endpoint a na-ebukarị. Ndepụta zuru ezu, ya na ihe a ga-ezighachi, nwere peeji nke ya. Njikwa njehie

Status Ụdị Ozi Mgbe
401 authentication_error Missing authentication
Invalid API key
Ezipụghị API key, ma ọ bụ key amabeghị ma ọ bụ a kagburu ya.
400 invalid_request_error unknown model: <id> model adịghị ma ọ bụ abụghị id e bipụtara.
400 invalid_request_error No user message provided. Shannon tiers: input enweghị user text.
400 invalid_request_error <id> does not accept image input Zipụrụ image na hosted open-weight model na-enweghị image input.
400 invalid_request_error <id> does not accept response_format Zipụrụ text.format na hosted open-weight model na-enweghị structured output.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high reasoning.effort nwere uru dị n'èzí ndepụta.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Body bụ JSON ziri ezi mana field nwere type na-ezighi ezi.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_output_tokens ka ukwuu karịa ihe fọdụrụ na balance gị.
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection: karịa requests 120 n'otu nkeji na akaụntụ gị.
500 api_error The model backend failed to answer. Please retry. Model emepụtaghị azịza. Zighachi request ahụ.
502 api_error The model backend failed to answer. Please retry. Otu ihe ahụ, na hosted open-weight models.
504 api_error upstream timed out Hosted open-weight model were oge karịrị oke oge nke azịza abụghị stream. Zipụ ya na stream tọrọ true.