Responses API

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

အသေးငယ်ဆုံး request တွင် model id တစ်ခုနှင့် စာသားတစ်ခု ပါသည်။ မတောင်းဆိုလျှင် ပြန်ကြားချက်ကို stream မလုပ်ပါ။

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

ပြန်ကြားချက်သည် response object တစ်ခုဖြစ်သည်။ ၎င်း၏ output တွင် model က reasoning လုပ်ခဲ့လျှင် reasoning နှင့် 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

request တစ်ခု လိုအပ်သည်မှာ model နှင့် input ဖြစ်သည်။ အသုံးပြုသည့် model ကော်လံသည် field တစ်ခုက ပြန်ကြားချက်ကို ပြောင်းလဲစေသည့် model များကို အမည်ပေးသည်။ Host လုပ်ထားသော open-weight models များမှာ model စာရင်းရှိ id ဆယ့်နှစ်ခု ဖြစ်ပြီး Shannon 3 မိသားစုမှာ shannon-3, shannon-3-pro, shannon-3.1 နှင့် shannon-3.1-pro ဖြစ်သည်။ Model များနှင့် ဈေးနှုန်း

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user နှင့် prompt_cache_key တို့ကို ရှိပြီးသား client code မပြောင်းလဲဘဲ အလုပ်လုပ်စေရန် လက်ခံသည်။ ၎င်းတို့သည် ပြန်ကြားချက်ကို မပြောင်းလဲစေပါ။ စကားပြောဆိုမှုကို မသိမ်းသဖြင့် နောက်ဆက်တွဲ request သည် ယခင် turn များကို input ထဲတွင် သယ်ဆောင်သည်။

Input items

input item သည် role နှင့် content ပါသော message တစ်ခု၊ သို့မဟုတ် tool call သို့မဟုတ် ၎င်း၏ ရလဒ်ကို သယ်ဆောင်သော type ပါ item တစ်ခု ဖြစ်သည်။ content သည် string တစ်ခု သို့မဟုတ် အစိတ်အပိုင်းများ၏ array ဖြစ်သည်။

ညွှန်ကြားချက်များကို instructions field တွင် ထည့်ပါ။ Shannon 3 မိသားစု id ဖြင့် မဖြစ်မနေလိုက်နာရမည့် ညွှန်ကြားချက်များကို user message ထဲတွင် ထည့်ပါ။

ပြန်ကြားချက်၏ output ၏ item များကို မပြောင်းလဲဘဲ input ထဲသို့ ပြန်ထည့်နိုင်သည်- message နှင့် function_call item များကို ဖတ်ပြီး reasoning item များကို ကျော်သွားသည်။

Content parts

Shannon အဆင့်များတွင် ပုံများနှင့် ဖိုင်များကို input ၏ နောက်ဆုံး user item မှ ဖတ်သည်။ အရွယ်အစားများနှင့် ကန့်သတ်ချက်များတွင် ကိုယ်ပိုင်စာမျက်နှာရှိသည်။ ပုံများနှင့် ဖိုင်များ

ညွှန်ကြားချက်များနှင့် options ပါသော request

ဤ request သည် ညွှန်ကြားချက်များ၊ input item များအဖြစ် စကားပြောဆိုမှု၊ output limit၊ temperature နှင့် reasoning effort တို့ကို ပို့သည်။ ၎င်းတို့အားလုံးကို အသုံးပြုသော host လုပ်ထားသည့် open-weight model တစ်ခုကို သုံးထားသည်။

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

host လုပ်ထားသော open-weight model ၏ ပြန်ကြားချက်တွင် id၊ object၊ model၊ created_at၊ status၊ output နှင့် usage ပါသည်။ ၎င်း၏ usage သည် cache မှ ဖတ်ထားသော tokens နှင့် reasoning အတွက် သုံးစွဲသော tokens တို့ကို ထပ်ထည့်သည်-

{
  "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 နှင့် usage တို့သည် ပြန်ကြားချက်တိုင်းတွင် ပါသည်။ သင့် code ကို ၎င်းတို့အပေါ် တည်ဆောက်ပါ။

Output items

OpenAI SDK များသည် message ၏ စာသားကို response.output_text တွင် သင့်အတွက် ပေါင်းပေးသည်။

Streaming

server-sent events အတွက် stream ကို true ဟု သတ်မှတ်ပါ။ frame တစ်ခုစီတွင် event အမည်ပါသော event: စာကြောင်းနှင့် JSON object ပါသော data: စာကြောင်း ပါသည်၊ object သည် အမည်ကို type တွင် ထပ်ဖော်ပြသည်။ delta များကို output_index ဖြင့် ၎င်းတို့၏ item နှင့် တွဲပါ။

OpenAI SDK ဖြင့် events များကို ၎င်းတို့၏ type အလိုက် ဖတ်ပါ-

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 များသည် ဤအစီအစဉ်ဖြင့် ရောက်လာသည်။ reasoning၊ message နှင့် tool calls အုပ်စုများသည် ပြန်ကြားချက်တွင် ရှိမှသာ ပေါ်လာသည်။

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

Shannon အဆင့်များတွင် ကျရှုံးသော ပြန်ကြားချက်သည် response.completed အစား response.failed ဖြင့် အဆုံးသတ်သည်။ ၎င်း၏ response.status သည် failed ဖြစ်ပြီး response.error တွင် code၊ rate_limit_exceeded သို့မဟုတ် server_error နှင့် message ပါသည်။

Host လုပ်ထားသော open-weight models များတွင် ကျရှုံးမှုသည် code api_error နှင့် message ပါသော error event ဖြစ်သည်။ ၎င်းနောက်တွင် response.completed ဆက်လာသေးသည်။

stream တွင် response.failed သို့မဟုတ် error event ပါလျှင် ကျရှုံးသည်ဟု သဘောထားပြီး request ကို ပြန်ပို့ပါ။

Tools

tool ဆိုသည်မှာ သင့် code run သော function တစ်ခုဖြစ်သည်။ ၎င်းကို tools တွင် ဖော်ပြပါ၊ model လိုချင်သောအခါ ပြန်ကြားချက်တွင် message အစား သို့မဟုတ် ၎င်းနှင့်အတူ function_call item ပါသည်။

tools ထဲရှိ tool အဓိပ္ပာယ်ဖွင့်ဆိုချက်-

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

ထို function ကို ခေါ်သော ပြန်ကြားချက်၏ output-

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

function ကို run ပြီး call နှင့် ၎င်း၏ ရလဒ်ကို input ထဲသို့ ထည့်ကာ request ကို ပြန်ပို့ပါ-

[
  {
    "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\"}"
  }
]

type function ပါသော tools များကိုသာ ဖတ်သည်။ shannon-1.6-*၊ shannon-2-* နှင့် shannon-coder-1 တွင် parameters schema ကို JSON Schema ၏ ဘုံ keyword များသို့ လျှော့ချသည်- oneOf ကို anyOf အဖြစ် ဖတ်ပြီး $ref၊ additionalProperties၊ const၊ default နှင့် title ကဲ့သို့ keyword များကို model သို့ မပေးပို့ပါ။

tool_choice တန်ဖိုး required နှင့် အမည်ပေးထားသော function ကို host လုပ်ထားသော open-weight models များက အသုံးပြုသည်။

tool loop ကို ၎င်း၏ ကိုယ်ပိုင်စာမျက်နှာတွင် အပြည့်အစုံ ဖော်ပြထားသည်။ လုပ်ဆောင်ချက် ခေါ်ဆိုမှု

Structured output

ဤ format တွင် structured output ကို text.format အဖြစ် ရေးသည်။ schema သည် Chat Completions ကဲ့သို့ json_schema member အောက်တွင် မဟုတ်ဘဲ name နှင့် strict ဘေးရှိ format ထဲတွင် တိုက်ရိုက် ရှိသည်။

• {"type": "json_object"} သည် JSON object မည်သည့်အရာမဆို တောင်းဆိုသည်။
• {"type": "json_schema", "name", "schema", "strict"} သည် သင့် schema အတိုင်းဖြစ်သော JSON ကို တောင်းဆိုသည်။ မထည့်လျှင် strict သည် true ဖြစ်သည်။

{
  "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 သည် message ၏ output_text part ထဲတွင် စာသားအဖြစ် ရောက်လာသည်၊ ကိုယ်တိုင် parse လုပ်ပါ။ structured output မရှိသော host လုပ်ထားသည့် open-weight model သည် 400 ကို ပြန်ပေးသည်။

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

ဘယ် model က ဘယ်ပုံစံကို လက်ခံသည်ကို ၎င်း၏ ကိုယ်ပိုင်စာမျက်နှာတွင် စာရင်းပြထားသည်။ ဖွဲ့စည်းထားသော အထွက်

Reasoning

reasoning လုပ်သော model သည် ၎င်း၏ reasoning ကို message မတိုင်မီ type reasoning ပါသော output item အဖြစ် ပြန်ပေးသည်။ stream တွင် ၎င်းသည် response.reasoning_summary_text.delta events အဖြစ် ရောက်လာသည်။

Host လုပ်ထားသော open-weight models များသည် reasoning.effort ကို အသုံးပြုသည်- off၊ low၊ medium သို့မဟုတ် high၊ ဘာမျှ မပို့လျှင် high ဖြစ်သည်။ off သည် reasoning item မပြန်ပေးပါ။ ၎င်းကို object အဖြစ် ပို့ပါ၊ ဤ endpoint တွင် သာမန် string ကို မဖတ်ပါ။

effort များကို ၎င်းတို့၏ ကိုယ်ပိုင်စာမျက်နှာတွင် ဖော်ပြထားသည်။ Reasoning effort

Output limit

max_output_tokens ကို မပို့လျှင် 4,096 ဖြစ်သည်။ ၎င်းသည် request စတင်သည့်အခါ သင့်လက်ကျန်ငွေမှ ဖယ်ထားသော tokens အရေအတွက် ဖြစ်ပြီး ပြန်ကြားချက် ပြီးမြောက်သောအခါ ထိုပမာဏကို request သုံးခဲ့သည့်ပမာဏဖြင့် အစားထိုးသည်။ သင့်လက်ကျန်ငွေထဲ မဆန့်သော တန်ဖိုးသည် 429 Quota exceeded ကို ပြန်ပေးသည်။

၎င်းသည် shannon-1.6-*၊ shannon-2-* နှင့် shannon-coder-1 တွင် ပြန်ကြားချက်၏ အရှည်ကို၊ host လုပ်ထားသော open-weight models တွင် အဖြေစာသား၏ အရှည်ကို ကန့်သတ်သည်။

ဤ endpoint တွင် shannon-coder-1 ကို အခြား model တိုင်းကဲ့သို့ သင့်လက်ကျန်ငွေမှ tokens ဖြင့် ကျသင့်ငွေတောင်းသည်။

request body သည် 32 MiB အထိ ရှိနိုင်သည်။ ကန့်သတ်ချက်များနှင့် လက်ကျန်ငွေ

အမှားများ

အမှားများသည် OpenAI error body ကို သုံးသည်- type နှင့် message ပါသော error object၊ အချို့တွင် တန်ဖိုး null ပါသော code နှင့် param ကိုလည်း ပါသည်။ ဇယားသည် ဤ endpoint က အများဆုံး ပြန်ပေးသည့်အရာကို စာရင်းပြသည်။ ပြန်ကြိုးစားရမည့်အရာများပါသည့် စာရင်းအပြည့်အစုံတွင် ကိုယ်ပိုင်စာမျက်နှာရှိသည်။ အမှားကိုင်တွယ်မှု