zend-token/docs/kimi.md

# Kimi API（月之暗面 Moonshot）

> 来源（官方文档站 `.md` 原文，采集于 2026-08-13）：
> - API 参考：[overview](https://platform.kimi.com/docs/api/overview.md)、[chat](https://platform.kimi.com/docs/api/chat.md)、[models-overview](https://platform.kimi.com/docs/api/models-overview.md)、[list-models](https://platform.kimi.com/docs/api/list-models.md)、[errors](https://platform.kimi.com/docs/api/errors.md)、[estimate](https://platform.kimi.com/docs/api/estimate.md)、[balance](https://platform.kimi.com/docs/api/balance.md)、[batch-create](https://platform.kimi.com/docs/api/batch-create.md)
> - 指南：[models](https://platform.kimi.com/docs/models.md)、[k3-quickstart](https://platform.kimi.com/docs/guide/kimi-k3-quickstart.md)、[k2.7-code-quickstart](https://platform.kimi.com/docs/guide/kimi-k2-7-code-quickstart.md)、[thinking](https://platform.kimi.com/docs/guide/use-thinking-models.md)、[reasoning-effort](https://platform.kimi.com/docs/guide/use-reasoning-effort.md)、[partial](https://platform.kimi.com/docs/guide/use-partial-mode-feature-of-kimi-api.md)、[caching](https://platform.kimi.com/docs/guide/use-context-caching-feature-of-kimi-api.md)、[tool-choice](https://platform.kimi.com/docs/guide/use-tool-choice.md)、[dynamic-tools](https://platform.kimi.com/docs/guide/use-dynamic-tool-loading.md)、[tool-calls](https://platform.kimi.com/docs/guide/use-kimi-api-to-complete-tool-calls.md)、[web-search](https://platform.kimi.com/docs/guide/use-web-search.md)、[official-tools](https://platform.kimi.com/docs/guide/use-official-tools.md)、[response_format](https://platform.kimi.com/docs/guide/response_format.md)、[streaming](https://platform.kimi.com/docs/guide/utilize-the-streaming-output-feature-of-kimi-api.md)、[vision](https://platform.kimi.com/docs/guide/use-kimi-vision-model.md)、[file-qa](https://platform.kimi.com/docs/guide/use-kimi-api-for-file-based-qa.md)、[batch](https://platform.kimi.com/docs/guide/use-batch-api.md)、[claude-code](https://platform.kimi.com/docs/guide/claude-code-kimi.md)、[troubleshooting](https://platform.kimi.com/docs/guide/troubleshooting.md)
> - 计价与限流：[limits](https://platform.kimi.com/docs/pricing/limits.md)、[chat-k3](https://platform.kimi.com/docs/pricing/chat-k3.md)
> - 完整索引：https://platform.kimi.com/docs/llms.txt ；OpenAPI：https://platform.kimi.com/docs/openapi.json
>
> **2026-08-13 用真实 API key 实测校验过一遍**（约 60 次请求，覆盖两个入口）。实测与文档冲突处均以实测为准。
> 实测环境：中国站 `api.moonshot.cn`，账号档位 `msh-gid: free`（Tier 0，3 RPM / 1 并发），流式 `system_fingerprint` = `fpv0_489ccb45`。
>
> **标注约定**：✅ 文档记载且实测确认；❌ **实测推翻文档**；🆕 文档未记载、实测发现；⚠️ 未实测或存疑。

Kimi 对外声称 **OpenAI 协议兼容**，OpenAI SDK 换 `base_url` 即可用。但实测下来它是本项目已调研的几家里**"最容易在第一个请求就 400"** 的一家：

1. **新模型把采样参数写死并硬 400**——`temperature` 不是 1.0 直接报错，实测确认不是静默忽略（§3）。带默认 `temperature=0.7` 的 OpenAI 客户端在 K3 上开箱即挂。
2. **同一模型在两个入口行为相反**——OpenAI 入口对 `temperature=0.7` 报 400，Anthropic 入口 200 静默忽略（§3.2）。
3. **参数集按模型分裂成四套**——合法请求体取决于 `model` 值（§3、§4）。
4. **文档与实现大面积脱节**——实测推翻了 8 条文档明确写下的规则，其中包括"K3 思考恒开不可关"这样的核心设定（§14）。**照文档写代码会同时踩到"文档说能实际不能"和"文档说不能实际能"两个方向。**
5. **它其实是两个产品**——`platform`（本文 §1–§16）和 **Kimi For Coding**（`api.kimi.com/coding`，见 **§17**）是**两套独立的服务栈**：账号体系、模型名、鉴权、限流、端点、id 格式全都不同，key 互不通用。**中转站必须当作两个上游分别配置。**

---

## 1. 端点、域名与鉴权

### 1.1 双站隔离 ✅

| 产品 / 站点 | 控制台 | API base URL | Key 前缀 |
| --- | --- | --- | --- |
| platform 中国站 | `platform.kimi.com` | `https://api.moonshot.cn/v1` | `sk-` |
| platform 国际站 | `platform.kimi.ai` | `https://api.moonshot.ai/v1` | `sk-` |
| **Kimi For Coding**（另一个产品，见 §17） | — | `https://api.kimi.com/coding/v1` | **`sk-kimi-`** |

两站账号、余额、API Key 完全独立，拿错区域的 key 返回 401。中转站的上游配置必须把 key 和 base URL 绑成一对。

✅ **Kimi For Coding 与 platform 的 key 双向不通用**（实测）——且两边的 401 文案不同，可用来判断打错了哪个上游：

```
coding key   → api.moonshot.cn : {"message":"Invalid Authentication","type":"invalid_authentication_error"}
platform key → api.kimi.com/coding : {"message":"The API Key appears to be invalid or may have expired. Please verify your credentials and try again.","type":"invalid_authentication_error"}
```

⚠️ **域名分层容易记错**：文档站/控制台已迁到 `kimi.com`（`platform.moonshot.cn` → `platform.kimi.com` 301），但 **API 数据面仍是 `api.moonshot.cn` / `api.moonshot.ai`**，没有迁到 `api.kimi.com`。

### 1.2 端点清单 ✅（均实测可用）

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v1/chat/completions` | 对话补全 |
| GET | `/v1/models` | 模型列表 |
| POST | `/v1/tokenizers/estimate-token-count` | 官方 token 计数 |
| GET | `/v1/users/me/balance` | 余额查询 |
| POST/GET/DELETE | `/v1/files`、`/v1/files/{id}`、`/v1/files/{id}/content` | 文件管理 |
| POST/GET | `/v1/batches`、`/v1/batches/{id}`、`/v1/batches/{id}/cancel` | 批处理 |

鉴权统一 `Authorization: Bearer <api_key>` ✅。**没有智谱那种 JWT 历史包袱**，这点比多数国产厂商干净。

🆕 **非 chat 端点带业务包装层**：`/v1/users/me/balance` 和 `/v1/tokenizers/estimate-token-count` 返回的**不是**裸对象，而是

```json
{"code":0,"data":{"total_tokens":87},"scode":"0x0","status":true}
```

即 HTTP 200 外面还套了一层 `code`/`scode`/`status`。而 `/v1/chat/completions` 和 `/v1/models` **没有**这层包装（直接 OpenAI 结构）。**同一个 API 里两种响应信封并存**——中转站的响应解析器不能一刀切。（对比 `china-providers.md` §0 里 MiniMax `base_resp` 那种"HTTP 200 藏业务错误"，Kimi 是同一思路的半吊子版本：只在辅助端点上有。）

🆕 **未记载的调试响应头**（每个响应都带）：

```
msh-request-id: 7b768543-96db-11f1-8fa0-624fe5b4e31b
msh-org-id:     org-xxxxxxxx
msh-project-id: proj-xxxxxxxx
msh-uid:        xxxxxxxxxxxxxxxxxxxx
msh-gid:        free            ← 账号档位，可用来自动探测 Tier
msh-trace-mode: on
```

`msh-request-id` 是报障时官方要的 request_id。⚠️ 但 `msh-org-id` / `msh-uid` / `msh-project-id` 是**账号标识**——中转站若原样透传响应头给下游，等于把自己的组织 ID 广播出去。**应当在响应头白名单里剥掉 `msh-*`**（`msh-request-id` 可保留或改名）。

### 1.3 Anthropic 兼容入口 ✅（实测可用，但与 OpenAI 入口行为不一致）

```
ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
ANTHROPIC_AUTH_TOKEN="<kimi api key>"     # 注意是 AUTH_TOKEN 不是 API_KEY
```

实测结论：

| 项 | 结果 |
| --- | --- |
| `POST /anthropic/v1/messages` + `x-api-key` | ✅ 200 |
| `POST /anthropic/v1/messages` + `Authorization: Bearer` | ✅ 200，**两种鉴权都接受** |
| `POST /anthropic/messages`（漏 `v1`） | ❌ 404，且**掉到网关层**（见下） |
| 不带 `anthropic-version` 头 | 🆕 200，**不强制** |
| `temperature: 0.7` | 🆕 **200 静默忽略**（OpenAI 入口同样请求是 400） |
| `top_p: 0.5` | 🆕 200 静默忽略 |
| `tool_choice: {"type":"tool","name":...}` | ✅ 400 `tool_choice 'specified' is incompatible with thinking enabled`（与 OpenAI 入口一致） |
| `thinking: {"type":"enabled","budget_tokens":2000}` | ✅ 200 接受 |
| `system` + `cache_control: {"type":"ephemeral"}` | 🆕 200 接受但 `cache_creation_input_tokens: 0`，**未实际建缓存**（自动缓存机制接管，见 §10） |
| `model: "kimi-k3[1m]"` | ❌ **404**（见下） |

> **两个入口对采样参数的处理相反，但对 `tool_choice` 的限制一致**——不是"Anthropic 入口更宽松"，而是**选择性地不一致**。中转站不能假设"打不通就换个入口试试"。

🆕 **Anthropic 入口的 `usage` 同时并存两套字段**：

```json
"usage": {
  "input_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 88,
  "output_tokens": 151, "output_tokens_details": {"thinking_tokens": 135},
  "service_tier": "standard", "inference_geo": "not_available",
  "prompt_tokens": 88, "cached_tokens": 88, "completion_tokens": 151, "total_tokens": 239
}
```

Anthropic 风格（`input_tokens`/`cache_read_input_tokens`/`output_tokens`）和 OpenAI 风格（`prompt_tokens`/`cached_tokens`/`completion_tokens`）**同时存在**，且语义不同：缓存命中时 `input_tokens` 变成 **0**（Anthropic 语义：不含缓存部分），而 `prompt_tokens` 仍是 **88**（OpenAI 语义：含缓存部分）。**中转站按哪套字段计费，账单会差一个缓存量。**

🆕 **thinking block 没有 `signature` 字段**——Anthropic 官方的 thinking block 带加密签名，Kimi 这个是纯明文 `{"type":"thinking","thinking":"..."}`。好处是不用当 opaque blob 搬运，坏处是**下游若按 Anthropic 规范校验 signature 会失败**。

❌ **`kimi-k3[1m]` 是错的**——官方 Claude Code 配置页把 `ANTHROPIC_MODEL` 等六个变量全设成 `kimi-k3[1m]`，但实测**两个入口都 404**：

```
OpenAI 入口:    {"error":{"message":"Not found the model kimi-k3[1m] or Permission denied","type":"resource_not_found_error"}}
Anthropic 入口: {"error":{"type":"resource_not_found_error","message":"Not found the model kimi-k3[1m] or Permission denied"},"request_id":"...","type":"error"}
```

`[1m]` 是 Claude Code 客户端侧的上下文变体后缀，Kimi 服务端并不认。**正确的模型名是 `kimi-k3`。** 官方文档这段配置照抄会直接失败。

🆕 **三种错误格式并存**（这是中转站错误处理的隐藏坑）：

```jsonc
// 1. OpenAI 入口 API 级错误
{"error":{"message":"...","type":"invalid_request_error"}}
// 2. Anthropic 入口 API 级错误 —— 多了 request_id 和顶层 type
{"error":{"type":"resource_not_found_error","message":"..."},"request_id":"...","type":"error"}
// 3. 网关级错误（路径不存在时）—— 完全不同的结构，中文消息，且回显 UA 和 URL
{"code":5,"error":"url.not_found","message":"没找到对象","method":"POST","scode":"0x5","status":false,"ua":"curl/8.7.1","url":"/anthropic/messages"}
```

第三种连 `error` 字段的类型都变了（从 object 变成 string）。**中转站解析上游错误时若假设 `error` 恒为 object，遇到网关级错误会抛类型异常。**

✅ 已知能力缺口：该端点**不支持 WebFetch**（Claude Code 里报 `temporarily unavailable`）。

---

## 2. 模型与能力矩阵

### 2.1 在售模型 ✅

| 模型 | 上下文（实测 `/v1/models`） | 默认 max output | 思考 | 视觉 | 视频 |
| --- | --- | --- | --- | --- | --- |
| `kimi-k3` | 1,048,576 | 131,072（上限 1,048,576） | 恒开但**可关**（§4.1） | ✓ | ✓ |
| `kimi-k2.7-code` | 262,144 | 32,768 | **不可关** | ✓ | ✓ |
| `kimi-k2.7-code-highspeed` | 262,144 | 32,768 | **不可关** | ✓ | ✓ |
| `kimi-k2.6` | 262,144 | ⚠️ 未记载 | 可关 | ✓ | ✓ |
| `kimi-k2.5` | 262,144 | ⚠️ 未记载 | 可关 | ✓ | ✓ |
| `moonshot-v1-{8k,32k,128k}` | 8192/32768/131072 | ⚠️ 未记载 | 无 | ✗ | ✗ |
| `moonshot-v1-{8k,32k,128k}-vision-preview` | 同上 | ⚠️ 未记载 | 无 | ✓ | ✗ |
| 🆕 `moonshot-v1-auto` | 131072 | — | 无 | ✗ | ✗ |

🆕 **`moonshot-v1-auto` 文档完全没提**，但 `/v1/models` 里有且可调用。它是**自动路由模型**：请求 `moonshot-v1-auto`，**响应的 `model` 字段返回 `moonshot-v1-8k`**（实测两次都是）。

> 这是 DeepSeek `deepseek-chat` → `deepseek-v4-flash` 静默映射的同类问题：**请求模型名 ≠ 响应模型名 ≠ 账单模型名**。中转站若按响应 `model` 字段记账，用户请求 auto 会看到一个自己没点过的模型名；若按请求名记账，又对不上实际计费。**建议两个都记。**

`kimi-k2.7-code-highspeed` 是同模型高速档（约 180 tok/s），能力相同——可当作同一逻辑模型的 QoS 变体。

⚠️ 文档提到 moonshot-v1 系列"8 月 31 日下线"但未给年份，而 `/v1/models` 仍在返回。需持续关注。

### 2.2 已下线模型：无别名兜底 ✅（实测确认）

```
kimi-k2      → 404 Not found the model kimi-k2 or Permission denied
kimi-latest  → 404 Not found the model kimi-latest or Permission denied
```

与 DeepSeek 把旧名静默映射到新模型**相反**，Kimi 是直接 404。中转站若面向存量客户需自建旧名映射表，并显式告知用户（别学 DeepSeek 静默换模型导致账单对不上）。

### 2.3 `/v1/models` 的真实返回：比文档丰富得多 🆕

文档给的示例只有 7 个字段，实测返回：

```json
{
  "id": "kimi-k3", "object": "model", "created": 1786362236, "owned_by": "moonshot",
  "permission": [{"created":0,"id":"","object":"","organization":"moonshot","group":"moonshot","is_blocking":false}],
  "root": "", "parent": "",
  "supports_image_in": true, "supports_video_in": true, "supports_reasoning": true,
  "supports_dynamic_tools": true,
  "think_efforts":     {"support": true, "valid_efforts": ["low","high","max"], "default_effort": "max"},
  "reasoning_efforts": {"support": true, "valid_efforts": ["low","high","max"], "default_effort": "max"},
  "supports_thinking_type": "only",
  "context_length": 1048576
}
```

- `permission[]` / `root` / `parent` 是 **OpenAI 早期 `/models` 的遗留字段**（现已从 OpenAI 移除），Kimi 还留着，且内容全是空壳。
- 🆕 `think_efforts` 和 `reasoning_efforts` **内容完全相同的两个字段**——显然是改名过程中的兼容遗留，两个都在返回。
- 🆕 `supports_dynamic_tools`（仅 K3 为 true）、`supports_thinking_type: "only"`（仅 K3 有此字段）——**这两个字段是判断能力的最可靠来源**，比文档准。
- ❌ 文档示例里 `kimi-k2.5` 的 `context_length` 写的是 `128000`，实测是 **262144**。

> 这是少见的"上游自带能力矩阵"，中转站可以自动同步能力表而非硬编码。但注意 `supports_thinking_type: "only"` 的值是字符串 `"only"` 而非布尔，且**只有 K3 有这个字段**——解析时要容忍字段缺失。

---

## 3. 采样参数：新模型写死且**硬 400**（实测确认，本文件最大的坑）

### 3.1 OpenAI 入口：逐个报错 ✅

实测逐参数验证，**全部是 400，不是静默忽略**：

| 请求 | 实际响应 |
| --- | --- |
| `kimi-k3` + `temperature: 0.7` | `400 invalid temperature: only 1 is allowed for this model` |
| `kimi-k3` + `top_p: 0.5` | `400 invalid top_p: only 0.95 is allowed for this model` |
| `kimi-k3` + `n: 2` | `400 invalid n: only 1 is allowed for this model` |
| `kimi-k3` + `presence_penalty: 1` | `400 invalid presence_penalty: only 0 is allowed for this model` |
| `kimi-k2.7-code` + `temperature: 0.7` | `400 invalid temperature: only 1 is allowed for this model` |
| `moonshot-v1-8k` + `temperature: 1.5` | `400 Invalid request: temperature must not be greater than 1.000000` |
| `moonshot-v1-8k` + `temperature: 0.7` | ✅ 200 |

| 参数 | `moonshot-v1` | `kimi-k3` / `kimi-k2.7-code` |
| --- | --- | --- |
| `temperature` | 0–1，默认 **0** | 固定 `1.0`，**传其他值 400** |
| `top_p` | 0–1，默认 1 | 固定 `0.95`，**传其他值 400** |
| `n` | 1–5，默认 1 | 固定 `1`，**传其他值 400** |
| `presence_penalty` / `frequency_penalty` | −2–2，默认 0 | 固定 `0`，**传其他值 400** |

**三条独立的怪癖：**

1. **`temperature` 默认值跨代反转**：moonshot-v1 默认 **0**，新模型固定 **1.0**。"同一家 API，不传 temperature 时的行为随模型跳变"。中转站若为对齐 OpenAI 而主动补默认 `temperature`，在 v1 上改变原有行为，在 K3 上直接 400。**结论：绝不给未传的参数补默认值。**
2. **`temperature` 上限是 1 而非 2**（OpenAI 是 2）。
3. 🆕 **`n > 1` 与 `temperature` 存在隐藏耦合**——在 moonshot-v1 上传 `n: 3` 而不动 temperature：

   ```
   400 Invalid request: n should not be greater than 1 when temperature is less than or equal to 1e-5
   ```

   因为 v1 的 temperature 默认是 0，**要用 `n > 1` 就必须同时把 temperature 设为 > 0**。文档从未提及这个约束。中转站转发 `n>1` 请求时得连带检查 temperature，否则报出的错会让用户完全摸不着头脑。

✅ 其他约束实测确认：`stop` 数组最多 5 个——传 6 个报 `400 stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead`（错误信息质量不错）。

🆕 **未知参数静默忽略**：传 `"foo_bar": 123` → 200 正常返回。即"未知字段宽松、已知字段严格"——这与多数厂商一致，但和它对已知参数的严苛形成反差。

### 3.2 Anthropic 入口：同样的参数被静默忽略 🆕

```
OpenAI 入口     kimi-k3 + temperature=0.7  → 400
Anthropic 入口  kimi-k3 + temperature=0.7  → 200（正常返回，参数被忽略）
Anthropic 入口  kimi-k3 + top_p=0.5        → 200
```

**同一个模型、同一个参数、两个入口结果相反。** 这是 DeepSeek "三入口行为不一致"的翻版（见 `deepseek.md`）。

> 中转站落地建议：为 Kimi 上游维护**按模型的参数白名单**，对新模型剥离 `temperature/top_p/n/presence_penalty/frequency_penalty` 后再转发。**这是本文件最该优先实现的一条规则**——它同时解决了两个入口的差异（剥离后两边行为一致）。

### 3.3 `max_tokens` vs `max_completion_tokens` ✅（实测厘清）

两个名字都能用。同时传时 **`max_completion_tokens` 优先**：

```
{"max_tokens": 1500, "max_completion_tokens": 30} → completion_tokens: 30, finish_reason: "length"
```

文档的参数表只列 `max_completion_tokens`，正文却反复用 `max_tokens`，两者是新旧别名关系（文档未声明）。中转站两个都要能发，且注意优先级。

---

## 4. 思考模型：文档与实现脱节最严重的一节

| 模型 | 开关参数 | 能否关闭 | 实测 |
| --- | --- | --- | --- |
| `kimi-k3` | `reasoning_effort`（`low`/`high`/`max`，默认 `max`）**和** `thinking.type` | ❌ **文档说不能，实测能** | 见 §4.1 |
| `kimi-k2.7-code` | `thinking.type` | ✅ 确实不能 | `400 invalid thinking: only type=enabled is allowed for this model` |
| `kimi-k2.6` | `thinking.type`：`enabled`/`disabled` | ✅ 能 | 200，`reasoning_content: ""` |
| `kimi-k2.5` | `thinking.type` | ⚠️ 未测 | — |

### 4.1 ❌ K3 的思考**可以**关闭（推翻文档）

文档（K3 quickstart、thinking 指南、troubleshooting 三处）都说"K3 始终开启思考模式，不可关闭，只能调 `reasoning_effort`"。实测：

```jsonc
// 请求
{"model":"kimi-k3","messages":[{"role":"user","content":"说:好"}],"max_tokens":1500,"thinking":{"type":"disabled"}}
// 响应 200
{"choices":[{"message":{"role":"assistant","content":"好"},"finish_reason":"stop"}],
 "usage":{"prompt_tokens":21,"completion_tokens":11,"total_tokens":32}}
```

- **没有 `reasoning_content` 字段**（不是空字符串，是字段不存在）。
- **`prompt_tokens` 从 88 掉到 21**。同一条 user 消息，思考开启时 88、关闭时 21——差值约 67 token 是**思考模式注入的隐藏 system prompt**。这也解释了为什么 `estimate-token-count` 对四个汉字的消息返回 87：**官方 tokenizer 把这段隐藏 prompt 也算进去了**。

🆕 **`thinking.disabled` 优先于 `reasoning_effort`**：两个同时传（`thinking:{"type":"disabled"}` + `reasoning_effort:"max"`）→ 思考仍然关闭，`prompt_tokens: 21`。

> 对中转站的影响是正面的：**"关闭思考"这个语义在 K3 上是可表达的**，能力降级表里不必再写"无法关闭"。但因为文档明说不行，这条**属于未文档化行为，随时可能变**——建议在实现里做成可开关的特性，并在上游探测时验证。

### 4.2 ❌ `reasoning_effort` 的枚举校验形同虚设（推翻文档）

`/v1/models` 明确声明 `valid_efforts: ["low","high","max"]`，但：

```
reasoning_effort: "medium"  → 200 正常思考（OpenAI 的枚举值）
reasoning_effort: "banana"  → 200 正常思考（完全非法的值）
```

**任意字符串都被接受并静默忽略。** 好消息是中转站不必做 `minimal`/`medium` → `low`/`high` 的枚举映射（不会 400）；坏消息是**用户传错值不会有任何反馈**，只会默默跑在默认的 `max` 档（最贵）。中转站若要给用户可预期的成本，应当自己校验枚举并拒绝非法值。

🆕 `kimi-k2.6` 传 `reasoning_effort: "low"` → 200，但仍正常思考（`reasoning_tokens: 151`）——同样是被忽略。

### 4.3 `reasoning_content` 的回传要求 ✅ 部分推翻

- 响应里思考内容在 `choices[].message.reasoning_content`（**明文**，无签名）。
- ✅ 流式中 `reasoning_content` **确实先于 `content` 出现**（实测 186 个 chunk 全是 reasoning_content 后才出 content）。`content` 开始即代表思考结束，是可靠的状态机切换信号。
- ✅ `reasoning_content` 计入 `completion_tokens`，并单独报在 `completion_tokens_details.reasoning_tokens`。
- ❌ **文档说"K3/K2.7-code 多轮缺少 `reasoning_content` 会报错"——实测不报错**：

  ```
  多轮 assistant 消息只带 content + tool_calls、不带 reasoning_content → 200 正常继续
  ```

  中转站不必强制存档回放 `reasoning_content`（虽然存了对模型质量更好）。这条推翻降低了实现负担——**但也意味着 Preserved Thinking 的实际语义比文档描述的松**，⚠️ 建议在长对话+多步工具链场景再验一次。

### 4.4 `max_tokens` 太小导致空 `content` ✅（实测确认）

```jsonc
{"model":"kimi-k3","max_completion_tokens":30,...}
→ 200 {"message":{"content":"","reasoning_content":"The user asked..."},"finish_reason":"length"}
```

token 全烧在思考上，`content` 为空字符串。官方建议 `max_tokens >= 16000`。

> **"200 OK + 空 content"是 Kimi 的正常返回，不能当上游故障重试**——重试只会再烧一遍思考 token。应原样透传让下游看到 `finish_reason: "length"`。

---

## 5. Partial Mode（前缀续写）✅

```json
{"role": "assistant", "content": "[\"红\",", "partial": true, "name": "可选"}
```

实测 200，返回 `" \"绿\", \"蓝\"]"`——**响应不含前缀**，需客户端自己拼。

| 维度 | Kimi | DeepSeek | Anthropic |
| --- | --- | --- | --- |
| 字段名 | **`partial: true`** | `prefix: true` | 无字段，末条 assistant 即前缀 |
| 端点 | 正式端点 | 需 `/beta` | 正式端点（Claude 4.6+ 已禁用） |

**同一能力三家三个名字**——中转站 IR 里应有单一 `prefill` 标志（见 `api-design.md`），落地时翻译成对应字段。

❌ **`partial` + `response_format: json_object` 不冲突**（推翻 `chat.md` 里那条警告）：

```
{"partial":true,"content":"{"} + response_format:{"type":"json_object"} → 200，正常续写出完整 JSON
```

这是实践中最常用的组合（前缀写 `{` 强制 JSON 开头），可以放心用。

⚠️ `name` 字段是 Kimi 独有语义：OpenAI 的 `name` 是"多说话人区分"，Kimi 在 partial 场景当"人设锚点"。转发时不要想当然丢弃。

⚠️ 与思考叠加的陷阱（文档提示，未实测）：K3 思考开启时若 `max_tokens` 太小，会在思考阶段截断导致 `content` 为空，**下一次续写等于从零重来**。

---

## 6. 工具调用

### 6.1 与 OpenAI 的差异 ✅/❌

`tools[] / tool_calls[] / role:"tool"` 结构、流式 `delta.tool_calls[].index` 累积规则均与 OpenAI 相同。差异：

1. ❌ **`role: "tool"` 消息的 `name` 字段实际可选**（推翻文档）。文档说"必须提供 `tool_call_id` 和 `name`，Kimi 才能正确匹配"，实测只给 `tool_call_id` 不给 `name` → **200 正常**。中转站从 Anthropic 入口转换时不必回查函数名（Anthropic 的 `tool_result` 只有 `tool_use_id`）。
2. ✅ **`tool_call_id` 必须严格匹配**：传一个不存在的 id →

   ```
   400 Invalid request: tool_call_id  is not found
   ```

   🆕 注意错误信息里 `tool_call_id` 和 `is not found` 之间是**两个空格**——本该填 id 值的位置是空的，是个字符串拼接 bug。**中转站不要指望从这条错误信息里解析出是哪个 id 出的问题。**
3. ✅ `finish_reason: "tool_calls"` 时 `content` 可能非空（Kimi 会解释为什么调用）。按"有 tool_calls 就忽略 content"写的下游会丢内容。
4. 🆕 **`tool_calls[].id` 不是随机串，而是 `{函数名}_{序号}`**：

   ```json
   {"index":0,"id":"get_weather_0","type":"function","function":{"name":"get_weather",...}}
   ```

   OpenAI 是 `call_abc123...` 的不透明随机串。这个格式**可预测且与函数名耦合**。风险有两层：中转站若按 id 反查函数名会"碰巧能用"，形成隐式依赖，换上游即崩；且多轮对话里**同名函数会产生重复 id**（第二轮又是 `get_weather_0`），若中转站用 id 做全局去重键会误判。**建议中转站重写 tool_call id 为自己的不透明 id 并维护映射表。**
5. ✅ `finish_reason` 枚举为 `stop` / `length` / `tool_calls`，**没有国产厂商常见的 `sensitive`**——内容安全走 400 `content_filter`，不污染枚举。

### 6.2 `tool_choice` 与思考的互斥 ✅，但有一个危险的例外 🆕

| 模型 / 条件 | `required` | 具体函数 |
| --- | --- | --- |
| `kimi-k3`（思考开） | ✅ **200 正常工作** | ❌ 400 `tool_choice 'specified' is incompatible with thinking enabled` |
| `kimi-k3`（思考关） | ⚠️ 未测 | 🆕 **200，但见下** |
| `kimi-k2.7-code`（思考不可关） | ❌ 400 `tool_choice 'required' is incompatible with thinking enabled` | ❌ 400 |
| `kimi-k2.6`（思考关） | ⚠️ 未测 | ✅ 200 正常调用工具 |
| Anthropic 入口 `kimi-k3` | ⚠️ 未测 | ❌ 400（同 OpenAI 入口） |

- ✅ K3 思考开启时 `required` **可用**（文档未明说，实测正常返回 tool_calls）；但 K2.7-code 的 `required` **报错**，错误信息是"与思考不兼容"。同样是"思考开启"，两个模型对 `required` 的判定不同。
- 🆕 **最危险的一条**：K3 关闭思考 + `tool_choice` 指定函数 → **HTTP 200，但模型没有调用工具，而是直接编造了结果**：

  ```jsonc
  // 请求：tool_choice 强制 get_weather，thinking disabled
  // 响应 200，无 tool_calls，finish_reason: "stop"
  {"content":"北京现在的天气情况如下：\n- **天气**：晴\n- **温度**：28°C\n- **湿度**：45%\n- **风向**：南风..."}
  ```

  **`tool_choice` 被静默无视，模型直接幻觉出一份完整的天气数据。** 这比 400 危险得多——下游代码等着解析 `tool_calls`，拿到的却是一段看起来很真的假数据。**中转站不应把"关闭思考"作为绕过 `tool_choice` 限制的变通方案**，那样只是把显式失败变成静默错误。

> 结论：思考开启时无法强制指定函数，这个缺口**无法用参数改写安全绕过**。能力降级表建议**显式报错**而非降级。

### 6.3 动态工具加载（K3 独有）✅ 实测确认

```json
{"role": "system", "tools": [{"type":"function","function":{...}}]}
```

- 这条 system 消息**没有 `content` 字段**——OpenAI 协议里不存在的消息形状。实测 K3 上 200 正常，模型正确调用了工具。
- ✅ `kimi-k2.6` 上 → `400 Invalid request: tokenization failed`（一个极不直观的报错，实测确认）。
- 消息位置决定工具从哪轮起可见；与顶层 `tools` 可共存。
- 官方指出顶层 `tools` 不影响前缀缓存，动态工具因进了消息历史所以会影响。

> 中转站风险：这条消息**无法用 OpenAI/Anthropic 语义表达**。若做严格消息 schema 校验（"system 必须有 content"）会把合法请求拒掉。**IR 里要给消息保留 passthrough 扩展字段，别做白名单式裁剪。**

### 6.4 内置工具：两套并存 ✅/⚠️

**（a）`builtin_function` 协议**（实测确认）：

```json
{"type": "builtin_function", "function": {"name": "$web_search"}}
```

实测响应：

```json
{"tool_calls":[{"id":"t-web_search-6a7d5fde","type":"builtin_function",
  "function":{"name":"$web_search","arguments":"{\"search_result\":{\"search_id\":\"dda31b08...\"},\"usage\":{\"total_tokens\":6674}}"}}]}
```

- 🆕 `tool_calls[].type` 回传的是 **`builtin_function`**，不是 OpenAI 枚举里的 `function`。**下游若按 OpenAI 枚举做校验会拒掉这个响应。**
- 🆕 id 格式又是另一套：`t-web_search-{短hash}`（与普通工具的 `get_weather_0` 不同）。
- ✅ 反直觉之处确认：**模型内部已执行搜索**（`arguments` 里直接带 `search_id` 和 `usage.total_tokens: 6674`），但客户端仍要把 `arguments` **原样**塞回 `role: "tool"` 消息再发一次。即"假装自己执行了"。
- 🆕 注意首轮的 `usage.total_tokens` 只有 93，而 arguments 内嵌的 `usage.total_tokens` 是 **6674**——**搜索消耗的 token 不在响应的 usage 里**，要从 arguments 里解析。中转站按响应 usage 计费会漏掉绝大部分搜索成本。
- ✅ 计费：每次搜索按次收费，搜索结果计入下一轮 `prompt_tokens`。

**（b）官方工具（Formula API）** ⚠️ 未实测 —— 另一套体系，12 个工具：`convert`、`web-search`、`rethink`、`random-choice`、`mew`、`memory`、`excel`、`date`、`base64`、`fetch`、`quickjs`、`code-runner`。走标准 `function` 协议 + Formula URI（`moonshot/{tool-name}:latest`），搜索类返回 `encrypted_output`（`----MOONSHOT ENCRYPTED BEGIN----...`）需原样回传。

⚠️ **`web-search`（连字符，官方工具）与 `$web_search`（美元符号，builtin_function）是两个不同的东西**，文档没交代关系。已实测的是后者。

> 中转站建议：内置工具**不要跨厂商翻译**（OpenAI `web_search_preview`、Anthropic `web_search_20250305`、Kimi `$web_search` 的执行模型和计费都不同），按 opaque 透传，并在文档标明"内置工具与上游绑定"。

---

## 7. 结构化输出 ✅（文档为准，部分实测）

`response_format` 支持 `text` / `json_object` / `json_schema`。

```json
{"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}}
```

- ✅ `json_object` 实测可用，且可与 partial 叠加（§5）。
- ⚠️ `strict: true` 走 token 级约束解码，要求 schema 符合 **MFJS（Moonshot Flavored JSON Schema）**——**自造方言**，与 OpenAI Structured Outputs 子集不是同一套。文档未给完整规则页。**未实测。**
- ⚠️ 文档罕见坦诚地承认支持度**按模型分层**：`kimi-k2.7-code` 最全（`anyOf`/`oneOf`/`$ref`/`additionalProperties`）；`kimi-k3` 稳定；**`kimi-k2.6` 复杂 schema 不稳定——`$ref` 可能返回 Markdown 代码块、`oneOf` 可能被忽略**。
- ✅ JSON Mode 只保证生成 JSON **Object**（不会返回顶层数组/标量）。

> 建议：`json_schema` **不做跨家 schema 转换**，透传 + 记录失败率。K2.6 可能吐 Markdown 围栏意味着"保证返回合法 JSON"的承诺需要中转站自己剥围栏——那属于改写响应体，需明确取舍。

---

## 8. 流式输出：`usage` 位置**由 `include_usage` 决定** ❌（推翻文档）

文档说 usage "只出现在最后一个 chunk 的 `choices[0].usage`，OpenAI SDK 的 `chunk.usage` 返回 None"。实测发现**两种模式并存，取决于是否传 `stream_options.include_usage`**：

**不传 `include_usage`**（Kimi 私有行为）：

```jsonc
// 最后一个 chunk —— usage 嵌在 choices[0] 里，与 finish_reason 同层
data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop",
  "usage":{"prompt_tokens":88,"completion_tokens":211,"total_tokens":299,
           "completion_tokens_details":{"reasoning_tokens":186}}}],"system_fingerprint":"fpv0_489ccb45"}
data: [DONE]
```

**传 `stream_options: {"include_usage": true}`**（与 OpenAI 完全一致）：

```jsonc
// 独立的最后一个 chunk —— choices 为空数组，usage 在顶层
data: {"id":"...","object":"chat.completion.chunk","choices":[],
  "usage":{"prompt_tokens":88,"completion_tokens":182,"total_tokens":270,"cached_tokens":88,
           "completion_tokens_details":{"reasoning_tokens":166},"prompt_tokens_details":{"cached_tokens":88}}}
data: [DONE]
```

> **中转站结论（比文档的推论简单得多）：总是显式传 `stream_options.include_usage = true`**，就能拿到 OpenAI 标准位置的 usage，不必改写响应体。代价从"改写响应"降为"改写请求"。
>
> 两个附带差异：① 不传时**也有** usage（OpenAI 是不传就完全没有），所以"不传就没计费数据"的假设在 Kimi 上不成立；② **只有传了 `include_usage` 的那个 chunk 才带 `cached_tokens`**——不传时的 `choices[0].usage` 里没有缓存字段，会漏掉缓存计费信息。

其余流式行为 ✅ 与 OpenAI 一致：`data:` 前缀、`chat.completion.chunk`、**增量** delta（不是阿里那种全量累积）、`role` 只在首 chunk、中途有 `"delta":{}` 空 chunk、`data: [DONE]` 收尾。官方要求**以 `[DONE]` 判断结束而非 `finish_reason`**。

🆕 每个 chunk 都带 `system_fingerprint`（如 `fpv0_489ccb45`），**非流式响应里没有这个字段**——两种模式的响应字段集不一致。

### 自动断线重连 ⚠️

官方那篇《自动断线重连》**只是应用层 try/except 重试循环**（最多 100 次、间隔 1s），**没有任何协议级续传**——没有断点 offset，没有 resume id，重连就是整个请求重发。标题容易让人误以为有 resumable stream。中转站不要指望它做流式续传。

---

## 9. 多模态：**不支持 http(s) 图片 URL** ✅（实测确认）

```
{"type":"image_url","image_url":{"url":"https://statics.moonshot.cn/.../logo.png"}}
→ 400 Invalid request: unsupported image url: https://statics.moonshot.cn/.../logo.png
```

注意这个 URL 还是 Kimi 自家域名的图片，同样被拒。只接受两种形式：

- base64 data URI：`data:image/png;base64,...`
- **Kimi 自有文件协议：`ms://<file_id>`**（先经 `/v1/files` 上传）

> 与 OpenAI（接受公网 URL）和 Anthropic（`source.type: "url"`）的硬性差异。中转站要么替用户下载转 base64（引入出网、体积、超时、**SSRF** 风险），要么显式报错。**建议默认报错，把"自动下载转码"做成可选开关**——代下载会让中转站变成任意 URL 的抓取代理。

其他 ✅（文档，未逐条实测）：
- `image_url` 既接受 `{"url": "..."}` 对象也接受**直接字符串**，比 OpenAI 宽松。
- 请求体上限 **100MB**；图片张数无硬限，受体积约束。建议图片 ≤4K、视频 ≤1080p。
- **`content` 必须是真数组，不能是序列化后的 JSON 字符串**——文档特意警告"序列化成字符串后各模型行为不可预测"。中转站做消息归一化时若曾把 content 压成字符串（OpenAI 单文本场景的常见优化），多模态消息上必须禁用。
- 视频输入（`video_url`）仅 K2.5/K2.6/K2.7-code/K3 支持——**OpenAI 协议里没有的模态**，跨家映射无对应物。

---

## 10. Context Caching：全自动 ✅，但 256 token 阈值 ❌

⚠️ **历史怪癖已消失**：Kimi 早期的显式 Cache 对象 API 已被移除，现行是**全自动前缀缓存**，无需创建或引用 cache id。（`china-providers.md` §3 原先标注的"需查证"由此作废。）

❌ **文档说"prompt tokens > 256 才能命中前缀缓存"——实测不成立**：

```
prompt_tokens: 88 → cached_tokens: 88   （命中）
prompt_tokens: 21 → cached_tokens: 21   （命中，仅 21 token）
```

21 token 的请求也完整命中。实际阈值远低于 256，或该限制已取消。

🆕 **`cached_tokens` 在响应里出现两次**（同一个值）：

```json
"usage": {"prompt_tokens":88, "completion_tokens":211, "total_tokens":299,
          "cached_tokens": 88,                              // 扁平（Kimi 私有）
          "prompt_tokens_details": {"cached_tokens": 88}}   // 嵌套（OpenAI 兼容）
```

文档只提到扁平那个。**中转站直接用 `prompt_tokens_details.cached_tokens` 即可对齐 OpenAI，不需要做字段映射**（比文档描述的情况好）。同理输出侧有 `completion_tokens_details.reasoning_tokens`。

⚠️ 但注意**首次请求的响应里完全没有缓存字段**（未命中时字段不出现，而非返回 0）——解析时要容忍缺失。

✅ 生命周期由系统管理，TTL 未公开。✅ 计价差异极大（K3）：**命中 ¥2 / 1M，未命中 ¥20 / 1M**，输出 ¥100 / 1M。

> **中转站影响（被低估的一条）**：10 倍输入价差意味着"保持前缀稳定"是硬性成本要求。任何对 prompt 前缀的改写——注入 system 提示、重排消息、规范化空白、动态插入时间戳——都会让缓存失效，成本瞬间 10 倍。**规则：对 Kimi 上游的请求，前缀必须逐字节稳定。** 同理动态工具进消息历史会影响缓存，顶层 `tools` 不会（§6.3）。

🆕 **`prompt_cache_key` 实测被接受**（200，不报错），但因为缓存本来就自动命中，无法从外部观测它是否真的分裂了缓存命名空间。⚠️ 语义仍未知，文档的 Context Caching 指南完全没提这个参数。

🆕 **Anthropic 入口的 `cache_control: {"type":"ephemeral"}` 被接受但不生效**：返回 `cache_creation_input_tokens: 0`。自动缓存机制接管了，显式缓存断点是空操作。

---

## 11. 文件、Batch 与辅助端点

### 11.1 文件问答 ✅（文档，未实测）

流程是"上传 → 抽取 → **把抽取出的文本当作 system 消息塞进 messages**"，官方强调放的是**文件内容而不是 file id**。模型侧没有"引用 file id 做问答"的通道（`ms://` 只用于多模态图片/视频块）。

- 单用户最多 **1000 个文件**，单文件 **100MB**，空文件报错。
- ⚠️ **`purpose` 取值文档自相矛盾**：错误码页说"仅接受 `file-extract`"，batch 创建页要求 `purpose="batch"`。至少两个合法值。
- 抽取行为：文本原样抽；图片走 OCR（**无文字则失败**）；PDF 直接抽文本，纯图 PDF 走 OCR。
- 文件类 API **限时免费**。

### 11.2 Batch API ✅（文档，未实测）

- `POST /v1/batches`，字段 `input_file_id` / `endpoint`（仅 `/v1/chat/completions`）/ `completion_window` / `metadata`（≤16 对，key ≤64 字符，value ≤512 字符）。
- ⚠️ `completion_window` 取值两处不一致：API 页说"最小 12h 最大 7d"，指南页说 `24h`/`3d`/`7d`。
- **省 40%** 推理费。**仅支持 `kimi-k2.6` / `kimi-k2.5`，不支持 `kimi-k3`**。
- batch 请求体里**不得包含** `temperature` / `top_p` / `n` / 两个 penalty——§3 那条规则在 batch 上变成"不许出现"而非"必须等于固定值"。
- JSONL 每行需 `custom_id`（文件内唯一）/ `method`（固定 POST）/ `url`（固定 `/v1/chat/completions`）/ `body`，文件 ≤100MB。
- 支持多模态 batch（base64 或 `ms://`）。

### 11.3 官方 tokenizer ✅（实测）

```
POST /v1/tokenizers/estimate-token-count
{"model":"kimi-k3","messages":[{"role":"user","content":"你好世界"}]}
→ {"code":0,"data":{"total_tokens":87},"scode":"0x0","status":true}
```

🆕 **四个汉字算出 87 token**——因为它把 §4.1 那段思考模式的隐藏 system prompt（约 67 token）也算进去了，与实际 chat 请求的 `prompt_tokens: 88` 基本吻合。

> 这其实是好事：**官方 tokenizer 的口径与计费口径一致**，中转站做成本预估/限流应当用它，而不是套 tiktoken（Kimi 不是 OpenAI 词表）。但要知道它包含隐藏开销，别拿它的结果去和"用户可见文本长度"做对比，会显得离谱。代价是每次预估多一次网络往返。

### 11.4 余额 ✅（实测）

```
GET /v1/users/me/balance
→ {"code":0,"data":{"available_balance":15,"voucher_balance":15,"cash_balance":0},"scode":"0x0","status":true}
```

`cash_balance` **可为负数表示欠费**；`available_balance <= 0` 时无法调用推理 API。可作上游健康检查与余额预警（对应 DeepSeek 的 `/user/balance`，路径和字段名都不同）。

❌ **文档说"K3 需最低充值 ¥10 解锁，注册代金券不解锁 K3"——不成立**：实测账号 `cash_balance: 0`、余额全是代金券，K3 调用完全正常。

---

## 12. 错误码与限流

### 12.1 错误体 ✅/🆕

OpenAI 入口：`{"error": {"message": "...", "type": "..."}}`——**没有 OpenAI 的 `code` / `param` 字段**。中转站若要输出严格 OpenAI 错误结构需补 `code: null` / `param: null`。

另有 Anthropic 入口格式和网关格式，共三种，见 §1.3。

### 12.2 错误码表 ✅（打勾项为实测触发）

| HTTP | `type` | 触发 |
| --- | --- | --- |
| 400 | `invalid_request_error` | ✅ 参数越界/固定值不符/schema 错/`tokenization failed`/`unsupported image url`/`tool_call_id is not found` |
| 400 | `content_filter` | 内容安全拦截 |
| 401 | `invalid_authentication_error` / `incorrect_api_key_error` | 鉴权头格式错 / key 无效（**含拿错区域的 key**） |
| 403 | `permission_denied_error` | API 未开通 / 越权 / IP 不在组织白名单 |
| 404 | `resource_not_found_error` | ✅ 模型不存在（下线模型、`kimi-k3[1m]`） |
| 429 | `engine_overloaded_error` | ✅ **上游过载**——退避重试 |
| 429 | `exceeded_current_quota_error` | **余额不足/欠费**——重试无用 |
| 429 | `rate_limit_reached_error` | ✅ **并发/RPM/TPM/TPD 超限**——降频 |
| 499 | `client_closed_request` | 客户端提前断开 |
| 500 | `server_error` / `unexpected_output` | 服务端错误 |
| 503 | `server_unavailable` | 扩缩容/维护 |
| 504 | — | **900 秒无响应**；官方建议长请求开 `stream: true` |

**429 必须按 `type` 分流** ✅——三种 429 处置完全相反：过载要退避、欠费重试纯属浪费、限流要降并发。只看状态码的通用重试逻辑在欠费时会打爆上游。实测两种 429 都遇到了，`engine_overloaded_error` 在正常低频调用下也会偶发。

🆕 **429 的错误信息泄漏账号标识**：

```
Your account org-xxxxxxxx<ak-xxxxxxxxxxxxxxxx> request reached organization max RPM: 3, please try again after 1 seconds
```

**org id 和 ak id（API key 的标识部分）直接出现在 message 里。** 中转站若把上游错误原样透传给下游，等于把自己的账号标识和 key 标识广播给所有用户。**这是必须在错误改写层拦截的信息泄漏点**，比 §1.2 的响应头更严重（响应头容易被整体过滤，错误 message 往往被原样转发）。

其他：
- ✅ **499 是非标准状态码**（nginx 系）。中转站的 HTTP 客户端和监控要能处理，别当 4xx 计入用户失败率。
- ✅ **504 的 900 秒超时**——中转站自身的上游超时必须 ≥900s，否则会在 Kimi 还在算时先断开，浪费已消耗的 token。
- ✅ 官方提醒：**OpenAI SDK 的自动重试会把 1 次请求放大成 2–3 次真实调用**，吃掉 RPM 配额。中转站应关掉 SDK 层重试，自己实现按 type 分流的重试。

### 12.3 限流响应头 🆕（文档完全未记载）

实测 429 响应头：

```
retry-after: 1
x-retry-after: 1
msh-cooldown-seconds: 1
```

**同一个信息重复了三份**（标准头 + 两个私有头），但**没有任何 `x-ratelimit-*` 头**——即**无法在请求成功时得知剩余配额**，只能等撞到 429 才知道。

> 中转站的配额管理因此只能靠本地计数 + 429 反馈，做不了"提前避让"。`retry-after` 是标准头，直接用它做退避即可。

### 12.4 限流分档 ✅

按累计充值金额定档（代金券不算）：

| Tier | 累计充值 | 并发 | RPM | TPM | TPD |
| --- | --- | --- | --- | --- | --- |
| 0 | ¥0 | 1 | 3 | 500K | 1.5M |
| 1 | ¥50 | 50 | 200 | 2M | 无限 |
| 2 | ¥100 | 100 | 500 | 3M | 无限 |
| 3 | ¥500 | 200 | 5K | 3M | 无限 |
| 4 | ¥5K | 400 | 5K | 4M | 无限 |
| 5 | ¥20K | 1K | 10K | 5M | 无限 |

✅ **Tier 0 的 3 RPM 是真实且严格的**——本次实测全程必须每请求间隔 21 秒，任何并发都立刻 429。联调时若发现大量 `rate_limit_reached_error`，先看档位而不是查代码。

🆕 响应头 `msh-gid` 直接给出档位（实测为 `free`），**中转站可用它自动探测上游档位并据此设置本地并发上限**，无需人工配置。

---

## 13. 计价（K3，人民币）✅

| 项 | 单价 / 1M tokens |
| --- | --- |
| 输入（缓存命中） | ¥2 |
| 输入（缓存未命中） | ¥20 |
| 输出 | ¥100 |

- 1M = 1,000,000。无按上下文长度分档。
- **输出是命中输入的 50 倍**。加上思考默认 `max` 档、隐藏 system prompt、Preserved Thinking，K3 的实际输出 token 量显著高于同类模型——实测一句"说:好"能烧掉 **310 个 completion tokens**（其中 287 是 reasoning），而关闭思考后只要 **11 个**。
- **同一请求关不关思考差 28 倍输出成本**，这是 §4.1"K3 思考实际可关"这条发现的直接价值。
- Batch 省 40%（不支持 K3）；联网搜索按次另计费，且**搜索 token 不在响应 usage 里**（§6.4）。

---

## 14. 实测推翻的文档结论（速查）

| # | 文档说法 | 实测结果 |
| --- | --- | --- |
| 1 | K3 思考恒开、不可关闭、不使用 `thinking` 参数 | ❌ `thinking:{"type":"disabled"}` 生效，`prompt_tokens` 88→21，无 `reasoning_content` |
| 2 | 流式 usage 只在 `choices[0].usage` | ❌ 传 `include_usage:true` 时在顶层 + `choices:[]`，与 OpenAI 一致 |
| 3 | `reasoning_effort` 仅接受 `low`/`high`/`max` | ❌ `"medium"`、`"banana"` 都返回 200，非法值静默忽略 |
| 4 | K3/K2.7-code 多轮缺 `reasoning_content` 会报错 | ❌ 200 正常继续 |
| 5 | `role:"tool"` 消息必须带 `name` | ❌ 不带也 200 |
| 6 | Partial Mode 与 `json_object` 冲突 | ❌ 200 正常工作 |
| 7 | 缓存需 prompt > 256 token 才命中 | ❌ 21 token 也命中 |
| 8 | K3 需最低充值 ¥10、代金券不解锁 | ❌ 纯代金券账号正常调用 K3 |
| 9 | Claude Code 用 `kimi-k3[1m]` | ❌ 两个入口都 404，正确名是 `kimi-k3` |
| 10 | `kimi-k2.5` context_length 128000（示例） | ❌ 实际 262144 |

**文档说不能、实际能**（1、3、4、5、6、7、8）意味着照文档写会**过度限制**；**文档说能、实际不能**（9）意味着照抄配置会**直接失败**。两个方向都有。

---

## 15. 仍待验证（下一轮实测）

1. **`json_schema` + `strict: true` 的 MFJS 实际约束**（§7）——本轮未测，是结构化输出的核心。
2. **K2.6 复杂 schema 吐 Markdown 围栏**的复现条件（§7）。
3. **官方工具（Formula API）与 `$web_search` 的关系**（§6.4）。
4. **`prompt_cache_key` 是否真的分裂缓存命名空间**（§10）——需要构造缓存命中/未命中对照。
5. **文件上传 `purpose` 的合法枚举全集**、Batch 端到端（§11.1、§11.2）。
6. **K3 关闭思考后 `tool_choice: "required"` 的行为**（§6.2）——指定函数已知会静默幻觉，`required` 未测。
7. **长对话 + 多步工具链下 `reasoning_content` 是否真的可省**（§4.3）——短对话已验证可省，长链路需复验。
8. **国际站 `api.moonshot.ai`** 的行为是否与国内站一致（本轮只测了国内站）。
9. **`kimi-k2.5`** 的思考开关与 max output（本轮未覆盖该模型）。

---

## 16. 中转站接入 checklist

**必须做的请求改写**：
- [ ] 按模型剥离 `temperature`/`top_p`/`n`/`presence_penalty`/`frequency_penalty`（§3）——**最高优先级**，同时消除两个入口的行为差异。
- [ ] 流式请求一律补 `stream_options.include_usage = true`（§8）——用改写请求换取 OpenAI 标准的 usage 位置和缓存字段。
- [ ] thinking 参数按模型分派：K3 可用 `reasoning_effort` 或 `thinking`；K2.7-code 只能 `enabled`；K2.6/K2.5 用 `thinking`（§4）。
- [ ] 自行校验 `reasoning_effort` 枚举（上游不校验，非法值会静默跑最贵档）（§4.2）。
- [ ] `prefill` → `partial: true`（§5）。
- [ ] `n > 1` 时连带检查 `temperature > 0`，否则上游报的错无法理解（§3.1）。
- [ ] 模型名 `kimi-k3[1m]` 之类的方括号后缀要拒绝或剥离（§1.3）。

**必须做的响应/错误改写**：
- [ ] **剥掉 `msh-org-id` / `msh-uid` / `msh-project-id` 响应头**（§1.2，账号标识泄漏）。
- [ ] **过滤 429 错误 message 里的 `org-xxx<ak-xxx>`**（§12.2，账号+key 标识泄漏）。
- [ ] 重写 `tool_calls[].id`（上游是 `{函数名}_{序号}`，多轮会重复）（§6.1）。
- [ ] 错误体补 `code`/`param` 以对齐 OpenAI；解析上游错误时容忍 `error` 字段可能是 string（网关格式）（§12.1、§1.3）。
- [ ] 非 chat 端点要剥掉 `{"code","scode","status","data"}` 业务包装（§1.2）。
- [ ] `tool_calls[].type` 可能是 `builtin_function`，不要按 OpenAI 枚举拒绝（§6.4）。

**必须保持不动的**：
- [ ] prompt 前缀逐字节稳定，不注入、不重排、不规范化空白（§10，**10 倍价差**）。
- [ ] `content` 数组不要压成字符串（§9）。
- [ ] 内置工具与 `encrypted_output` 按 opaque 透传（§6.4）。
- [ ] 不给未传参数补默认值（§3.1）。
- [ ] 消息保留 passthrough 扩展字段（动态工具的 `{"role":"system","tools":[...]}` 无 content）（§6.3）。

**能力降级表**：
- [ ] 思考开启时**无法强制调用指定函数**——应**显式报错**，不要靠关闭思考绕过（§6.2，会静默幻觉出假数据）。
- [ ] K2.7-code 思考不可关、`required` 也不可用（§4、§6.2）。
- [ ] 不支持 http(s) 图片 URL（§9）。
- [ ] 新模型不支持 `n > 1`（§3.1）。
- [ ] 动态工具加载仅 K3（§6.3）。

**运维配置**：
- [ ] 上游超时 ≥900s（§12.2）。
- [ ] 关闭 SDK 层自动重试，按 error `type` 分流（过载退避 / 欠费停止 / 限流降并发）（§12.2）。
- [ ] 用 `retry-after` 头做退避；**没有 `x-ratelimit-*`，配额只能本地计数**（§12.3）。
- [ ] 用响应头 `msh-gid` 自动探测账号档位并设置本地并发上限（§12.4）。
- [ ] key 与区域 base URL 绑定成对（§1.1）。
- [ ] "200 OK + 空 content + `finish_reason: length`" 不触发重试（§4.4）。
- [ ] 用 `/v1/tokenizers/estimate-token-count` 做预估（口径含隐藏 system prompt，与计费一致）（§11.3）。

**Kimi For Coding 走单独一套配置**（§17）：模型别名表、鉴权、限流、错误改写都不能与 platform 共用。

---

## 17. Kimi For Coding：同一家公司的另一套栈 ✅（2026-08-13 实测）

> Base URL：`https://api.kimi.com/coding/v1`（根路径 `https://api.kimi.com/coding/` 返回 `{"message":"Welcome to the Kimi For Coding API!"}`）
> Key 形如 `sk-kimi-...`。面向 Claude Code / 编码 Agent 的**订阅制**产品，不是 platform 的一个套餐。

**底层推理栈相同**（流式 `system_fingerprint` 两边都是 `fpv0_489ccb45`），**但接入层是完全独立的两套实现**。官方 troubleshooting 只用一句"API Platform keys ≠ Kimi Code keys"带过，实际差异远不止鉴权。

### 17.1 差异总表

| 维度 | platform（`api.moonshot.cn`） | Kimi For Coding（`api.kimi.com/coding`） |
| --- | --- | --- |
| Key 前缀 | `sk-` | **`sk-kimi-`** |
| 账号体系 | 组织/项目/余额 | **个人账号**（见 §17.4） |
| 模型名 | `kimi-k3`、`kimi-k2.7-code`、`moonshot-v1-*` | **`k3`、`k3-256k`、`kimi-for-coding`、`kimi-for-coding-highspeed`** |
| 模型名校验 | 严格，未知名 404 | ❌ **几乎不校验**（见 §17.3） |
| OpenAI 入口 | `/v1/chat/completions` | `/v1/chat/completions` |
| Anthropic 入口 | `/anthropic/v1/messages` | **`/v1/messages`**（与 chat 同前缀，无 `/anthropic`） |
| thinking `signature` | ❌ 无 | ✅ **有真实签名** |
| Anthropic usage 字段 | 混入 OpenAI 字段（双套并存） | **纯 Anthropic 字段** |
| Anthropic 响应 id | `chatcmpl-...`（不规范） | **`msg_...`**（规范） |
| SSE 事件分隔 | `event: message_start`（有空格） | `event:message_start`（**无空格**） |
| `count_tokens` | ❌ 无 | ✅ `POST /v1/messages/count_tokens` |
| `estimate-token-count` | ✅ 有 | ❌ 404 |
| 余额查询 | ✅ `/v1/users/me/balance` | ❌ **404，无余额端点** |
| 账号信息端点 | ❌ 无 | 🆕 **`/v1/me`（返回手机号等 PII）** |
| `tool_calls[].id` | `get_weather_0`（可预测、会重复） | **`tool_jfSEsjJ6HvGswLR2r8XaBjnc`**（随机串，规范） |
| `$web_search` 的 id | `t-web_search-{hash}` | `tool_{随机串}` |
| 响应 id | `chatcmpl-6a7d5c23...`（十六进制） | `chatcmpl-JfEbxqHjKWC5fADqUduALJfG`（大小写混合） |
| 限流 | Tier 0 = **3 RPM / 1 并发** | ✅ **并发 10 全部 200**，无可观测的 RPM 限制 |
| 调试响应头 | `msh-request-id` / `msh-org-id` / `msh-uid` / `msh-gid` | **`x-trace-id`**、`server-timing`、`server: nginx`（**无 `msh-*`**） |
| 网关错误 | 中文 `{"code":5,"error":"url.not_found","message":"没找到对象"}` | 统一 API 格式 `{"error":{"message":"The requested resource was not found","type":"resource_not_found_error"}}` |
| `/v1/models` 字段 | `owned_by`/`permission`/`root`/`parent` | **`display_name`/`created_at`/`type`** + 分页字段 `first_id`/`last_id`/`has_more` |
| `reasoning_effort` 默认 | `max` | **`high`**（省钱档） |

**行为一致的部分**（说明共用推理层）：采样参数硬 400（`invalid temperature: only 1 is allowed for this model` 逐字相同）、`tool_choice` 指定函数与思考互斥的 400、K3 `thinking:{"type":"disabled"}` 可关（`prompt_tokens` 同样 21）、partial mode、`$web_search` 的 builtin_function 协议、流式 usage 由 `include_usage` 控制、`system_fingerprint` 值相同。

🆕 但**同一个校验的错误文案两边不同**，说明校验逻辑各写了一遍：

```
n=2  platform : invalid n: only 1 is allowed for this model
n=2  coding   : Your request body contains invalid value for param n
```

### 17.2 模型列表（实测 `GET /coding/v1/models`）

| id | display_name | context | 实测备注 |
| --- | --- | --- | --- |
| `kimi-for-coding` | K2.7 Coding | 262144 | **未知模型名的 fallback 目标**（§17.3.1）；无隐藏 system prompt |
| `kimi-for-coding-highspeed` | K2.7 Coding Highspeed | 262144 | ⚠️ 与上一行**实测无法区分**（指纹、上限、速度全同） |
| `k3` | K3 | 1048576 | `default_effort: "high"`；带 79 token 隐藏 system prompt |
| `k3-256k` | K3-256k | 262144 | 实测是**网关层给 `k3` 加的 256K 限制**，非独立模型；`supports_video_in: false` |

四个模型全部 `supports_thinking_type: "only"`。**没有 moonshot-v1 系列**。

> ⚠️ 注意 `k3-256k` 是**同模型的短上下文 SKU**——这与 platform 用 `moonshot-v1-8k/32k/128k` 切窗口是同一思路，但命名规则又不一样。中转站的别名表要为两个上游各维护一份。

### 17.3 ❌ 最危险的差异：`model` 字段几乎不校验

实测 Kimi For Coding 对未知模型名**不报错，而是照常返回 200 并把请求的名字原样回显**：

```jsonc
{"model":"gpt-4",            ...} → 200，响应 "model":"gpt-4"，但内容带 reasoning_content（实际是 Kimi 在跑）
{"model":"claude-sonnet-4-5",...} → 200，响应 "model":"claude-sonnet-4-5"
{"model":"moonshot-v1-8k",   ...} → 200，响应 "model":"moonshot-v1-8k"（该模型在此产品里根本不存在）
{"model":"foobar123",        ...} → 200，响应 "model":"foobar123"
{"model":"",                 ...} → 200，响应 "model":""（空字符串也接受）
```

**唯一被拒的是带方括号的名字**，而且报错方式很离谱：

```
{"model":"k3[1m]"} → HTTP 401
{"error":{"message":"Your model id does not exist, recognized as other:k3[1m]. Please set model id as `k3`.",
          "type":"invalid_authentication_error"}}
```

**模型不存在却返回 401 + `invalid_authentication_error`**——状态码和错误类型都与语义不符（platform 同样情况返回的是 404 `resource_not_found_error`）。中转站若按 401 触发"key 失效"逻辑去刷新凭据或告警，会被这个错误误导。

> **对中转站的三重后果**：
> 1. **无法用模型名做路由校验**——上游不会告诉你名字写错了，只会默默用 fallback 模型跑完并收钱。
> 2. **响应的 `model` 字段不可信**——它是请求值的回显，不是实际推理的模型。platform 那边至少 `moonshot-v1-auto` 会回显真实模型名（§2.1），这边连这个都没有。
> 3. **下游可能被误导**：用户传 `gpt-4` 拿到 200 和一个 `"model":"gpt-4"` 的响应，会以为真的调用了 GPT-4。**中转站必须自己维护白名单并拒绝未知模型名**，不能依赖上游校验。

### 17.3.1 反推：模型名确实参与路由，未知名 fallback 到 `kimi-for-coding` ✅

响应只回显请求值，无法直接观测实际模型。用**两个独立的侧信道**反推，结论一致。

**方法一：上下文上限边界。** 构造 270,015 token 的 prompt（经 `count_tokens` 校准，介于 262144 与 1048576 之间），分别打各模型名：

| 请求的 model | 结果 |
| --- | --- |
| `k3` | ✅ **200 正常返回**（真的吃下了 270K） |
| `k3-256k` | `k3-256k supports only 256K context.` |
| `kimi-for-coding` | `Invalid request: Your request exceeded model token limit: 262144 (requested: 270016)` |
| `gpt-4` | **同上，逐字相同** |
| `foobar123` | **同上，逐字相同** |

**方法二：隐藏 system prompt 的 token 指纹。** §4.1 发现思考模式会注入一段隐藏 system prompt，各模型注入量不同，可作指纹。同一句 `"说:好"`：

| 请求的 model | `prompt_tokens` |
| --- | --- |
| `k3` | **89** |
| `k3-256k` | **89** |
| `kimi-for-coding` | **10** |
| `kimi-for-coding-highspeed` | **10** |
| `gpt-4` / `foobar123` / `""` / `claude-sonnet-4-5` | **10** |

两个方法交叉印证：

- ✅ **模型名确实参与路由**——`k3` 走 1M 上下文且带 79 token 的隐藏 system prompt；`kimi-for-coding` 系列走 256K 且**无隐藏 prompt**。二者是两条不同的推理路径。
- ✅ **所有无法识别的模型名（含空字符串）一律 fallback 到 `kimi-for-coding` 系列**，**不是** `k3`。
- ✅ `k3-256k` 是**网关层对 `k3` 加的 256K 限制**，不是独立模型：它的隐藏 prompt 指纹与 `k3` 相同（89），但超限错误是一条**人工写的独立文案**（不含 `requested:` 数字），与 `kimi-for-coding` 那条模型层通用错误明显不同源。

> **中转站可直接用的结论**：用户若传了拼错的模型名，实际跑的是 K2.7 Coding（256K），而不是他以为的 K3——**上下文能力从 1M 悄悄降到 256K**，长上下文任务会在毫无提示的情况下超限失败。这使"自建模型名白名单"从建议变成必需。

⚠️ 仍无法区分的是 `kimi-for-coding` 与 `kimi-for-coding-highspeed`：两者 token 指纹相同（均为 10）、上下文上限相同（262144）、**实测输出速度也无差异**（33.2 vs 34.9 tok/s，重复一轮后 highspeed 反而更慢）。官方宣称 highspeed 约 180 tok/s，**实测两者都只有约 33 tok/s**——要么高速档在当前负载/订阅层级下未生效，要么二者本就是同一后端。

### 17.4 🆕 `/coding/v1/me` 返回个人身份信息（隐私暴露面）

platform 只有余额端点（返回金额），Kimi For Coding 则有一个 `/v1/me`：

```jsonc
{
  "user_id": "...", "global_id": "...",
  "nickname": "登月者XXXX",
  "avatar": "https://avatar.moonshot.cn/avatar/default/...",
  "phone": {"country_code": "86", "number": "1XX****XXXX"},   // ← 部分脱敏的手机号（实测返回真实号码的首三位+后四位）
  "status": "USER_STATUS_NORMAL", "region": "REGION_CN",
  "user_level": 25, "user_level_name": "Allegretto",
  "domain": 1, "domain_name": "DOMAIN_NEXUS",
  "created_time": "...", "last_login_time": "..."
}
```

> **任何持有这个 key 的人都能读到账号主人的手机号（部分脱敏）、昵称、注册与最后登录时间。** 对中转站的含义：
> - **把 Kimi For Coding 的 key 交给第三方使用 = 交出账号主人的部分身份信息**，风险等级远高于 platform 的 key（那边最多泄漏余额）。多租户中转站尤其要注意。
> - 中转站**不应把 `/v1/me` 透传给下游**。若要做上游健康检查，用它是可行的（无余额端点可用），但响应必须裁剪，只保留 `status`。
> - 反过来，这也是**唯一能确认 coding key 是否有效**的轻量端点（没有余额接口）。

### 17.5 计费与配额：中转站看不见

- ❌ **没有余额/用量端点**（`/balance`、`/usage`、`/quota`、`/subscription` 全部 404）。订阅制产品，用量只能在网页端看。
- 因此**中转站无法对 Kimi For Coding 做余额预警或成本核算**——只能自己按 usage 累加统计，且没有官方口径可对账。这与 platform（有 `/v1/users/me/balance`，可做健康检查与预警）是运维层面的实质差别。
- 限流宽松（10 并发实测无 429），但**限额规则未公开**，撞到限制时的错误类型未知（本轮未触发）。⚠️ 中转站应做好"上游可能在没有任何预警的情况下拒绝服务"的准备。

### 17.6 Anthropic 入口质量反而更高

Kimi For Coding 的 `/coding/v1/messages` 是**本次调研里最接近 Anthropic 官方规范的实现**：

- ✅ 规范的事件序列：`message_start` → `content_block_start` → `content_block_delta` ×N → `content_block_stop` → `message_delta` → `message_stop`
- ✅ `msg_` 前缀的 id、纯 Anthropic 的 usage 字段、**thinking block 带 `signature`**
- ✅ 有 `POST /v1/messages/count_tokens`（返回 `{"input_tokens":9}`）
- ✅ `x-api-key` 和 `Authorization: Bearer` 都接受，`anthropic-version` 头非必需

对比 platform 的 `/anthropic/v1/messages`：id 是 `chatcmpl-`、usage 混两套字段、thinking 无 signature、无 count_tokens。

> **中转站若要做 Anthropic 格式的上游，Kimi For Coding 明显是更合适的一侧。**

### 17.6.1 反推：`signature` 是**装饰品**，服务端不校验 ✅

Anthropic 真机会校验 thinking 的 `signature`（篡改会报错），这是"推理内容不可跨家搬运"结论的根基（见 README §2 第 2 条）。实测 Kimi For Coding 的 signature（长达 12,946 字符，看起来很像真的）：

| 多轮回传时对 thinking block 的处理 | 结果 |
| --- | --- |
| 原样回传 | 200 |
| **signature 全部替换成 `XXXX...`**（等长） | **200** |
| **完全删除 `signature` 字段** | **200** |
| **保留原 signature，但把 `thinking` 文本换成伪造内容** | **200** |

**四种情况全部正常返回，没有任何校验。**

> 这条对中转站是**减负**：Kimi For Coding 的 thinking block **不必当 opaque blob 搬运**，可以自由丢弃 `signature`、截断甚至改写 thinking 内容——与 platform 那侧（明文无签名）的处理方式可以统一。
>
> 但反过来它是个**安全提示**：这个 signature 只是长得像密码学签名，实际不提供任何完整性保证。**中转站不要把它当作"上游已验证推理内容"的证据**，也不要在自己的对外 API 里模仿这种"假签名"——下游若据此信任内容，就是被误导。
>
> ⚠️ 注意方向性：这条结论**只适用于 Kimi**。转发到 Anthropic 真机时，signature 仍必须原样搬运。

### 17.7 结论：必须分开处理

**是的，必须当作两个完全独立的上游。** 具体到实现：

| 层面 | 要点 |
| --- | --- |
| 上游配置 | 独立的 base URL + key + 模型别名表；key 前缀（`sk-` vs `sk-kimi-`）可用于自动识别配错 |
| 模型路由 | **中转站自建白名单**——coding 侧不校验模型名，**错名静默 fallback 到 `kimi-for-coding`（256K），上下文能力从 1M 悄悄降级**（§17.3.1） |
| thinking | coding 侧的 `signature` 不参与校验，可自由丢弃/改写（§17.6.1）；转发到 Anthropic 真机时则必须原样搬运 |
| 响应处理 | coding 侧的 `model` 字段是回显值，**不可用于记账**；platform 侧 `moonshot-v1-auto` 也有类似问题 |
| 错误处理 | coding 侧模型不存在返回 **401**，不能触发凭据刷新逻辑；两侧错误文案不同 |
| 限流 | platform 需按 Tier 严格限速（Tier 0 = 3 RPM）；coding 侧宽松但规则不透明 |
| 运维 | platform 用 `/v1/users/me/balance` 做健康检查；coding 只能用 `/v1/me`（**响应需裁剪，含 PII**） |
| Anthropic 格式 | 优先用 coding 侧；但其 thinking `signature` 必须 opaque 搬运，platform 侧则不用 |
| 隐私 | coding key 泄漏 = 泄漏账号主人手机号等信息，**不可作为共享凭据下发** |