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

Жауап — 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 қажет. Қолданатындар бағанасы өріс жауапты өзгертетін модельдерді атайды. 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 бар хабарлама, немесе құрал шақыруын не оның нәтижесін алып жүретін типтелген элемент. content — жол немесе бөліктер массиві.

Нұсқауларды instructions өрісіне қойыңыз. Shannon 3 тобының id-імен орындалуы міндетті нұсқауларды user хабарламасына қойыңыз.

Жауаптың output элементтері input ішіне өзгеріссіз қайта берілуі мүмкін: message және function_call элементтері оқылады, reasoning элементтері өткізіліп жіберіледі.

Мазмұн бөліктері

Shannon деңгейлерінде суреттер мен файлдар input ішіндегі соңғы user элементінен оқылады. Көлемдер мен лимиттердің өз беті бар. Суреттер және файлдар

Нұсқаулары мен опциялары бар сұрау

Бұл сұрау нұсқауларды, енгізу элементтері түріндегі сөйлесуді, шығыс лимитін, температураны және пайымдау күшін жібереді. Ол барлығын қолданатын 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 мәліметіне кэштен оқылған токендер мен пайымдауға жұмсалған токендер қосылады:

{
  "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 ішіне біріктіреді.

Streaming

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

Оқиғалар осы ретпен келеді. Пайымдау, хабарлама және құрал шақырулары топтары жауапта бар болғанда ғана пайда болады.

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 бар.

Hosted open-weight модельдерде ақау 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 және атаулы функцияны hosted open-weight модельдер қолданады.

Құрал циклі өз бетінде толық сипатталған. Функция шақыру

Құрылымдалған шығыс

Бұл формат құрылымдалған шығысты 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 бөлігінде келеді; оны өзіңіз парсинг жасаңыз. Құрылымдалған шығысы жоқ hosted open-weight модель 400 қайтарады.

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

Қай модель қай пішінді қабылдайтыны өз бетінде көрсетілген. Құрылымдалған нәтижелер

Пайымдау

Пайымдайтын модель өз пайымдауын хабарламадан бұрын reasoning түріндегі шығыс элементі ретінде қайтарады. Стримде ол response.reasoning_summary_text.delta оқиғалары ретінде келеді.

Hosted open-weight модельдер reasoning.effort мәнін қолданады: off, low, medium немесе high, ештеңе жібермесеңіз high. off пайымдау элементін қайтармайды. Оны нысан ретінде жіберіңіз; бұл endpoint-те жай жол оқылмайды.

Effort деңгейлері өз бетінде сипатталған. Пайымдау күші

Шығыс лимиті

max_output_tokens жібермесеңіз 4,096 болады. Бұл сұрау басталғанда балансыңыздан бөлек қойылатын токен саны; жауап толық болғанда ол көлем сұрау жұмсағанмен ауыстырылады. Қалған балансыңызға сыймайтын мән 429 Quota exceeded қайтарады.

Ол shannon-1.6-*, shannon-2-* және shannon-coder-1 модельдерінде жауап ұзындығын, ал hosted open-weight модельдерде жауап мәтінінің ұзындығын шектейді.

Бұл endpoint-те shannon-coder-1 үшін басқа модельдер сияқты балансыңыздан токенмен төленеді.

Сұрау денесі 32 MiB-қа дейін болуы мүмкін. Шектеулер және баланс

Қателер

Қателер OpenAI қате денесін қолданады: type және message бар error нысаны; кейбіреулері null мәні бар code және param де алып жүреді. Кестеде осы endpoint ең жиі қайтаратындар берілген. Толық тізімнің, нені қайталау керегімен бірге, өз беті бар. Қателерді өңдеу