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) import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const response = await client.responses.create({
model: "shannon-3",
input: "Say hello in one sentence.",
});
console.log(response.output_text); curl https://api.shannon-ai.com/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"input": "Say hello in one sentence."
}' Azịza bụ response object. output ya nwere reasoning, mgbe model chere echiche, na message:
{
"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) import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const response = await 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 (const item of response.output) {
if (item.type === "reasoning") console.log("reasoning:", item.summary[0].text);
if (item.type === "message") console.log("answer:", item.content[0].text);
}
console.log(response.usage); curl https://api.shannon-ai.com/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"}
}' 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:
{
"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") import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const stream = await client.responses.create({
model: "shannon-3",
input: "Explain server-sent events in three sentences.",
stream: true,
});
for await (const event of stream) {
if (event.type === "response.reasoning_summary_text.delta") {
// a piece of reasoning: event.delta
} else if (event.type === "response.output_text.delta") {
process.stdout.write(event.delta);
} else if (event.type === "response.output_item.done" && event.item.type === "function_call") {
console.log("\ntool call:", event.item.name, event.item.arguments);
} else if (event.type === "response.completed") {
console.log("\n", event.response.usage);
} else if (event.type === "response.failed" || event.type === "error") {
throw new Error("the stream failed, send the request again");
}
} curl -N https://api.shannon-ai.com/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"input": "Explain server-sent events in three sentences.",
"stream": true
}' 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. |
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:
[
{
"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:
[
{
"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:
[
{
"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ị.strictbụtruemgbe ị hapụrụ ya.
{
"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.
{"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 authenticationInvalid 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. |