Responses API

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

Ombi dogo zaidi ni model id na maandishi. Jibu halina stream usipoliomba.

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

Jibu ni kitu cha response. output yake ina reasoning, model ilipofikiri, na ujumbe:

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

Fields za ombi

model na input ndivyo ombi linahitaji. Safu ya Inatumiwa na inataja model ambazo field inabadilisha jibu juu yake. Model za open-weight zinazopangishwa ni id kumi na mbili za orodha ya model; familia ya Shannon 3 ni shannon-3, shannon-3-pro, shannon-3.1 na shannon-3.1-pro. Model na bei

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user na prompt_cache_key zinakubaliwa ili code ya client iliyopo ifanye kazi bila mabadiliko. Hazibadilishi jibu. Kwa sababu hakuna mazungumzo yanayohifadhiwa, ombi linalofuata hubeba zamu za awali kwenye input.

Input items

Input item ni ujumbe, wenye role na content, au item yenye aina inayobeba wito wa tool au matokeo yake. content ni string au array ya sehemu.

Weka maagizo kwenye field ya instructions. Ukiwa na id ya familia ya Shannon 3, weka maagizo yanayopaswa kushikilia kwenye ujumbe wa user.

Items za output ya jibu zinaweza kurudi kwenye input kama zilivyo: items za message na function_call husomwa, items za reasoning huruka.

Sehemu za maudhui

Kwenye viwango vya Shannon picha na mafaili husomwa kutoka kwenye item ya mwisho ya user ya input. Ukubwa na mipaka vina ukurasa wake. Picha na mafaili

Ombi lenye instructions na options

Ombi hili linatuma instructions, mazungumzo kama input items, kikomo cha output, temperature na reasoning effort. Linatumia model ya open-weight inayopangishwa, ambayo huzitumia zote.

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

Jibu la model ya open-weight inayopangishwa lina id, object, model, created_at, status, output na usage. usage yake huongeza tokens zilizosomwa kutoka cache na tokens zilizotumika kwa reasoning:

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

Kitu cha response

id, object, status, output na usage ziko kwenye kila jibu. Jenga code yako juu ya hizo.

Output items

SDK za OpenAI huunganisha maandishi ya ujumbe kwa ajili yako kwenye response.output_text.

Streaming

Weka stream kuwa true kupata server-sent events. Kila frame ina mstari wa event: wenye jina la tukio na mstari wa data: wenye kitu cha JSON; kitu hurudia jina kwenye type. Linganisha deltas na item yake kwa output_index.

Ukiwa na SDK ya OpenAI, soma matukio kwa type yake:

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

Matukio hufika kwa mpangilio huu. Makundi ya reasoning, ujumbe na wito wa tools yanaonekana tu jibu likiwa nayo.

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 inayoshindwa

Kwenye viwango vya Shannon jibu lililoshindwa huisha na response.failed badala ya response.completed. response.status yake ni failed na response.error ina code, rate_limit_exceeded au server_error, na message.

Kwenye model za open-weight zinazopangishwa kushindwa ni tukio la error lenye code api_error na message. response.completed bado inalifuata.

Chukulia stream kama iliyoshindwa inapokuwa na response.failed au tukio la error, na utume ombi tena.

Tools

Tool ni function ambayo code yako inaendesha. Ieleze kwenye tools; model inapoitaka, jibu lina item ya function_call badala ya, au kando ya, ujumbe.

Ufafanuzi wa tool kwenye tools:

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

output ya jibu linaloiita:

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

Endesha function, kisha tuma ombi tena na wito na matokeo yake yaliyoongezwa kwenye 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\"}"
  }
]

Ni tools za aina function pekee zinazosomwa. Kwenye shannon-1.6-*, shannon-2-* na shannon-coder-1 schema ya parameters hupunguzwa hadi keywords za kawaida za JSON Schema: oneOf husomwa kama anyOf, na keywords kama $ref, additionalProperties, const, default na title hazipitishwi kwa model.

Thamani za tool_choice required na function iliyotajwa zinatumiwa na model za open-weight zinazopangishwa.

Mzunguko wa tool umeelezwa kikamilifu kwenye ukurasa wake. Uitoaji wa kazi

Matokeo yaliyopangwa

Umbizo hili huandika matokeo yaliyopangwa kama text.format. Schema iko moja kwa moja kwenye format, kando ya name na strict, si chini ya member ya json_schema kama kwenye Chat Completions.

• {"type": "json_object"} huomba kitu chochote cha JSON.
• {"type": "json_schema", "name", "schema", "strict"} huomba JSON inayofuata schema yako. strict ni true ukiiacha nje.

{
  "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 hufika kama maandishi kwenye sehemu ya output_text ya ujumbe; ichanganue (parse) mwenyewe. Model ya open-weight inayopangishwa isiyo na matokeo yaliyopangwa hurudisha 400.

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

Model ipi inakubali umbo lipi imeorodheshwa kwenye ukurasa wake. Matokeo yaliyopangwa

Reasoning

Model inayofikiri hurudisha reasoning yake kama output item ya aina reasoning, kabla ya ujumbe. Kwenye stream hufika kama matukio ya response.reasoning_summary_text.delta.

Model za open-weight zinazopangishwa hutumia reasoning.effort: off, low, medium au high, na high usipotuma chochote. off haitoi reasoning item. Itume kama kitu; string pekee haisomwi kwenye endpoint hii.

Efforts zimeelezwa kwenye ukurasa wake. Reasoning effort

Kikomo cha output

max_output_tokens ni 4,096 usipoituma. Ni idadi ya tokens inayotengwa kutoka kwenye salio lako ombi linapoanza; jibu likikamilika, kiasi hicho hubadilishwa na kile ambacho ombi lilitumia. Thamani isiyoingia kwenye salio lako lililobaki hurudisha 429 Quota exceeded.

Inapunguza urefu wa jibu kwenye shannon-1.6-*, shannon-2-* na shannon-coder-1, na urefu wa maandishi ya jibu kwenye model za open-weight zinazopangishwa.

Kwenye endpoint hii shannon-coder-1 hutozwa kwa tokens kutoka kwenye salio lako, kama kila model nyingine.

Mwili wa ombi unaweza kuwa hadi 32 MiB. Mipaka na salio

Makosa

Makosa hutumia mwili wa kosa wa OpenAI: kitu cha error chenye type na message; baadhi pia hubeba code na param zenye thamani null. Jedwali linaorodhesha kile ambacho endpoint hii hurudisha mara nyingi zaidi. Orodha kamili, pamoja na yapi ya kujaribu tena, ina ukurasa wake. Ushughulikiaji wa Makosa