---
title: '28 如何高效利用 API 文档'
video_id: MxyRjL7NG18
part: 28
---

> 章节 28 / 37 · [[00-总览|课程总览]] · 起始 [4:03:43](https://youtu.be/MxyRjL7NG18?t=14623)


## 章节主旨

在 Agentic 工作流里接入第三方 API 时,不要让模型自己上网去"读"文档——那样又慢、又容易踩错、还烧 context。本章讲更高效的做法:把文档手动粘进上下文一次到位,并识别那些已经为 AI 优化过的 API。

## 核心论点

1. **让模型自己搜 API 文档是最大的隐性成本**——它约一半时间在查文档、一半在踩错。([[#1-让模型自己查文档的双重损耗-40411|→ 详解1]])
2. **JS 渲染的文档页模型根本抓不到**,只能瞎猜端点,既不准又持续吃 context。([[#2-js-渲染文档页抓不到就开始瞎猜-40504|→ 详解2]])
3. **直接复制粘贴文档 = 一次给全**,省掉"搜索"这个会复合错误概率的额外步骤。([[#3-手动粘贴文档一次给全避免复合错误-40649|→ 详解3]])
4. **越来越多 API 主动为 AI 优化**(copy for LLM 按钮 / markdown 版),token 高效、AI 原生可读。([[#4-为-ai-优化的-apicopy-for-llm-与-markdown-40740|→ 详解4]])
5. **会连 API 就能承接自由职业市场上大量一次性对接需求**,这是可交付的实操能力。([[#5-会连-api--可变现的实操能力-40857|→ 详解5]])

## 知识点详解

### 1. 让模型自己查文档的双重损耗 [4:04:11](https://youtu.be/MxyRjL7NG18?t=14651)

当你只丢一个文档链接给模型、让它自己去读时,它会花掉大约一半时间在查阅 API 文档、另一半时间在撞各种错误上。表面看只是"帮我读一下",实际是把最不确定的一步交给了概率系统。

它拿到链接的第一反应是用 web search 工具去访问。但页面一旦返回不完整,模型就会反复兜圈子:再搜一次、再猜一次,始终拿不到确切的 endpoint schema、限流规则或代码示例。

### 2. JS 渲染文档页:抓不到就开始瞎猜 [4:05:04](https://youtu.be/MxyRjL7NG18?t=14704)

关键坑在于:有些 API 文档页只通过 JavaScript 加载。模型的抓取工具看到的是渲染前的空壳,端点根本不在 HTML 里,于是它只能开始"猜" JSON 结构、转头去翻别人的文档和博客帖子。

这一路的代价是可量化的:Nick 现场敲 `/context` 查看,还没干正事,message 上下文已经涨到 1.4%;若任其自己循环三十秒,轻松爬到 3%–5% 甚至更多。搜索这一步不但慢,还在持续侵蚀有限的上下文预算。

### 3. 手动粘贴文档:一次给全,避免复合错误 [4:06:49](https://youtu.be/MxyRjL7NG18?t=14809)

Nick 的做法是:自己打开需要的那几页文档(比如 open、get、URL 校验这些端点页),把内容**整段复制粘贴**进对话,直接告诉模型"这些是该服务的 API 文档,给我列出端点"。

这么做的逻辑是——让模型自己搜,是一个额外步骤,而额外步骤会**复合(compound)错误概率**。你把资料一次喂全,它第一次就能拿对,不再来回猜端点。要它照着写一段调用 POST 端点的 Python,它立刻就能给出完整正确的代码。

这正是概率系统 vs 确定性工作思路的落地:凡是能提前确定的输入,就别留给模型现场概率化处理。

### 4. 为 AI 优化的 API:copy for LLM 与 markdown [4:07:40](https://youtu.be/MxyRjL7NG18?t=14860)

有些 API 已经直接为大模型和 agentic 工作流做了适配。Nick 举的例子是 Apify 这类服务:文档页顶部带有 **copy for LLM** 按钮,还能一键 view as markdown、直接在 ChatGPT / Claude / Perplexity 里打开。

拷出来的其实就是整页内容的 markdown 版本。因为是 markdown,它天然更紧凑、更 token 高效,模型也原生就懂怎么遍历这种结构。把这段 markdown 粘给模型,它访问一次就能抓全并快速给出总览,后续追问端点也答得很顺。

背后的信号是:API 提供方正在预判 agentic 工作流会大规模到来,于是主动把文档做成对 AI 友好的 token 高效格式。遇到这类 API,直接用它的 LLM 版本即可。

### 5. 会连 API = 可变现的实操能力 [4:08:57](https://youtu.be/MxyRjL7NG18?t=14937)

剥离推销话术后,这里有一条站得住的操作认知:自由职业平台上有大量"一次性 API 对接"需求——某企业在用 X 平台,但 X 没有一键 Zapier 集成,他们不知道怎么连它的 API,觉得又难又吓人。

而如今你甚至不必精通如何手写对接,只需能把"我想连这个 API、发一条测试查询 XYZ"清楚地传达给模型,它就能替你完成。掌握这套读文档 + 粘文档 + 让模型调用的流程,就能接下这类常见、明确、可快速交付的对接活。

## 术语

- API documentation(API 文档,描述某服务可用端点、请求/响应结构与用法的说明页)
- endpoint schema(端点结构,某个 API 端点的入参/返回字段定义)
- JS-rendered docs(JS 渲染文档,页面内容靠 JavaScript 动态生成、静态抓取拿不到)
- copy for LLM(为大模型准备的一键复制按钮,输出 token 高效的 markdown 版文档)
- context budget(上下文预算,模型对话可容纳的有限 token 空间)

## 自检问题

1. 为什么"让模型自己上网读 API 文档"往往是低效且不可靠的?
   **答案**:它约一半时间耗在查文档、一半时间在踩错;遇到 JS 渲染的页面还抓不到端点,只能瞎猜并反复搜索,既不准又持续吃掉上下文预算。见详解1、2。[4:04:11](https://youtu.be/MxyRjL7NG18?t=14651)
2. Nick 推荐的替代做法是什么?为什么它更可靠?
   **答案**:自己打开所需文档页、整段复制粘贴进对话,让模型一次拿全资料。因为"让模型自己搜"是会复合错误概率的额外步骤,直接给全就能第一次做对、不再来回猜端点。见详解3。[4:06:49](https://youtu.be/MxyRjL7NG18?t=14809)
3. 怎样识别一个"为 AI 优化过"的 API 文档?这样的文档好在哪?
   **答案**:看它是否提供 copy for LLM 按钮或 markdown 版(可直接在 ChatGPT/Claude/Perplexity 打开)。markdown 更紧凑、token 高效,模型原生就懂遍历,访问一次即可抓全。见详解4。[4:07:40](https://youtu.be/MxyRjL7NG18?t=14860)