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 нь загвар reasoning хийсэн бол reasoning-ийг, мөн мессежийг агуулна:

{
  "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 хэрэгтэй. Хэрэгжүүлэгч багана талбар хариуг өөрчилдөг загваруудыг нэрлэнэ. Hosted 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 дотор агуулна.

Оролтын зүйлс

Оролтын зүйл нь role ба content-той мессеж, эсвэл tool дуудлага эсвэл түүний үр дүнг агуулсан төрөлтэй зүйл. content нь string эсвэл хэсгүүдийн массив.

Зааврыг instructions талбарт оруулна уу. Shannon 3 гэр бүлийн id-тай бол заавал мөрдөх зааврыг user мессежид оруулна уу.

Хариуны output зүйлсийг input руу хэвээр нь буцааж болно: message ба function_call зүйлсийг уншиж, reasoning зүйлсийг алгасна.

Агуулгын хэсгүүд

Shannon түвшнүүд дээр зураг, файлыг input-ийн сүүлийн user зүйлээс уншина. Хэмжээ, хязгаар нь тусдаа хуудастай. Зураг ба файл

Заавар ба сонголттой хүсэлт

Энэ хүсэлт заавар, оролтын зүйл хэлбэрийн харилцан яриа, гаралтын хязгаар, temperature ба reasoning effort илгээнэ. Бүгдийг хэрэгжүүлдэг hosted 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"}
  }'

Hosted open-weight загварын хариу id, object, model, created_at, status, output ба usage-тэй. Түүний usage нь кэшээс уншсан токен ба reasoning-д зарцуулсан токеныг нэмж агуулна:

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

Response объект

id, object, status, output ба usage хариу бүрд байна. Кодоо эдгээр дээр түшиглэн бичнэ үү.

Гаралтын зүйлс

OpenAI SDK-ууд мессежийн текстийг response.output_text дотор таны оронд залгана.

Streaming

Server-sent events авахын тулд stream-ийг true болгоно уу. Frame бүр event-ийн нэртэй event: мөр ба JSON объекттой data: мөртэй; объект нэрийг type дотор давтана. Delta-г output_index-ээр зүйлтэй нь тааруулна.

OpenAI SDK-тай event-үүдийг 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-үүд дараах дарааллаар ирнэ. Reasoning, мессеж, tool дуудлагын бүлэг хариунд байгаа үед л гарна.

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 нь rate_limit_exceeded эсвэл server_error гэсэн code ба message агуулна.

Hosted open-weight загварууд дээр алдаа нь code нь api_error, message-тэй error event байна. Түүний дараа response.completed мөн л дагана.

Stream response.failed эсвэл error event агуулсан бол амжилтгүй гэж үзэж, хүсэлтийг дахин илгээнэ үү.

Tools

Tool бол таны кодын ажиллуулдаг функц. Үүнийг tools дотор тайлбарлана; загвар хүсэхэд хариу мессежийн оронд эсвэл хажууд function_call зүйл агуулна.

tools дэх tool тодорхойлолт:

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

Функцээ ажиллуулаад, дуудлага ба түүний үр дүнг 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 төрлийн tool-ийг уншина. shannon-1.6-*, shannon-2-* ба shannon-coder-1 дээр parameters schema нь нийтлэг JSON Schema түлхүүр үг болтол багасгагдана: oneOf-ийг anyOf гэж уншиж, $ref, additionalProperties, const, default, title зэрэг түлхүүр үгсийг загварт дамжуулахгүй.

tool_choice-ийн required болон нэрлэсэн функц утгыг hosted open-weight загварууд хэрэгжүүлнэ.

Tool давталтыг тусдаа хуудсанд бүрэн тайлбарласан. Функц дуудлага

Бүтэцтэй гаралт

Энэ формат бүтэцтэй гаралтыг text.format гэж бичнэ. Schema нь Chat Completions дээрх шиг json_schema гишүүний дор биш, name ба strict-ийн хажууд format дотор шууд байрлана.

• {"type": "json_object"} нь дурын JSON объект хүснэ.
• {"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 хийнэ үү. Бүтэцтэй гаралтгүй hosted open-weight загвар 400 буцаана.

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

Аль загвар аль хэлбэрийг авдгийг тусдаа хуудсанд жагсаасан. Бүтэцтэй гаралт

Reasoning

Reasoning хийдэг загвар reasoning-ээ мессежийн өмнө reasoning төрлийн гаралтын зүйл болгон буцаана. Stream дээр response.reasoning_summary_text.delta event хэлбэрээр ирнэ.

Hosted open-weight загварууд reasoning.effort-ийг хэрэгжүүлнэ: off, low, medium эсвэл high, юу ч илгээгээгүй бол high. off нь reasoning зүйл буцаахгүй. Объект хэлбэрээр илгээнэ үү; энэ endpoint дээр зүгээр string-ийг уншдаггүй.

Effort-уудыг тусдаа хуудсанд тайлбарласан. Reasoning effort

Гаралтын хязгаар

max_output_tokens нь илгээгээгүй үед 4,096. Энэ нь хүсэлт эхлэхэд таны үлдэгдлээс нөөцлөх токены тоо; хариу бүрэн болоход тэр хэмжээг хүсэлтийн ашигласанаар сольдог. Үлдсэн үлдэгдэлд багтахгүй утга 429 Quota exceeded буцаана.

Энэ нь shannon-1.6-*, shannon-2-* ба shannon-coder-1 дээр хариуны уртыг, hosted open-weight загварууд дээр хариултын текстийн уртыг хязгаарлана.

Энэ endpoint дээр shannon-coder-1-ийг бусад загварын адил үлдэгдлээс токеноор тооцно.

Хүсэлтийн body 32 MiB хүртэл байж болно. Хязгаар ба үлдэгдэл

Алдаа

Алдаа OpenAI-ийн алдааны body-г ашиглана: type ба message-тэй error объект; зарим нь null утгатай code ба param-г бас агуулна. Хүснэгт энэ endpoint-ийн хамгийн түгээмэл буцаадгийг жагсаана. Бүрэн жагсаалт, юуг дахин оролдохтой нь тусдаа хуудастай. Алдаа боловсруулах