Responses API

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

Kopo e nyane ka ho fetisisa ke id ea model le mongolo. Karabo ha e etse streaming ntle le haeba u e kopa.

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."
  }'

Karabo ke ntho ea karabo. output ea eona e na le reasoning, ha model e nahanne, le molaetsa:

{
  "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
  }
}

Li-field tsa kopo

model le input ke tseo kopo e li hlokang. Kholomo ea E sebelisoa ke e reha li-model tseo field e fetolang karabo ho tsona. Li-model tse hosted tsa open-weight ke li-id tse leshome le metso e 'meli tsa lenane la li-model; lelapa la Shannon 3 ke shannon-3, shannon-3-pro, shannon-3.1 le shannon-3.1-pro. Li-model le litheko

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user le prompt_cache_key lia amohelwa e le hore code ea moreki e teng e sebetse ntle le phetoho. Ha li fetole karabo. Kaha ha ho moqoqo o bolokiloeng, kopo e latelang e nka li-turn tse fetileng ho input.

Lintho tsa input

Ntho ea input ke molaetsa, o nang le role le content, kapa ntho e nang le mofuta e nkang kopo ea tool kapa sephetho sa eona. content ke string kapa array ea likarolo.

Kenya litaelo ho field ea instructions. Ka id ea lelapa la Shannon 3, kenya litaelo tse lokelang ho latelloa molaetsa oa user.

Lintho tsa output ea karabo li ka khutlela ho input joalo ka ha li le: lintho tsa message le function_call lia baloa, lintho tsa reasoning lia tlolloa.

Likarolo tsa litaba

Ho li-tier tsa Shannon litšoantšo le lifaele li baloa ho ntho ea ho qetela ea user ea input. Boholo le meeli li na le leqephe la tsona. Litšoantšo le lifaele

Kopo e nang le litaelo le likhetho

Kopo ena e romela litaelo, moqoqo e le lintho tsa input, moeli oa output, temperature le reasoning effort. E sebelisa model e hosted ea open-weight, e sebelisang tsohle.

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"}
  }'

Karabo ea model e hosted ea open-weight e na le id, object, model, created_at, status, output le usage. usage ea eona e eketsa tokens tse baloang ho cache le tokens tse sebelisitsoeng ho reasoning:

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

Ntho ea karabo

id, object, status, output le usage li ho karabo e 'ngoe le e 'ngoe. Aha code ea hau holim'a tsena.

Lintho tsa output

Li-SDK tsa OpenAI li u kopanyetsa mongolo oa molaetsa ho response.output_text.

Streaming

Beha stream ho true bakeng sa server-sent events. Frame e 'ngoe le e 'ngoe e na le mohala oa event: o nang le lebitso la event le mohala oa data: o nang le ntho ea JSON; ntho e pheta lebitso ho type. Amanya li-delta le ntho ea tsona ka output_index.

Ka SDK ea OpenAI, bala li-event ka type ea tsona:

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
  }'

Li-event li fihla ka tatellano ena. Lihlopha tsa reasoning, molaetsa le likopo tsa tool li hlaha feela ha karabo e na le tsona.

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 e hlolehang

Ho li-tier tsa Shannon karabo e hlolehileng e fela ka response.failed sebakeng sa response.completed. response.status ea eona ke failed mme response.error e na le code, rate_limit_exceeded kapa server_error, le message.

Ho li-model tse hosted tsa open-weight ho hloleha ke event ea error e nang le code api_error le message. response.completed e ntse e e latela.

Nka stream e le e hlolehileng ha e na le event ea response.failed kapa error, mme u romele kopo hape.

Tools

Tool ke function eo code ea hau e e etsang. E hlalose ho tools; ha model e e batla, karabo e na le ntho ea function_call sebakeng sa, kapa haufi le, molaetsa.

Tlhaloso ea tool ho tools:

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

output ea karabo e e bitsang:

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

Etsa function, ebe u romela kopo hape le kopo le sephetho sa eona li kentsoe ho 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\"}"
  }
]

Ke lisebelisoa feela tsa mofuta function tse baloang. Ho shannon-1.6-*, shannon-2-* le shannon-coder-1 schema ea parameters e fokotsoa ho mantsoe a tloaelehileng a JSON Schema: oneOf e baloa e le anyOf, mme mantsoe a kang $ref, additionalProperties, const, default le title ha a fetisetsoe ho model.

Litekanyo tsa tool_choice required le function e rehiloeng li sebelisoa ke li-model tse hosted tsa open-weight.

Tool loop e hlalositsoe ka botlalo leqepheng la eona. Mekhosi ya mesebetsi

Structured output

Sebopeho sena se ngola structured output e le text.format. Schema e ho format ka ho toba, haufi le name le strict, eseng tlasa setho sa json_schema joalo ka ho Chat Completions.

• {"type": "json_object"} e kopa ntho efe kapa efe ea JSON.
• {"type": "json_schema", "name", "schema", "strict"} e kopa JSON e latelang schema ea hau. strict ke true ha u e siea ka ntle.

{
  "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 e fihla e le mongolo karolong ea output_text ea molaetsa; e parse ka bouena. Model e hosted ea open-weight e se nang structured output e khutlisa 400.

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

Hore na model efe e amohela sebopeho sefe e thathamisitsoe leqepheng la eona. Diphumo tse hlophisitsoeng

Reasoning

Model e nahanang e khutlisa reasoning ea eona e le ntho ea output ea mofuta reasoning, pele ho molaetsa. Ho stream e fihla e le li-event tsa response.reasoning_summary_text.delta.

Li-model tse hosted tsa open-weight li sebelisa reasoning.effort: off, low, medium kapa high, le high ha u sa romele letho. off ha e khutlise ntho ea reasoning. E romele e le ntho; string e hlakileng ha e baloe ho endpoint ena.

Li-effort li hlalositsoe leqepheng la tsona. Effort ea reasoning

Output limit

max_output_tokens ke 4,096 ha u sa e romele. Ke palo ea tokens e behelloang thoko ho balance ea hau ha kopo e qala; ha karabo e phethahetse, palo eo e nkeloa sebaka ke seo kopo e se sebelisitseng. Boleng bo sa keneng ho balance ea hau e setseng bo khutlisa 429 Quota exceeded.

E lekanyetsa bolelele ba karabo ho shannon-1.6-*, shannon-2-* le shannon-coder-1, le bolelele ba mongolo oa karabo ho li-model tse hosted tsa open-weight.

Ho endpoint ena shannon-coder-1 e lefisoa ka tokens ho tsoa ho balance ea hau, joalo ka model e 'ngoe le e 'ngoe.

Body ea kopo e ka ba 32 MiB. Meeli le balance

Liphoso

Liphoso li sebelisa body ea phoso ea OpenAI: ntho ea error e nang le type le message; tse ling li boetse li nka code le param le boleng null. Tafole e thathamisa seo endpoint ena e se khutlisang hangata. Lenane le felletseng, le se ka lekoang hape, le na le leqephe la lona. Diphoso