Усилие рассуждения
НовоеМодель, которая рассуждает, возвращает текст reasoning рядом с ответом, в отдельном поле. У размещенных моделей с открытыми весами одно поле запроса задает, насколько глубоко модель рассуждает перед ответом.
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 находится в reasoning_content, ответ — в content, а токены reasoning — в 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}
}
} Какие модели рассуждают
| Модель | Возвращает текст reasoning | Применяет поле усилия |
|---|---|---|
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 | Да | — |
| Каждая размещенная модель с открытыми весами | Да | Да |
Это флаги capabilities.reasoning и capabilities.reasoning_effort, которые GET /v1/models сообщает для каждого id. Ответ содержит текст reasoning, только если модель его создала. Модели и цены
Настройка усилия
У каждого эндпоинта своя запись усилия. Все они выбирают один из одних и тех же четырех уровней.
| Поле | Тип | По умолчанию | Описание | Применяется на |
|---|---|---|---|---|
reasoning_effort | string | high | /v1/chat/completions. Насколько глубоко модель рассуждает перед ответом: off, low, medium или high. | Размещенные модели с открытыми весами |
reasoning | object | string | /v1/chat/completions. То же значение в виде {"effort": "low"} или простой строки. Если отправлены оба поля, действует reasoning_effort. | Размещенные модели с открытыми весами | |
reasoning.effort | string | high | /v1/responses. Записывается как объект {"effort": "low"}. | Размещенные модели с открытыми весами |
thinking | object | /v1/messages. {"type": "enabled", "budget_tokens": n} или {"type": "disabled"}. Бюджет выбирает один из уровней; см. таблицу ниже. | Размещенные модели с открытыми весами |
{
"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 | Без рассуждений. В ответе нет текста reasoning. |
low | Краткое рассуждение. | |
medium | default | Средняя глубина. |
high | max | Самый глубокий уровень. Его получает запрос, в котором значение не указано. |
- Значения читаются без учета регистра.
- Значение
defaultозначаетmedium. Если поле не указано, подразумеваетсяhigh. - Модели Shannon (
shannon-*) сами задают глубину в каждом запросе;GET /v1/modelsсообщает для нихreasoning_effort: false.
Бюджет thinking на /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 |
Где приходит текст reasoning
Текст reasoning всегда отделен от ответа. В каждом формате для него свое место:
| Эндпоинт | Без стриминга | Со стримингом |
|---|---|---|
/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. Если reasoning нет, элемента тоже нет. | response.output_item.added с элементом reasoning, затем события response.reasoning_summary_text.delta и одно response.reasoning_summary_text.done. |
/v1/messages | Первый блок контента {"type": "thinking", "thinking": "…"}, затем блок text. Если reasoning нет, блока 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
}
} Где искать, по моделям:
| Модели | Где приходит текст |
|---|---|
| Размещенные модели с открытыми весами | На каждом эндпоинте, со стримингом и без. Запрос с усилием off или с response_format / text.format получает ответ без текста reasoning. |
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | На каждом эндпоинте, со стримингом и без, если модель создала текст reasoning. |
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, если модель создала текст reasoning. |
На /v1/responses ответ без стриминга содержит элемент reasoning для семейства Shannon 3 и размещенных моделей с открытыми весами.
Чтение потока
В потоке сначала идет текст reasoning, в собственных дельтах, а затем ответ. Выводите или сохраняйте их по отдельности:
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?"}
]
}' Первый чанк размещенной модели с открытыми весами, будь то reasoning или ответ, также содержит delta.role: "assistant". Потоковая передача
Токены reasoning и биллинг
У размещенных моделей с открытыми весами токены reasoning — это выходные токены: они оплачиваются по цене вывода модели, и счетчик вывода уже включает их. usage показывает долю reasoning здесь:
| Эндпоинт | Поле | Примечание |
|---|---|---|
/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 | Reasoning и ответ вместе. В этом формате отдельного счетчика нет. |
- У размещенных моделей с открытыми весами
max_tokensограничивает текст ответа. Токены reasoning в него не засчитываются. - Поскольку reasoning тарифицируется как вывод, уровень усилия — это еще и настройка стоимости: при
offтокены reasoning не создаются. - Модели Shannon сообщают
prompt_tokens,completion_tokensиtotal_tokens(input_tokensиoutput_tokensна/v1/messages) без доли reasoning и тарифицируют по единой цене за токен. Модели и цены
Reasoning в следующем запросе
Отправлять reasoning обратно не нужно. Блок thinking или элемент reasoning в отправляемом разговоре не передается модели, поэтому ход ассистента можно отправить как с ним, так и без него. У блока thinking два поля, type и thinking; поля signature нет.
Ошибки
| Статус | Тип | Сообщение | Когда |
|---|---|---|---|
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Размещенная модель с открытыми весами получила значение вне списка, например xhigh. С баланса ничего не списывается. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | reasoning_effort не является строкой. |
Ошибки аутентификации, баланса и сервера такие же, как для любого запроса. Обработка ошибок