一份烂透了的 LLM API 文档，比高定价更快杀死交易。我亲眼见过团队因为文档含糊，丢掉年均超过 30 万的合同——开发者搞不清楚基本的集成细节，直接放弃了。
好文档不是锦上添花——它是营收保护。文档清晰的 LLM API 团队，技术支持工单减少 60%，集成时间缩短 40%。
先写计费模型（买家第一个看这个）
计费模型决定了集成的一切。在文档开头就说清楚你是按 Token 计费、按次计费，还是混合模式。
不要把它埋在定价页的角落。直接在 API 概述里给出真实数字：
// 定价：输入 ¥0.014/1K tokens，输出 ¥0.056/1K tokens
// 限速：100 次/分钟，4 万 tokens/分钟
// 上下文窗口：最大 8,192 tokens如果你有旗舰档和经济档，直接链到分档策略页面。开发者在写第一行代码之前，就需要搞清楚成本影响。我见过团队在发现隐藏的按次费用会超出预算后，直接放弃了集成。
给出真实请求与响应（可直接复制）
没有什么比看起来不能运行的示例更让开发者抓狂。为你最常见的用例提供完整、可运行的代码片段。
| 要包含的 | 不必要的 |
|---|---|
| 带完整请求头的 curl 命令 | 伪代码"示例" |
| 3 种以上语言的 SDK 代码 | 只有 REST 端点 |
| 预期的响应 JSON | "返回用户数据"这种描述 |
| 错误响应示例 | 泛泛的错误说明 |
错误文档比成功案例更重要。明确展示限速、上下文超限、鉴权失败时的错误结构：
{
"error": {
"type": "rate_limit_exceeded",
"message": "速率超限：每分钟 100 次请求",
"retry_after": 45
}
}附上补救步骤。不要只说"被限速了"——告诉他们应该用指数退避，并给出具体等待时间。
用 Token 定义上限，不要模糊地写字符数
字符数对 LLM 集成规划毫无用处。Token 才是决定上下文窗口和计费的真实单位。
烂文档写的是："最大提示长度：约 32,000 字符。"
好文档写的是："上下文窗口：共 8,192 tokens（提示 + 补全）。英文平均约 4 字符/token，中文约 1.5-2 字符/token。"
提供 Token 计算器，帮开发者在上线前估算真实用量。文档里要把上下文预算拆清楚：
- 系统 prompt：约 200 tokens
- 用户消息：不定
- 响应预留：1,000 tokens
- 可用于用户内容的：7,000 tokens
维护公开变更日志（建立 API 信任）
模型升级和调价不应该让客户措手不及。公开的变更日志能让用户看到你在认真运营。
每条记录都要标日期，用语义化版本号管理 API 版本，破坏性变更要链到迁移指南。参考格式：
## 2026-04-01 - v2.1.0
### 新增
- 实时响应新端点 /v2/chat/stream
- 支持 chat completions 中的 function calling
### 变更
- 文本生成响应时间提升 15%
- 限速更新：200 次/分钟（原 100 次）
### 定价
- 输入 token 降至 $0.0015/1K（原 $0.002）
- 2026-05-01 生效补充实践集成指南
除了基础 API 参考，还要为常见集成模式写指南：聊天界面的流式响应、大数据集的批处理、错误处理与重试策略、成本优化技巧、生产部署检查清单。
建议按不同用例分别写快速上手指南。聊天机器人集成和内容生成流水线完全是两回事，混在一起会制造困惑。
什么时候不要过度写文档
不要给每种参数组合都写文档——那会让用户选择困难。先聚焦 80% 的用例，高级配置放补充指南。
跳过"LLM 是什么原理"的理论解释——你的受众知道自己在构建什么，他们需要的是具体实现细节，不是 AI 科普。