Responses API

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

Pempho laling'ono kwambiri ndi model id ndi text. Yankho silichita stream pokhapokha mutapempha.

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

Yankho ndi response object. output yake ili ndi reasoning, pamene model yaganiza, ndi 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
  }
}

Ma field a pempho

model ndi input ndizo zomwe pempho limafuna. Column ya Imagwira ntchito pa imatchula ma model omwe field imasintha yankho. Hosted open-weight model ndi ma id khumi ndi awiri a mndandanda wa ma model; banja la Shannon 3 ndi shannon-3, shannon-3-pro, shannon-3.1 ndi shannon-3.1-pro. Ma model ndi mitengo

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ndi prompt_cache_key zimalandiridwa kuti code ya client yomwe ilipo igwire ntchito popanda kusintha. Sizisintha yankho. Chifukwa palibe zokambirana zomwe zimasungidwa, pempho lotsatira limanyamula ma turn akale mu input.

Input items

Input item ndi message, yokhala ndi role ndi content, kapena item yokhala ndi type yomwe imanyamula call ya tool kapena zotsatira zake. content ndi string kapena array ya ma part.

Ikani malangizo mu field ya instructions. Ndi id ya banja la Shannon 3, ikani malangizo omwe ayenera kutsatiridwa mu message ya user.

Ma item a output ya yankho amatha kubwerera mu input monga alili: ma item a message ndi function_call amawerengedwa, ma item a reasoning amadumphidwa.

Ma content part

Pa ma tier a Shannon zithunzi ndi ma file zimawerengedwa kuchokera ku item yomaliza ya user ya input. Kukula ndi malire zili patsamba lawo. Zithunzi ndi ma file

Pempho lokhala ndi instructions ndi options

Pempho ili limatumiza instructions, zokambirana ngati ma input item, output limit, temperature ndi reasoning effort. Limagwiritsa ntchito hosted open-weight model, yomwe imagwiritsa ntchito zonsezo.

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

Yankho la hosted open-weight model lili ndi id, object, model, created_at, status, output ndi usage. usage yake imawonjezera ma token owerengedwa kuchokera ku cache ndi ma token ogwiritsidwa ntchito pa reasoning:

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

Object ya response

id, object, status, output ndi usage zili pa yankho lililonse. Mangani code yanu pa izo.

Ma output item

Ma OpenAI SDK amalumikiza text ya message m'malo mwanu mu response.output_text.

Streaming

Khazikitsani stream kukhala true kuti mulandire server-sent events. Frame iliyonse ili ndi mzere wa event: wokhala ndi dzina la event ndi mzere wa data: wokhala ndi JSON object; object imabwereza dzinalo mu type. Fananizani ma delta ndi item yawo ndi output_index.

Ndi OpenAI SDK, werengani ma event ndi type yawo:

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

Ma event amafika motsatira dongosolo ili. Magulu a reasoning, message ndi ma call a tool amaoneka pokhapokha yankho lili nawo.

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 yomwe yalephera

Pa ma tier a Shannon yankho lolephera limatha ndi response.failed m'malo mwa response.completed. response.status yake ndi failed ndipo response.error ili ndi code, rate_limit_exceeded kapena server_error, ndi message.

Pa hosted open-weight model cholakwika ndi event ya error yokhala ndi code api_error ndi message. response.completed imatsatirabe.

Ganizirani stream ngati yolephera ikakhala ndi event ya response.failed kapena error, ndipo tumizaninso pempho.

Ma tool

Tool ndi function yomwe code yanu imayendetsa. Ifotokozeni mu tools; model ikaifuna, yankho limakhala ndi item ya function_call m'malo mwa message kapena pambali pake.

Tanthauzo la tool mu tools:

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

output ya yankho lomwe limayitana tool:

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

Yendetsani function, kenako tumizaninso pempho ndi call ndi zotsatira zake zowonjezedwa ku 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\"}"
  }
]

Ma tool a type function okha ndi omwe amawerengedwa. Pa shannon-1.6-*, shannon-2-* ndi shannon-coder-1 schema ya parameters imachepetsedwa kufika pa ma keyword wamba a JSON Schema: oneOf imawerengedwa ngati anyOf, ndipo ma keyword monga $ref, additionalProperties, const, default ndi title sapatsidwa kwa model.

Mitengo ya tool_choice required ndi function yotchulidwa imagwiritsidwa ntchito ndi hosted open-weight model.

Tool loop yafotokozedwa mokwanira patsamba lake. Kuyitana mafunkseni

Structured output

Mtundu uwu umalemba structured output ngati text.format. Schema ili mwachindunji mu format, pambali pa name ndi strict, osati pansi pa member ya json_schema monga pa Chat Completions.

• {"type": "json_object"} imapempha JSON object iliyonse.
• {"type": "json_schema", "name", "schema", "strict"} imapempha JSON yotsatira schema yanu. strict ndi true mukapanda kuilemba.

{
  "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 imafika ngati text mu part ya output_text ya message; isanthuleni nokha. Hosted open-weight model yopanda structured output imabweza 400.

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

Model yomwe imalandira mtundu uti yalembedwa patsamba lake. Zotuluka zokonzedwa

Reasoning

Model yomwe imaganiza imabweza reasoning yake ngati output item ya type reasoning, patsogolo pa message. Mu stream imafika ngati ma event a response.reasoning_summary_text.delta.

Hosted open-weight model zimagwiritsa ntchito reasoning.effort: off, low, medium kapena high, ndi high mukapanda kutumiza kanthu. off simabweza reasoning item. Itumizeni ngati object; string yokha siiwerengedwa pa endpoint iyi.

Ma effort amafotokozedwa patsamba lawo. Reasoning effort

Output limit

max_output_tokens ndi 4,096 mukapanda kuitumiza. Ndi chiwerengero cha ma token chomwe chimasungidwa pa balance yanu pempho likayamba; yankho likatha, kuchuluka kumeneko kumasinthidwa ndi zomwe pempho lagwiritsa ntchito. Mtengo wosakwana mu balance yanu yotsala umabweza 429 Quota exceeded.

Imalepheretsa kutalika kwa yankho pa shannon-1.6-*, shannon-2-* ndi shannon-coder-1, ndi kutalika kwa text ya yankho pa hosted open-weight model.

Pa endpoint iyi shannon-coder-1 imaperekedwa mtengo mu ma token kuchokera ku balance yanu, monga model ina iliyonse.

Body ya pempho ikhoza kufika 32 MiB. Malire ndi balance

Zolakwika

Zolakwika zimagwiritsa ntchito body ya cholakwika ya OpenAI: object ya error yokhala ndi type ndi message; zina zimanyamulanso code ndi param ndi mtengo null. Table imalemba zomwe endpoint iyi imabweza kawirikawiri. Mndandanda wonse, ndi zoyenera kuyesanso, uli patsamba lake. Zolakwika