zend-token/docs/README.md

AI API 中转站 — 资料索引

本目录收集各 AI provider 的 API 规格与"怪癖"（quirks），用于实现一个多格式兼容的中转站（gateway）。

资料采集时间：2026-08-12。 各家文档变动频繁（尤其是模型名与 thinking 相关参数），落地实现前请对照文件头部的来源 URL 复核。

文件清单

文件	内容
api-design.md	本项目的 API 契约设计（双模板入口、IR、能力降级、thinking 桥接）— 其余文件是它的调研依据
transform-spec.md	转写方案 v0.3（四家求同存异、上游 Profile、请求/响应改写管线 R1–R9 / S1–S9、推理内容可信度分级）— api-design 的落地层
openai.md	OpenAI Chat Completions + Responses API 规格与怪癖
anthropic.md	Anthropic Messages API 规格与怪癖
deepseek.md	DeepSeek API 规格与怪癖
kimi.md	Kimi（月之暗面 Moonshot）API 规格与怪癖，含 Kimi For Coding 独立产品线对比（§17）
china-providers.md	国产厂商（通义/GLM/Kimi/豆包/文心/混元/MiniMax/星火）的怪癖
cross-provider-mapping.md	三家之间的字段/语义映射表，含流式事件映射
compatibility-layers.md	各家官方提供的"他家格式兼容层"，可作为中转站行为的参考实现
errors-and-limits.md	错误码、限流、超时、请求体积上限对照

中转站要处理的核心难题（速览）

1. 消息模型不同构：OpenAI 是扁平 messages[] + role: system；Anthropic 是 messages[] + 独立顶层 system，且 content 是 block 数组。转换必然有损。
2. 推理内容（thinking/reasoning）不可互换：Anthropic 的 thinking 文本只是摘要，真正的推理内容加密在 signature 里，服务端靠解密它重建思考——所以"翻译成字符串再翻译回来"是死路，只能把密文当 opaque blob 原样搬运。OpenAI 用 encrypted_content，DeepSeek 用明文 reasoning_content。三者回传规则均不同，详见 cross-provider-mapping.md §7。
3. 工具调用 ID 与结构：Anthropic tool_use.id / tool_result.tool_use_id（在 user 消息里）；OpenAI Chat 用 tool_calls[].id / role: tool 消息；OpenAI Responses 用 call_id。
4. 流式协议不同：OpenAI 是增量 delta 的 chat.completion.chunk + [DONE]；Anthropic 是有状态的 block 事件机（content_block_start/delta/stop），且 message_delta.usage 是累计值。
5. 未支持参数的处理策略：三家普遍静默忽略而非报错。中转站应明确选择"静默忽略"还是"显式报错"，并保持一致。

国产厂商的坑是另一个维度——不在语义层而在协议层：HTTP 200 里藏业务错误（MiniMax base_resp）、流式默认返回全量累积文本（阿里 incremental_output）、六种互不相同的鉴权方式、finish_reason: "sensitive" 打破 OpenAI 枚举。详见 china-providers.md，其中 §0 和 §9 是跨厂商的共性结论。

还有第三个维度：同一家 API 内部按模型/按入口分裂。 Kimi 是典型——temperature 在新模型上写死 1.0 且传其他值直接 400（OpenAI 客户端的默认值开箱打不通），但同样的参数走它自家的 Anthropic 入口却被静默忽略；流式 usage 的位置由 stream_options.include_usage 决定（不传就藏在 choices[0].usage）。即"合法请求体取决于 model 和入口"。详见 kimi.md，§16 是可直接落地的接入 checklist。

第四个维度是文档可信度。 Kimi 已用真实 key 实测，10 条文档明确写下的规则被推翻（含"K3 思考恒开不可关"这样的核心设定、以及官方 Claude Code 配置页照抄会 404 的模型名），见 kimi.md §14。教训是：涉及"报错/不支持/必须"的文档表述，落地前一律实测——两个方向的错都有（文档说不能实际能、文档说能实际不能）。

第五个维度：一个"厂商"可能是多个上游。 Kimi 的 platform（api.moonshot.cn）和 Kimi For Coding（api.kimi.com/coding）共用推理层却是两套接入实现——模型名、鉴权、限流、端点、错误语义、tool_call id 格式全不同，key 互不通用，且 coding 侧不校验模型名（传 gpt-4 返回 200 并原样回显）。中转站必须按两个上游配置。见 kimi.md §17。

未覆盖 / 待补

• Google Gemini（generateContent）— 用户未列入，尚未收集。
• 零一万物 Yi、百川、阶跃星辰 StepFun、商汤日日新。
• OpenAI Realtime API、Batch API、Embeddings 等非 chat 端点。
• DeepSeek multi_round_chat、token_usage、rate_limit 页面（内容与其他页重合度高，未单独抓取）。