Responses API

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

بچووکترین داواکاری 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 ە. 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
  }
}

بوارەکانی داواکاری

model و input ئەوەن کە داواکارییەک پێویستییەتی. ستوونی جێبەجێ دەکرێت لەلایەن ئەو مۆدێلانە ناو دەبات کە بوارێک وەڵامەکەیان تێدا دەگۆڕێت. مۆدێلە open-weight ـە میوانداریکراوەکان ئەو دوازدە id ـەن کە لە لیستی مۆدێلەکاندان؛ بنەماڵەی Shannon 3 shannon-3، shannon-3-pro، shannon-3.1 و shannon-3.1-pro ە. مۆدێل و نرخ

previous_response_id، store، metadata، parallel_tool_calls، truncation، include، user و prompt_cache_key وەردەگیرێن بۆ ئەوەی کۆدی کلاینتی هەبوو بێ گۆڕان کار بکات. وەڵامەکە ناگۆڕن. چونکە هیچ گفتوگۆیەک پاشەکەوت ناکرێت، داواکارییەکی دواتر نۆرە پێشووەکان لە input دا هەڵدەگرێت.

Input items

ئایتمی input یان نامەیە، بە role و content، یان ئایتمێکی جۆردارە کە بانگکردنی ئامرازێک یان ئەنجامەکەی هەڵدەگرێت. content string ە یان ئارەیەک لە بەش.

ڕێنماییەکان لە بواری instructions دابنێ. لەگەڵ id ی بنەماڵەی Shannon 3، ئەو ڕێنماییانەی دەبێت بمێنن بخەرە ناو نامەی user.

ئایتمەکانی output ی وەڵامێک دەتوانن وەک خۆیان بگەڕێنەوە بۆ input: ئایتمەکانی message و function_call دەخوێنرێنەوە، ئایتمەکانی reasoning تێدەپەڕێنرێن.

بەشەکانی ناوەڕۆک

لەسەر ئاستەکانی Shannon وێنە و فایلەکان لە دوایین ئایتمی user ی input دەخوێنرێنەوە. قەبارە و سنوورەکان لاپەڕەی تایبەتی خۆیان هەیە. وێنە و فایلەکان

داواکارییەک لەگەڵ ڕێنمایی و بژاردەکان

ئەم داواکارییە ڕێنمایی، گفتوگۆیەک وەک ئایتمی input، سنووری output، temperature و ئاستی بیرکردنەوە دەنێرێت. مۆدێلێکی open-weight ی میوانداریکراو بەکاردەهێنێت کە هەموویان جێبەجێ دەکات.

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 ی میوانداریکراو id، object، model، created_at، status، output و usage ی هەیە. usage ـەکەی ئەو تۆکنانە زیاد دەکات کە لە cache خوێندراونەتەوە و ئەوانەی بۆ بیرکردنەوە خەرج کراون:

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

ئۆبجێکتی وەڵام

id، object، status، output و usage لەسەر هەموو وەڵامێک هەن. کۆدەکەت لەسەر ئەوانە بنیات بنێ.

ئایتمەکانی output

SDK ـەکانی OpenAI دەقی نامەکە بۆت لە response.output_text دا یەک دەخەنەوە.

Streaming

stream بکە بە true بۆ server-sent events. هەر frame ێک هێڵی event: ی هەیە لەگەڵ ناوی ڕووداوەکە و هێڵی data: لەگەڵ ئۆبجێکتێکی JSON؛ ئۆبجێکتەکە ناوەکە لە type دا دووبارە دەکاتەوە. delta ـەکان بە output_index لەگەڵ ئایتمەکەیان جووت بکە.

لەگەڵ SDK ی OpenAI، ڕووداوەکان بە 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
  }'

ڕووداوەکان بەم ڕیزبەندییە دەگەن. گرووپەکانی بیرکردنەوە، نامە و بانگکردنی ئامراز تەنها کاتێک دەردەکەون کە وەڵامەکە هەیانبێت.

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.failed کۆتایی دێت لە جێی response.completed. response.status ـەکەی failed ە و response.error code ێک، rate_limit_exceeded یان server_error، و message ێک هەڵدەگرێت.

لەسەر مۆدێلە open-weight ـە میوانداریکراوەکان شکست ڕووداوی error ە لەگەڵ code ی api_error و message ێک. response.completed هێشتا دوای ئەو دێت.

stream وەک شکستخواردوو ببینە کاتێک response.failed یان ڕووداوی error هەڵدەگرێت، و داواکارییەکە دووبارە بنێرە.

Tools

ئامراز function ێکە کە کۆدەکەت جێبەجێی دەکات. لە tools دا وەسفی بکە؛ کاتێک مۆدێلەکە دەیەوێت، وەڵامەکە ئایتمێکی function_call هەڵدەگرێت لە جێی نامەکە، یان لەتەنیشتی.

پێناسەی ئامراز لە tools دا:

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

output ی وەڵامێک کە بانگی دەکات:

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

function ـەکە جێبەجێ بکە، پاشان داواکارییەکە دووبارە بنێرە لەگەڵ بانگکردنەکە و ئەنجامەکەی زیادکراو بۆ 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 دەخوێنرێنەوە. لەسەر shannon-1.6-*، shannon-2-* و shannon-coder-1 schema ی parameters بۆ وشە کلیلییە گشتییەکانی JSON Schema کورت دەکرێتەوە: oneOf وەک anyOf دەخوێنرێتەوە، و وشە کلیلییەکانی وەک $ref، additionalProperties، const، default و title نادرێنە مۆدێلەکە.

بەهاکانی tool_choice ی required و function ی ناونراو لەلایەن مۆدێلە open-weight ـە میوانداریکراوەکانەوە جێبەجێ دەکرێن.

خولی ئامراز بە تەواوی لە لاپەڕەی تایبەتی خۆی باس کراوە. Bangkirina fonksiyonê

Structured output

ئەم فۆرماتە output ی structured وەک text.format دەنووسێت. schema ڕاستەوخۆ لە format دایە، لەتەنیشت name و strict، نەک لەژێر ئەندامی json_schema وەک لە Chat Completions.

• {"type": "json_object"} هەر ئۆبجێکتێکی JSON داوا دەکات.
• {"type": "json_schema", "name", "schema", "strict"} JSON ێک داوا دەکات کە schema ـکەی تۆ دەگرێتەبەر. 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 ی بکە. مۆدێلێکی open-weight ی میوانداریکراو بەبێ output ی structured 400 دەگەڕێنێتەوە.

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

کام مۆدێل کام شێواز وەردەگرێت لە لاپەڕەی تایبەتی خۆی لیست کراوە. Derketinên strukturkirî

بیرکردنەوە

مۆدێلێک کە بیر دەکاتەوە بیرکردنەوەکەی وەک ئایتمێکی output ی جۆری reasoning دەگەڕێنێتەوە، پێش نامەکە. لە stream دا وەک ڕووداوەکانی response.reasoning_summary_text.delta دەگات.

مۆدێلە open-weight ـە میوانداریکراوەکان reasoning.effort جێبەجێ دەکەن: off، low، medium یان high، بە high کاتێک هیچ نانێریت. off هیچ ئایتمێکی reasoning ناگەڕێنێتەوە. وەک ئۆبجێکت بینێرە؛ string ی سادە لەسەر ئەم endpoint ـە ناخوێنرێتەوە.

ئاستەکان لە لاپەڕەی تایبەتی خۆیاندا باس کراون. ئاستی بیرکردنەوە

Output limit

max_output_tokens 4,096 ە کاتێک ناینێریت. ئەو ژمارە تۆکنەیە کە لە باڵانسەکەت ڕادەگیرێت کاتێک داواکارییەکە دەست پێدەکات؛ کاتێک وەڵامەکە تەواو بوو، ئەو بڕە بەوەی داواکارییەکە بەکاری هێناوە دەگۆڕدرێت. بەهایەک کە لەگەڵ ماوەی باڵانسەکەت نەگونجێت 429 Quota exceeded دەگەڕێنێتەوە.

درێژی وەڵام سنووردار دەکات لەسەر shannon-1.6-*، shannon-2-* و shannon-coder-1، و درێژی دەقی وەڵام لەسەر مۆدێلە open-weight ـە میوانداریکراوەکان.

لەسەر ئەم endpoint ـە shannon-coder-1 بە تۆکن لە باڵانسەکەت نرخ دەگیرێت، وەک هەموو مۆدێلێکی دیکە.

body ی داواکاری دەتوانێت تا 32 MiB بێت. سنوور و باڵانس

هەڵەکان

هەڵەکان body ی هەڵەی OpenAI بەکاردەهێنن: ئۆبجێکتی error بە type و message؛ هەندێکیان code و param یش هەڵدەگرن بە بەهای null. خشتەکە ئەوە لیست دەکات کە ئەم endpoint ـە زۆرتر دەیگەڕێنێتەوە. لیستی تەواو، لەگەڵ ئەوەی چی دووبارە بکرێتەوە، لاپەڕەی تایبەتی خۆی هەیە. Çewtî