Responses API

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

Ìbéèrè tó kéré jù jẹ́ id model àti ọ̀rọ̀ kan. Èsì náà kì í ṣe streaming àfi tí o bá béèrè fún un.

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

Èsì náà jẹ́ object èsì. output rẹ̀ ní ìrònú, nígbà tí model bá ronú, àti ìfiránṣẹ́ náà:

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

Àwọn field ìbéèrè

model àti input ni ohun tí ìbéèrè nílò. Column Ó ń ṣiṣẹ́ lórí dárúkọ àwọn model tí field ti ń yí èsì padà. Àwọn model open-weight tí a gbàlejò ni id méjìlá inú àtòjọ model; ìdílé Shannon 3 jẹ́ shannon-3, shannon-3-pro, shannon-3.1 àti shannon-3.1-pro. Àwọn model àti iye owó

A gba previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user àti prompt_cache_key kí code client tó wà lè ṣiṣẹ́ láìyípadà. Wọn kì í yí èsì padà. Nítorí a kì í pa ìjíròrò mọ́, ìbéèrè tó tẹ̀lé e ń gbé àwọn ìyípo tẹ́lẹ̀ nínú input.

Àwọn ohun input

Ohun input jẹ́ ìfiránṣẹ́, pẹ̀lú role àti content, tàbí ohun tí a ti dárúkọ irú rẹ̀ tó gbé ìpè tool tàbí abajade rẹ̀. content jẹ́ string tàbí array ti àwọn apá.

Fi àwọn ìtọ́ni sínú field instructions. Pẹ̀lú id ìdílé Shannon 3, fi àwọn ìtọ́ni tó gbọdọ̀ dúró sínú ìfiránṣẹ́ user.

Àwọn ohun output ti èsì lè padà sínú input bí wọ́n ṣe wà: a ń ka àwọn ohun message àti function_call, a sì ń fo àwọn ohun reasoning.

Àwọn apá àkóónú

Lórí àwọn ipele Shannon, a ń ka àwọn àwòrán àti fáìlì láti ohun user tó gbẹ̀yìn nínú input. Àwọn ìwọ̀n àti ààlà ní ojú-ìwé tiwọn. Àwọn àwòrán àti fáìlì

Ìbéèrè pẹ̀lú àwọn ìtọ́ni àti àwọn aṣayan

Ìbéèrè yìí ń fi àwọn ìtọ́ni, ìjíròrò bí àwọn ohun input, ààlà output, temperature àti Ipa ìrònú ránṣẹ́. Ó lo model open-weight tí a gbàlejò, èyí tó ń lo gbogbo wọn.

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

Èsì model open-weight tí a gbàlejò ní id, object, model, created_at, status, output àti usage. usage rẹ̀ ń fi àwọn token tí a kà láti cache àti àwọn token tí a lò lórí ìrònú kún:

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

Object èsì

id, object, status, output àti usage wà lórí gbogbo èsì. Kọ́ code rẹ lé wọn.

Àwọn ohun output

Àwọn SDK OpenAI ń so ọ̀rọ̀ ìfiránṣẹ́ náà pọ̀ fún ọ nínú response.output_text.

Streaming

Ṣètò stream sí true fún server-sent events. Frame kọ̀ọ̀kan ní ìlà event: pẹ̀lú orúkọ event àti ìlà data: pẹ̀lú object JSON; object náà ń tún orúkọ sọ nínú type. So àwọn delta mọ́ ohun wọn nípasẹ̀ output_index.

Pẹ̀lú SDK OpenAI, ka àwọn event nípasẹ̀ type wọn:

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

Àwọn event ń dé ní ìlànà yìí. Àwọn ẹgbẹ́ fún ìrònú, ìfiránṣẹ́ àti àwọn ìpè tool ń hàn nígbà tí èsì bá ní wọn nìkan.

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 tó kùnà

Lórí àwọn ipele Shannon, èsì tó kùnà ń parí pẹ̀lú response.failed dípò response.completed. response.status rẹ̀ jẹ́ failed, response.error sì ní code, rate_limit_exceeded tàbí server_error, àti message.

Lórí àwọn model open-weight tí a gbàlejò, ìkùnà jẹ́ event error pẹ̀lú code api_error àti message. response.completed ṣì tẹ̀lé e.

Ka stream sí èyí tó kùnà nígbà tó bá ní response.failed tàbí event error, kí o sì tún fi ìbéèrè náà ránṣẹ́.

Àwọn tool

Tool jẹ́ function tí code rẹ ń ṣe. Ṣàpèjúwe rẹ̀ nínú tools; nígbà tí model bá fẹ́ ẹ, èsì ní ohun function_call dípò, tàbí lẹ́gbẹ̀ẹ́, ìfiránṣẹ́ náà.

Ìtumọ̀ tool nínú tools:

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

output ti èsì tó pè é:

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

Ṣe function náà, lẹ́yìn náà tún fi ìbéèrè náà ránṣẹ́ pẹ̀lú ìpè àti abajade rẹ̀ tí a fi kún 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 ń ka àwọn tool ti irú function nìkan. Lórí shannon-1.6-*, shannon-2-* àti shannon-coder-1, schema parameters ni a dín kù sí àwọn keyword JSON Schema gbogbogbò: a ń ka oneOf bí anyOf, a kì í sì í fi àwọn keyword bíi $ref, additionalProperties, const, default àti title fún model.

Àwọn iye tool_choice required àti function tí a dárúkọ ni àwọn model open-weight tí a gbàlejò ń lò.

A ṣàpèjúwe tool loop ní kíkún lórí ojú-ìwé tirẹ̀. Ipe iṣẹ

Structured output

Ọ̀nà yìí ń kọ structured output bí text.format. Schema wà tààrà nínú format, lẹ́gbẹ̀ẹ́ name àti strict, kì í ṣe lábẹ́ ẹ̀yà json_schema bí lórí Chat Completions.

• {"type": "json_object"} ń béèrè object JSON èyíkéyìí.
• {"type": "json_schema", "name", "schema", "strict"} ń béèrè JSON tó tẹ̀lé schema rẹ. strict jẹ́ true nígbà tí o bá fi sílẹ̀.

{
  "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 ń dé bí ọ̀rọ̀ nínú apá output_text ti ìfiránṣẹ́; parse rẹ̀ fúnra rẹ. Model open-weight tí a gbàlejò láìsí structured output ń dá 400 padà.

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

A ṣàkójọ model tó ń gba ọ̀nà wo lórí ojú-ìwé tirẹ̀. Awọn igbejade ti a ṣeto

Ìrònú

Model tó ń ronú ń dá ìrònú rẹ̀ padà bí ohun output ti irú reasoning, ṣáájú ìfiránṣẹ́. Nínú stream, ó ń dé bí àwọn event response.reasoning_summary_text.delta.

Àwọn model open-weight tí a gbàlejò ń lo reasoning.effort: off, low, medium tàbí high, pẹ̀lú high nígbà tí o kò fi nǹkankan ránṣẹ́. off kì í dá ohun ìrònú padà. Fi ránṣẹ́ bí object; a kì í ka string lásán lórí endpoint yìí.

A ṣàpèjúwe àwọn effort lórí ojú-ìwé tiwọn. Ipa ìrònú

Ààlà output

max_output_tokens jẹ́ 4,096 nígbà tí o kò fi ránṣẹ́. Ó jẹ́ iye token tí a fi pamọ́ láti balance rẹ nígbà tí ìbéèrè bá bẹ̀rẹ̀; nígbà tí èsì bá parí, iye yẹn ni a ó fi ohun tí ìbéèrè lò rọ́pò. Iye tí kò wọ inú balance rẹ tó kù ń dá 429 Quota exceeded padà.

Ó ń fi ààlà sí gígùn èsì lórí shannon-1.6-*, shannon-2-* àti shannon-coder-1, àti gígùn ọ̀rọ̀ ìdáhùn lórí àwọn model open-weight tí a gbàlejò.

Lórí endpoint yìí, a ń gba owó shannon-coder-1 ní token láti balance rẹ, bí gbogbo model mìíràn.

Body ìbéèrè lè tó 32 MiB. Àwọn ààlà àti balance

Àwọn àṣìṣe

Àwọn àṣìṣe ń lo body àṣìṣe OpenAI: object error pẹ̀lú type àti message; àwọn kan tún gbé code àti param pẹ̀lú iye null. Tábìlì náà ṣàkójọ ohun tí endpoint yìí ń dá padà jù. Àtòjọ kíkún, pẹ̀lú ohun tí a ó tún gbìyànjú, ní ojú-ìwé tirẹ̀. Mimu Aṣiṣe