推理强度
新会推理的模型会在答案旁边的单独字段中返回其推理文本。在托管开源权重模型上，一个请求字段即可设置模型在回答之前推理的深度。
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 中携带推理 tokens：
200 JSON
{
"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}
}
}哪些模型会推理
| 模型 | 返回推理文本 | 应用 effort 字段 |
|---|---|---|
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 | 是 | — |
| 所有托管开源权重模型 | 是 | 是 |
这些是 GET /v1/models 为每个 id 报告的标志 capabilities.reasoning 和 capabilities.reasoning_effort。只有模型产生了推理文本，回复才会带有推理文本。 模型与定价
设置 effort
每个端点对 effort 有各自的写法。它们都对应同样的四个级别之一。
| 字段 | 类型 | 默认值 | 说明 | 适用模型 |
|---|---|---|---|---|
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 | 不推理。回复中没有推理文本。 |
low | 简短推理。 | |
medium | default | 中等深度。 |
high | max | 最深的级别。不发送任何值的请求即为此级别。 |
- 取值不区分大小写。
- 值
default表示medium。省略该字段表示high。 - Shannon 模型（
shannon-*）在每个请求中自行决定深度；GET /v1/models对它们报告reasoning_effort: false。
/v1/messages 上的思考预算
在 /v1/messages 上，由 thinking 字段选择级别。budget_tokens 用于选择上面的某个级别；它本身不是 token 上限。adaptive 的处理方式与 enabled 相同。
| 你发送 | 级别 |
|---|---|
{"type": "disabled"} | off |
{"type": "enabled", "budget_tokens": n}，其中 n 不超过 2,048 | low |
n 从 2,049 到 8,192 | medium |
更大的 n，或没有 budget_tokens 的 enabled | high |
没有 thinking 字段 | high |
推理文本到达的位置
推理文本始终与答案分开。每种格式各有其存放位置：
| 端点 | 非流式 | 流式 |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content：一个字符串，模型没有产生推理时为 null。 | 带有 choices[0].delta.reasoning_content 的数据块，位于带有 delta.content 的数据块之前。 |
/v1/responses | 位于 message 项之前的一个 output 项 {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]}。没有推理时不会有该项。 | 带有 reasoning 项的 response.output_item.added，然后是若干 response.reasoning_summary_text.delta 事件和一个 response.reasoning_summary_text.done。 |
/v1/messages | 第一个内容块 {"type": "thinking", "thinking": "…"}，然后是 text 块。没有推理时不会有 thinking 块。 | 一个 thinking 内容块：content_block_start、带有 thinking_delta 的 content_block_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
}
}每个模型应该看哪里：
| 模型 | 文本到达的位置 |
|---|---|
| 托管开源权重模型 | 在所有端点上，无论是否流式。effort 为 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 上，非流式回复对 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 answerimport 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?"}
]
}'托管开源权重模型的第一个数据块，无论是推理还是答案，也会带有 delta.role: "assistant"。 流式
推理 tokens 与计费
在托管开源权重模型上，推理 tokens 属于输出 tokens：按该模型的输出价格计费，输出计数已包含它们。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 | 推理和答案合计。这种格式没有单独的计数。 |
- 在托管开源权重模型上，
max_tokens限制的是答案文本。推理 tokens 不计入其中。 - 由于推理按输出计费，effort 级别同时也是一个成本设置：
off不产生推理 tokens。 - Shannon 模型报告
prompt_tokens、completion_tokens和total_tokens（/v1/messages上为input_tokens和output_tokens），不单列推理部分，并按每个 token 一个统一价格计费。 模型与定价
下一个请求中的推理
你不必把推理发回去。你发送的对话中的 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 不是字符串。 |
认证、余额和服务器错误与所有请求相同。 错误处理