Responses API

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

Codsiga ugu yar waa id model iyo qoraal. Jawaabtu stream ma aha haddii aadan codsan.

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

Jawaabtu waa shay jawaab ah. output kiisu wuxuu haystaa reasoning-ka, marka model-ku fikiray, iyo fariinta:

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

Field-yada codsiga

model iyo input waa waxa codsigu u baahan yahay. Tiirka Waxay dabaqaan wuxuu magacaabayaa model-yada field-ku jawaabta ku beddelo. Model-yada open-weight ee la martigeliyo waa laba iyo toban id oo ka mid ah liiska model-yada; qoyska Shannon 3 waa shannon-3, shannon-3-pro, shannon-3.1 iyo shannon-3.1-pro. Model-yo & qiimo

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user iyo prompt_cache_key waa la aqbalaa si code-ka macmiilka ee jira u shaqeeyo isbeddel la'aan. Jawaabta ma beddelaan. Maadaama wada-hadal la ma keydiyo, codsi xiga wuxuu wareegyada hore ku sidaa input.

Input items

Input item waa fariin, oo leh role iyo content, ama shay nooc leh oo sida wicitaan tool ama natiijadiisa. content waa string ama array ah qaybo.

Tilmaamaha geli field-ka instructions. Id qoyska Shannon 3 la isticmaalayo, tilmaamaha waajibka ah geli fariinta user.

Shayada output ee jawaab waxay dib ugu laaban karaan input sida ay yihiin: shayada message iyo function_call waa la akhriyaa, shayada reasoning waa la ka boodaa.

Qaybaha nuxurka

Heerarka Shannon sawirrada iyo faylasha waxaa laga akhriyaa shayga user ee ugu dambeeya ee input. Cabbirrada iyo xadadku waxay leeyihiin bog u gaar ah. Sawirro iyo faylal

Codsi leh instructions iyo ikhtiyaaro

Codsigani wuxuu diraa instructions, wada-hadal sida input items, xad output, temperature iyo reasoning effort. Wuxuu isticmaalaa model open-weight oo la martigeliyay, kaas oo dabaqa dhammaantood.

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

Jawaabta model open-weight oo la martigeliyay waxay leedahay id, object, model, created_at, status, output iyo usage. usage kiisu wuxuu ku daraa token-yada laga akhriyay cache iyo token-yada loo isticmaalay reasoning:

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

Shayga jawaabta

id, object, status, output iyo usage waxay ku yaalliin jawaab kasta. Code-kaaga ku dhis kuwaas.

Output items

SDK-yada OpenAI waxay kuu isku xiraan qoraalka fariinta response.output_text.

Streaming

Deji stream true si aad u hesho server-sent events. Frame kasta wuxuu leeyahay xariiq event: oo leh magaca event-ka iyo xariiq data: oo leh shay JSON ah; shaygu wuxuu magaca ku celiyaa type. Deltas-ka shayadooda ku waafaji output_index.

SDK OpenAI, events-ka ku akhri type kooda:

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-ku waxay u yimaadaan sidan. Kooxaha reasoning, fariinta iyo wicitaannada tool waxay muuqdaan marka jawaabtu leedahay oo keliya.

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 fashilma

Heerarka Shannon jawaab fashilantay waxay ku dhammaataa response.failed halkii response.completed. response.status kiisu waa failed response.error-na wuxuu haystaa code, rate_limit_exceeded ama server_error, iyo message.

Model-yada open-weight ee la martigeliyo fashil waa event error oo leh code api_error iyo message. response.completed weli wuu raacaa.

Stream u aqoon sida fashilmay marka uu haysto event response.failed ama error, oo mar kale dir codsiga.

Tools

Tool waa function uu code-kaagu ordo. Ku sharax tools; marka model-ku rabo, jawaabtu waxay haysaa shay function_call fariinta meeshiisa, ama agteeda.

Qeexida tool ee tools:

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

output ee jawaab wacda:

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

Orod function-ka, kaddib mar kale dir codsiga adigoo wicitaanka iyo natiijadiisa ku darayay 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\"}"
  }
]

Kaliya tools-ka nooca function ayaa la akhriyaa. shannon-1.6-*, shannon-2-* iyo shannon-coder-1 schema-ha parameters waxaa loo dhimaa erayada JSON Schema ee guud: oneOf waxaa loo akhriyaa sida anyOf, erayada sida $ref, additionalProperties, const, default iyo title model-ka looma gudbiyo.

Qiimayaasha tool_choice ee required iyo function la magacaabay waxaa dabaqa model-yada open-weight ee la martigeliyo.

Wareegga tool-ka si buuxda ayaa loogu sharaxay bog u gaar ah. Wacyigelinta Shaqada

Structured output

Qaabkani structured output wuxuu u qoraa text.format. Schema-hu wuxuu si toos ah ugu jiraa format, name iyo strict agtooda, ma aha xubin json_schema hoosteeda sida Chat Completions.

• {"type": "json_object"} wuxuu codsadaa shay JSON ah oo kasta.
• {"type": "json_schema", "name", "schema", "strict"} wuxuu codsadaa JSON raacaya schema-gaaga. strict waa true marka aad reebto.

{
  "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-ku wuxuu u yimaadaa sida qoraal qaybta output_text ee fariinta; adigu parse-garee. Model open-weight oo la martigeliyay oo aan lahayn structured output wuxuu soo celiyaa 400.

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

Model kasta qaabka uu qaato wuxuu ku liis garaysan yahay bog u gaar ah. Waxsoosaarka qaabaysan

Reasoning

Model fikiraya wuxuu reasoning-kiisa soo celiyaa sida output item oo nooca reasoning ah, ka hor fariinta. Stream dhexdiisa wuxuu u yimaadaa sida events response.reasoning_summary_text.delta.

Model-yada open-weight ee la martigeliyo waxay dabaqaan reasoning.effort: off, low, medium ama high, high marka aadan waxba dirin. off shay reasoning ah ma soo celiyo. U dir sida shay; string cirro ah endpoint-kan lagu ma akhriyo.

Effort-yada waxaa lagu sharaxay bog u gaar ah. Effort-ka reasoning-ka

Xadka output-ka

max_output_tokens waa 4,096 marka aadan dirin. Waa tirada token-yada laga kala dhigo haraaggaaga marka codsigu bilaabmo; marka jawaabtu dhammaato, cadadkaas waxaa lagu beddelaa waxa codsigu isticmaalay. Qiime aan ku soo galin haraaggaaga hadhay wuxuu soo celiyaa 429 Quota exceeded.

Wuxuu xadidaa dhererka jawaabta shannon-1.6-*, shannon-2-* iyo shannon-coder-1, iyo dhererka qoraalka jawaabta model-yada open-weight ee la martigeliyo.

Endpoint-kan shannon-coder-1 waxaa lagu dallacaa token-yo haraaggaaga, sida model kasta oo kale.

Jidhka codsigu wuxuu noqon karaa ilaa 32 MiB. Xadad iyo haraag

Khaladaad

Khaladaadku waxay isticmaalaan jidhka khaladka OpenAI: shay error oo leh type iyo message; qaarna waxay sidaan code iyo param oo qiimahoodu yahay null. Shaxdu waxay liis garaynaysaa waxa endpoint-kani inta badan soo celiyo. Liiska buuxa, oo ay la socoto waxa dib loo tijaabiyo, wuxuu leeyahay bog u gaar ah. Khaladaadka Maareynta