Responses API

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

Эң кичинекей сурам — модель id жана текст. Сиз сурабасаңыз, жооп стримделбейт.

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

Жооп — жооп объекти. Анын 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 керек. Колдонот тилкеси талаа жоопту өзгөрткөн моделдерди атайт. Хостингдеги ачык салмактуу моделдер — модель тизмесиндеги он эки 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 бар билдирүү, же курал чалуусун же анын натыйжасын алып жүргөн түрдүү элемент. content — сап же бөлүктөрдүн массиви.

Нускамаларды instructions талаасына салыңыз. Shannon 3 үй-бүлөсүнүн id'си менен сакталышы керек болгон нускамаларды user билдирүүсүнө салыңыз.

Жооптун output элементтери input ичине өзгөрүүсүз кайра кире алат: message жана function_call элементтери окулат, reasoning элементтери өткөрүлүп жиберилет.

Мазмун бөлүктөрү

Shannon деңгээлдеринде сүрөттөр менен файлдар input ичиндеги акыркы user элементинен окулат. Өлчөмдөр жана чектөөлөр өз бетинде. Сүрөттөр жана файлдар

Нускамалар жана опциялар менен сурам

Бул сурам нускамаларды, киргизүү элементтери катары сүйлөшүүнү, чыгыш чегин, температураны жана reasoning аракетин жөнөтөт. Ал алардын баарын колдонгон хостингдеги ачык салмактуу моделди колдонот.

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

Хостингдеги ачык салмактуу модельдин жообунда 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
  }
}

Жооп объекти

id, object, status, output жана usage ар бир жоопто бар. Кодуңузду ушуларга курсаңыз болот.

Чыгыш элементтери

OpenAI SDK'лары билдирүүнүн текстин сиз үчүн response.output_text ичинде бириктирет.

Стриминг

server-sent events үчүн stream'ди true кылыңыз. Ар бир фреймде окуянын аты бар event: сабы жана JSON объекти бар data: сабы бар; объект атты type ичинде кайталайт. Дельталарды өз элементине output_index боюнча байлаңыз.

OpenAI SDK менен окуяларды 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
  }'

Окуялар ушул тартипте келет. Reasoning, билдирүү жана курал чалуулары топтору жоопто алар болгондо гана пайда болот.

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}, …}}

Ишке ашпаган стрим

Shannon деңгээлдеринде ишке ашпаган жооп response.completed ордуна response.failed менен аяктайт. Анын response.status — failed, ал эми response.error code, rate_limit_exceeded же server_error, жана message камтыйт.

Хостингдеги ачык салмактуу моделдерде ката code api_error жана message бар error окуясы. response.completed андан кийин да келет.

Стримде response.failed же error окуясы болсо, аны ишке ашпады деп эсептеп, сурамды кайра жөнөтүңүз.

Куралдар

Курал — коддуңуз аткарган функция. Аны 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\"}"
  }
]

Функцияны аткарыңыз, андан кийин сурамды чалууну жана анын натыйжасын 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 боюнча parameters схемасы жалпы JSON Schema ачкыч сөздөрүнө чейин кыскартылат: oneOf anyOf катары окулат, ал эми $ref, additionalProperties, const, default жана title сыяктуу ачкыч сөздөр моделге өткөрүлбөйт.

tool_choice маанилери required жана аталган функцияны хостингдеги ачык салмактуу моделдер колдонот.

Курал цикли өз бетинде толук сүрөттөлгөн. Функция чакыруу

Структураланган чыгыш

Бул формат структураланган чыгышты text.format деп жазат. Схема Chat Completions'тагыдай json_schema мүчөсүнүн астында эмес, format ичинде name жана strict жанында түз турат.

• {"type": "json_object"} каалаган JSON объектин сурайт.
• {"type": "json_schema", "name", "schema", "strict"} схемаңызга ылайык 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 бөлүгүндө текст катары келет; аны өзүңүз талдаңыз. Структураланган чыгышы жок хостингдеги ачык салмактуу модель 400 кайтарат.

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

Кайсы модель кайсы форманы кабыл алары өз бетинде тизмеленген. Түзүмдүү чыгыштар

Reasoning

Reasoning жүргүзгөн модель өзүнүн reasoning'ин билдирүүнүн алдында reasoning түрүндөгү чыгыш элементи катары кайтарат. Стримде ал response.reasoning_summary_text.delta окуялары катары келет.

Хостингдеги ачык салмактуу моделдер reasoning.effort колдонот: off, low, medium же high, эч нерсе жөнөтпөсөңүз high. off reasoning элементин кайтарбайт. Аны объект катары жөнөтүңүз; бул endpoint'те жылаңач сап окулбайт.

Аракеттер өз бетинде сүрөттөлгөн. Reasoning аракет деңгээли

Чыгыш чеги

max_output_tokens жөнөтпөсөңүз 4,096. Бул сурам башталганда балансыңыздан резервделген токендердин саны; жооп толук болгондо ал сумма сурам колдонгон менен алмаштырылат. Калган балансыңызга батпаган маани 429 Quota exceeded кайтарат.

Ал shannon-1.6-*, shannon-2-* жана shannon-coder-1 боюнча жооптун узундугун, ал эми хостингдеги ачык салмактуу моделдерде жооп текстинин узундугун чектейт.

Бул endpoint'те shannon-coder-1 башка ар бир модель сыяктуу балансыңыздан токен менен эсептелет.

Сурам денеси 32 MiB'ге чейин болушу мүмкүн. Чектөөлөр жана баланс

Каталар

Каталар OpenAI ката денесин колдонот: type жана message бар error объекти; кээ бирлери null маанилүү code жана param да алып келет. Таблица бул endpoint эң көп кайтарганды тизмелейт. Эмнени кайра жөнөтүү керек экени менен толук тизме өз бетинде. Ката иштетүү