Зусилля міркування
НовеМодель, що міркує, повертає текст міркувань поряд із відповіддю в окремому полі. На хостованих open-weight моделях одне поле запиту задає, наскільки глибоко модель міркує перед відповіддю.
POST https://api.shannon-ai.com/v1/chat/completions
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")
response = client.chat.completions.create(
model="Kimi-K3-3BIT-REAP",
reasoning_effort="low",
messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)
message = response.choices[0].message
print("Reasoning:", getattr(message, "reasoning_content", None))
print("Answer:", message.content)
print("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "low",
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
const message = response.choices[0].message;
console.log("Reasoning:", message.reasoning_content);
console.log("Answer:", message.content);
console.log("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "low",
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' Відповідь містить текст міркувань у reasoning_content, відповідь у content, а токени міркувань у usage:
{
"id": "chatcmpl-2a6c8e0b4d1f4a3c9e7b5d3f1a8c6e4b",
"object": "chat.completion",
"created": 1791590400,
"model": "Kimi-K3-3BIT-REAP",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "No. 221 = 13 x 17, so it is not prime.",
"reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 43,
"total_tokens": 57,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 27}
}
} Які моделі міркують
| Модель | Повертає текст міркувань | Застосовує поле зусилля |
|---|---|---|
shannon-1.6-lite | — | — |
shannon-1.6-pro, shannon-2-lite, shannon-2-pro, shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro, shannon-coder-1 | Так | — |
| Кожна хостована open-weight модель | Так | Так |
Це прапорці capabilities.reasoning і capabilities.reasoning_effort, які GET /v1/models повідомляє для кожного id. Відповідь містить текст міркувань, лише якщо модель його створила. Моделі та ціни
Задання зусилля
Кожен ендпоінт має своє написання зусилля. Усі вони вибирають один із тих самих чотирьох рівнів.
| Поле | Тип | За замовчуванням | Опис | Застосовують |
|---|---|---|---|---|
reasoning_effort | string | high | /v1/chat/completions. Наскільки глибоко модель міркує перед відповіддю: off, low, medium або high. | Хостовані open-weight моделі |
reasoning | object | string | /v1/chat/completions. Те саме значення, що й {"effort": "low"}, або просто рядок. Якщо надіслано обидва поля, діє reasoning_effort. | Хостовані open-weight моделі | |
reasoning.effort | string | high | /v1/responses. Записується як об'єкт {"effort": "low"}. | Хостовані open-weight моделі |
thinking | object | /v1/messages. {"type": "enabled", "budget_tokens": n} або {"type": "disabled"}. Бюджет вибирає один з рівнів; див. таблицю нижче. | Хостовані open-weight моделі |
{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "low",
"messages": [{"role": "user", "content": "Is 221 a prime number?"}]
} {
"model": "Kimi-K3-3BIT-REAP",
"reasoning": {"effort": "low"},
"input": "Is 221 a prime number?"
} {
"model": "Kimi-K3-3BIT-REAP",
"max_tokens": 1024,
"thinking": {"type": "enabled", "budget_tokens": 2048},
"messages": [{"role": "user", "content": "Is 221 a prime number?"}]
} | Значення | Також приймається | Ефект |
|---|---|---|
off | none, minimal | Без міркувань. Відповідь не містить тексту міркувань. |
low | Стислі міркування. | |
medium | default | Середня глибина. |
high | max | Найглибший рівень. Це рівень запиту, що не надсилає значення. |
- Значення читаються без урахування регістру.
- Значення
defaultозначаєmedium. Якщо поле пропущено, це означаєhigh. - Моделі Shannon (
shannon-*) самі задають глибину в кожному запиті;GET /v1/modelsповідомляє для нихreasoning_effort: false.
Бюджет мислення на /v1/messages
На /v1/messages поле thinking вибирає рівень. budget_tokens вибирає один з рівнів вище; це не окремий ліміт токенів. adaptive читається як enabled.
| Ви надсилаєте | Рівень |
|---|---|
{"type": "disabled"} | off |
{"type": "enabled", "budget_tokens": n} з n до 2,048 | low |
n від 2,049 до 8,192 | medium |
Більше n або enabled без budget_tokens | high |
Без поля thinking | high |
Де надходить текст міркувань
Текст міркувань завжди окремо від відповіді. Кожен формат має для нього своє місце:
| Ендпоінт | Без стрімінгу | Зі стрімінгом |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content: рядок або null, якщо модель нічого не створила. | Чанки з choices[0].delta.reasoning_content перед чанками з delta.content. |
/v1/responses | Елемент output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} перед елементом message. Без міркувань елемента немає. | response.output_item.added з елементом reasoning, потім події response.reasoning_summary_text.delta і одна response.reasoning_summary_text.done. |
/v1/messages | Перший блок контенту {"type": "thinking", "thinking": "…"}, потім блок text. Без міркувань блока thinking немає. | Блок контенту thinking: content_block_start, події content_block_delta з thinking_delta, content_block_stop. Далі йде блок тексту. |
{
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "No. 221 = 13 x 17, so it is not prime.",
"reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 43,
"total_tokens": 57,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 27}
}
} {
"output": [
{
"id": "rs_6f0a2c4e8b1d4f3a9c7e5b3d1f8a6c4e",
"type": "reasoning",
"summary": [
{
"type": "summary_text",
"text": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
}
]
},
{
"id": "msg_1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f1a",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "No. 221 = 13 x 17, so it is not prime.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 14,
"input_tokens_details": {"cached_tokens": 0},
"output_tokens": 43,
"output_tokens_details": {"reasoning_tokens": 27},
"total_tokens": 57
}
} {
"content": [
{
"type": "thinking",
"thinking": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
},
{"type": "text", "text": "No. 221 = 13 x 17, so it is not prime."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 14,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 43
}
} Де шукати, за моделями:
| Моделі | Де надходить текст |
|---|---|
| Хостовані open-weight моделі | На кожному ендпоінті, зі стрімінгом чи без. Запит із зусиллям off або з response_format / text.format отримує відповідь без тексту міркувань. |
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | На кожному ендпоінті, зі стрімінгом чи без, щоразу коли модель створила текст міркувань. |
shannon-2-lite, shannon-2-pro | /v1/chat/completions без стрімінгу: у message.reasoning_content. Зі стрімінгом у запиті без tools або response_format: стрім несе рядки-коментарі : thinking, поки модель міркує, потім чанки відповіді. /v1/messages зі стрімінгом: блок thinking перед блоком тексту. |
shannon-1.6-pro, shannon-coder-1 | У відповідях зі стрімінгом і у відповідях на запити з tools, щоразу коли модель створила текст міркувань. |
На /v1/responses відповідь без стрімінгу містить елемент reasoning для сімейства Shannon 3 і хостованих open-weight моделей.
Читання стріму
У стрімі спершу йде текст міркувань в окремих дельтах, потім відповідь. Виводьте або зберігайте їх окремо:
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")
stream = client.chat.completions.create(
model="Kimi-K3-3BIT-REAP",
reasoning_effort="medium",
stream=True,
messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
print(reasoning, end="", flush=True) # the reasoning text comes first
if delta.content:
print(delta.content, end="", flush=True) # then the answer import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const stream = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "medium",
stream: true,
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta ?? {};
if (delta.reasoning_content) process.stdout.write(delta.reasoning_content); // the reasoning text comes first
if (delta.content) process.stdout.write(delta.content); // then the answer
} curl -N https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "medium",
"stream": true,
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' Перший чанк хостованої open-weight моделі, міркування чи відповідь, також містить delta.role: "assistant". Стримінг
Токени міркувань і тарифікація
На хостованих open-weight моделях токени міркувань — це вихідні токени: вони тарифікуються за ціною виходу моделі, і кількість виходу їх уже включає. Частку міркувань тут показує usage:
| Ендпоінт | Поле | Примітка |
|---|---|---|
/v1/chat/completions | usage.completion_tokens_details.reasoning_tokens | Уже входить до completion_tokens. |
/v1/responses | usage.output_tokens_details.reasoning_tokens | Уже входить до output_tokens. |
/v1/messages | usage.output_tokens | Міркування та відповідь разом. Цей формат не має окремого підрахунку. |
- На хостованих open-weight моделях
max_tokensобмежує текст відповіді. Токени міркувань до нього не зараховуються. - Оскільки міркування тарифікуються як вихід, рівень зусилля є також налаштуванням вартості:
offне створює токенів міркувань. - Моделі Shannon повідомляють
prompt_tokens,completion_tokensіtotal_tokens(input_tokensтаoutput_tokensна/v1/messages) без частки міркувань і тарифікують одну плоску ціну за токен. Моделі та ціни
Міркування в наступному запиті
Міркування не обов'язково надсилати назад. Блок thinking або елемент reasoning у розмові, яку ви надсилаєте, не передається моделі, тож хід асистента можна повертати з ним або без нього. Блок thinking має два поля, type і thinking; поля signature у нього немає.
Помилки
| Статус | Тип | Повідомлення | Коли |
|---|---|---|---|
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Хостована open-weight модель отримала значення поза списком, наприклад xhigh. З вашого балансу нічого не списується. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | reasoning_effort не є рядком. |
Помилки автентифікації, балансу та сервера такі самі, як для кожного запиту. Обробка помилок