Responses API

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

කුඩාම ඉල්ලීම යනු 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 එකකි. Model එක තර්ක කළ විට, එහි output හි තර්කනය සහ පණිවිඩය ඇත:

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

ඉල්ලීමකට අවශ්‍ය වන්නේ model සහ input ය. Applied by තීරුවේ field එකක් පිළිතුර වෙනස් කරන models නම් කර ඇත. අපගේ සේවාදායකවල ධාවනය වන open-weight models යනු model ලැයිස්තුවේ ඇති id දොළහයි; Shannon 3 පවුල යනු shannon-3, shannon-3-pro, shannon-3.1 සහ shannon-3.1-pro ය. Models සහ මිල ගණන්

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user සහ prompt_cache_key දැනට ඇති client code වෙනසක් නොමැතිව ක්‍රියා කිරීම සඳහා පිළිගනී. ඒවා පිළිතුර වෙනස් නොකරයි. සංවාදයක් ගබඩා නොකරන බැවින්, පසු ඉල්ලීමක පෙර turns input හි රැගෙන යයි.

Input items

Input item එකක් යනු role එකක් සහ content එකක් සහිත පණිවිඩයක්, නැතහොත් tool call එකක් හෝ එහි ප්‍රතිඵලයක් රැගෙන යන type සහිත item එකකි. content යනු string එකක් හෝ කොටස් array එකකි.

උපදෙස් instructions field එකේ තබන්න. Shannon 3 පවුලේ id එකක් සමඟ, අනිවාර්යයෙන් පිළිපැදිය යුතු උපදෙස් user පණිවිඩයට ඇතුළත් කරන්න.

පිළිතුරක output හි items එලෙසම input වෙත ආපසු යැවිය හැක: message සහ function_call items කියවයි, reasoning items මඟ හරියි.

අන්තර්ගත කොටස්

Shannon tiers මත රූප සහ ගොනු කියවන්නේ input හි අවසාන user item එකෙනි. ප්‍රමාණ සහ සීමා වලට තමන්ගේම පිටුවක් ඇත. රූප සහ ගොනු

උපදෙස් සහ විකල්ප සහිත ඉල්ලීමක්

මෙම ඉල්ලීම උපදෙස්, input items ලෙස සංවාදයක්, output සීමාවක්, temperature එකක් සහ reasoning effort එකක් යවයි. එය ඒ සියල්ල ක්‍රියාත්මක කරන, අපගේ සේවාදායකවල ධාවනය වන 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"}
  }'

අපගේ සේවාදායකවල ධාවනය වන open-weight model එකක පිළිතුරේ id, object, model, created_at, status, output සහ usage ඇත. එහි usage cache එකෙන් කියවූ tokens සහ තර්කනයට වැය වූ 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 SDKs පණිවිඩයේ පෙළ ඔබ වෙනුවෙන් response.output_text හි එකට සම්බන්ධ කරයි.

Streaming

Server-sent events සඳහා stream true ලෙස සකසන්න. සෑම frame එකකම event එකේ නම සහිත event: පේළියක් සහ JSON object එකක් සහිත data: පේළියක් ඇත; object එක type හි එම නම නැවත දක්වයි. Deltas ඒවායේ item එකට output_index මගින් ගළපන්න.

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 පැමිණෙන්නේ මෙම පිළිවෙලටයි. තර්කනය, පණිවිඩය සහ 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 tiers මත අසාර්ථක පිළිතුරක් response.completed වෙනුවට response.failed සමඟ අවසන් වේ. එහි response.status failed වන අතර response.error හි code, rate_limit_exceeded හෝ server_error, සහ message එකක් ඇත.

අපගේ සේවාදායකවල ධාවනය වන open-weight models මත අසාර්ථකත්වයක් යනු code api_error සහ message එකක් සහිත error event එකකි. response.completed තවමත් ඊට පසුව පැමිණේ.

Stream එකක response.failed හෝ error event එකක් ඇති විට එය අසාර්ථක ලෙස සලකා, ඉල්ලීම නැවත යවන්න.

Tools

Tool එකක් යනු ඔබේ code එක ක්‍රියාත්මක කරන function එකකි. එය tools හි විස්තර කරන්න; model එකට එය අවශ්‍ය වූ විට, පිළිතුරේ පණිවිඩය වෙනුවට හෝ ඒ අසල 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"
      ]
    }
  }
]

එය call කරන පිළිතුරක output:

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

Function එක ක්‍රියාත්මක කර, ඉන්පසු call එක සහ එහි ප්‍රතිඵලය 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\"}"
  }
]

කියවන්නේ function type එකේ tools පමණි. shannon-1.6-*, shannon-2-* සහ shannon-coder-1 මත parameters schema එක පොදු JSON Schema මූල පද දක්වා අඩු කෙරේ: oneOf anyOf ලෙස කියවන අතර, $ref, additionalProperties, const, default සහ title වැනි මූල පද model එකට ලබා නොදේ.

tool_choice අගයන් required සහ නම් කළ function එකක් ක්‍රියාත්මක කරන්නේ අපගේ සේවාදායකවල ධාවනය වන open-weight models ය.

Tool loop එක සම්පූර්ණයෙන් තමන්ගේම පිටුවේ විස්තර කර ඇත. කාර්ය කැඳවීම

ව්‍යුහගත output

මෙම format එක ව්‍යුහගත 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 පැමිණෙන්නේ පණිවිඩයේ output_text කොටසේ පෙළක් ලෙසය; එය ඔබම parse කරන්න. ව්‍යුහගත output නැති, අපගේ සේවාදායකවල ධාවනය වන open-weight model එකක් 400 ආපසු දෙයි.

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

කුමන model එක කුමන ආකාරය පිළිගනීද යන්න එහිම පිටුවේ ලැයිස්තුගත කර ඇත. ව්‍යුහගත ප්‍රතිදාන

තර්කනය

තර්ක කරන model එකක් එහි තර්කනය පණිවිඩයට පෙර reasoning type එකේ output item එකක් ලෙස ආපසු දෙයි. Stream එකක එය response.reasoning_summary_text.delta events ලෙස පැමිණේ.

අපගේ සේවාදායකවල ධාවනය වන open-weight models reasoning.effort ක්‍රියාත්මක කරයි: off, low, medium හෝ high, ඔබ කිසිවක් නොයවන විට high. off reasoning item එකක් ආපසු නොදෙයි. එය object එකක් ලෙස යවන්න; මෙම endpoint හි හුදෙක් string එකක් කියවන්නේ නැත.

Efforts ගැන තමන්ගේම පිටුවේ විස්තර කර ඇත. Reasoning effort

Output සීමාව

ඔබ එය නොයවන විට max_output_tokens 4,096 වේ. ඉල්ලීම ආරම්භ වන විට ඔබේ ශේෂයෙන් වෙන් කර තබන tokens ගණන එයයි; පිළිතුර සම්පූර්ණ වූ විට, එම ප්‍රමාණය ඉල්ලීම භාවිතා කළ ප්‍රමාණයෙන් ප්‍රතිස්ථාපනය වේ. ඔබේ ඉතිරි ශේෂයට නොගැළපෙන අගයකට 429 Quota exceeded ලැබේ.

එය shannon-1.6-*, shannon-2-* සහ shannon-coder-1 මත පිළිතුරේ දිග ද, අපගේ සේවාදායකවල ධාවනය වන open-weight models මත පිළිතුරේ පෙළේ දිග ද සීමා කරයි.

මෙම endpoint හි shannon-coder-1 වෙනත් සෑම model එකක් මෙන් ඔබේ ශේෂයෙන් tokens වලින් අය කෙරේ.

ඉල්ලීමේ body එක 32 MiB දක්වා විය හැක. සීමා සහ ශේෂය

දෝෂ

දෝෂ OpenAI දෝෂ body එක භාවිතා කරයි: type සහ message සහිත error object එකක්; සමහරක null අගය සහිත code සහ param ද ඇත. වගුවේ මෙම endpoint එක බොහෝ විට ආපසු දෙන දේ ලැයිස්තුගත කර ඇත. නැවත උත්සාහ කළ යුතු දේ සහිත සම්පූර්ණ ලැයිස්තුවට තමන්ගේම පිටුවක් ඇත. දෝෂ