Responses API

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

Хурдтарин дархост аз id-и модел ва матн иборат аст. Ҷавоб бо streaming намеояд, магар ин ки онро талаб кунед.

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 он чизест, ки дархост ба он ниёз дорад. Сутуни Татбиқ мекунад моделҳоеро номбар мекунад, ки дар онҳо майдон ҷавобро тағйир медиҳад. Моделҳои 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 гузоред. Бо id-и оилаи Shannon 3 дастурҳоеро, ки бояд риоя шаванд, ба паёми user гузоред.

Ҷузъҳои output-и ҷавобро бетағйир ба input баргардонидан мумкин аст: ҷузъҳои message ва function_call хонда мешаванд, ҷузъҳои reasoning гузаронида мешаванд.

Қисмҳои мундариҷа

Дар сатҳҳои Shannon тасвирҳо ва файлҳо аз ҷузъи охирини user-и input хонда мешаванд. Андозаҳо ва маҳдудиятҳо саҳифаи худро доранд. Тасвирҳо ва файлҳо

Дархост бо дастурҳо ва имконот

Ин дархост дастурҳо, гуфтугӯро ҳамчун ҷузъҳои вуруд, ҳади баромад, ҳарорат ва сатҳи кӯшиши reasoning мефиристад. Он модели 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-и он токенҳои аз кэш хондашуда ва токенҳои барои 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 дар ҳар ҷавоб мавҷуданд. Рамзи худро ба онҳо асос диҳед.

Ҷузъҳои баромад

SDK-ҳои OpenAI матни паёмро барои шумо дар response.output_text якҷоя мекунанд.

Streaming

stream-ро ба true гузоред, то server-sent events гиред. Ҳар фрейм хати 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
  }'

Рӯйдодҳо бо ин тартиб меоянд. Гурӯҳҳои 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 дорад.

Дар моделҳои open-weight-и хостшуда нокомӣ рӯйдоди error бо code-и api_error ва message аст. Пас аз он ҳам 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 ва функсияи номбаршударо моделҳои open-weight-и хостшуда татбиқ мекунанд.

Ҳалқаи абзорҳо дар саҳифаи худаш ба таври пурра тавсиф шудааст. Даъвати функсия

Баромади сохторӣ

Ин формат баромади сохториро ҳамчун text.format менависад. Схема бевосита дар format, дар паҳлӯи name ва strict меистад, на дар зери узви json_schema мисли Chat Completions.

• {"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-и паём меояд; онро худатон парс кунед. Модели open-weight-и хостшуда бе баромади сохторӣ 400 бармегардонад.

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

Кадом модел кадом шаклро мепазирад, дар саҳифаи худаш номбар шудааст. Баромадҳои сохторӣ

Reasoning

Модели reasoning-кунанда reasoning-и худро ҳамчун ҷузъи баромади навъи reasoning, пеш аз паём бармегардонад. Дар ҷараён он ҳамчун рӯйдодҳои response.reasoning_summary_text.delta меояд.

Моделҳои open-weight-и хостшуда 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 ва дарозии матни ҷавобро дар моделҳои open-weight-и хостшуда маҳдуд мекунад.

Дар ин endpoint shannon-coder-1 бо токен аз балансатон ҳисоб карда мешавад, мисли ҳар модели дигар.

Бадани дархост то 32 MiB шуда метавонад. Маҳдудиятҳо ва баланс

Хатогиҳо

Хатогиҳо бадани хатогии OpenAI-ро истифода мебаранд: объекти error бо type ва message; баъзеҳо ҳамчунин code ва param-ро бо қимати null доранд. Ҷадвал он чиро нишон медиҳад, ки ин endpoint аксар вақт бармегардонад. Рӯйхати пурра, бо нишони он ки чӣ бояд такрор шавад, саҳифаи худро дорад. Идораи хатогиҳо