# Claude API 教程：用 Python 和 TypeScript 完成第一次调用 > Claude API 的核心接口只有一个：Messages。你发送模型 id、`max_tokens` 上限和一组消息，拿回内容块、`stop_reason` 和 token 用量。本教程先在控制台创建 API 密钥，再安装 Python 或 TypeScript SDK，完成第一次调用，做流式输出，并读懂返回结果。 Mindket 编辑部 · 发布于 2026-11-04 · 更新于 2026-11-05 · https://mindket.com/cn/learn/claude-api/claude-api-quickstart ## 要点 - 创建 API 密钥，并把它放在 ANTHROPIC_API_KEY 变量里。 - 用 Python 或 TypeScript 发送带系统提示词的 Messages API 请求。 - 读 content 内容块、usage 和 stop_reason，不要默认只有一个文本块。 - 给长回答做流式输出，并知道 SDK 已经替你重试了哪些错误。 ## 开始之前 你需要一个 [Claude Console](https://platform.claude.com/) 账号和一个 API 密钥。在控制台打开 [API keys 页面](https://platform.claude.com/settings/keys)，点 **Create key**，给它起名并选一个过期时间。控制台只会显示一次完整的密钥，它以 `sk-ant-` 开头，所以要马上复制到密钥管理工具里。个人密钥会在你离开组织后失效，所以文档建议共享的工作负载改用服务账号密钥。两种密钥的区别见[Anthropic 的密钥页面](https://platform.claude.com/docs/en/get-api-key)。 SDK 要求 Python 3.10 或更高版本，或者 Node.js 20 LTS 或更高版本，加上 TypeScript 5.0 或更高版本。两个 SDK 默认都从环境变量里读取 `ANTHROPIC_API_KEY`，密钥不会出现在代码里。TypeScript SDK 在浏览器里默认拒绝运行，除非你设置 `dangerouslyAllowBrowser`。这个名字就是警告：能打开页面的人都能读到密钥。 ## 用 Python 完成第一次调用 下面是文档里的快速入门代码，加了一条系统提示词和一行用量输出。模型 id 来自[模型页面](https://platform.claude.com/docs/en/models/overview)，复制之前也请先去那里核对一遍。 ````python import anthropic client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY message = client.messages.create( model="claude-opus-5-5", max_tokens=1000, system="You are a concise assistant. Answer in three bullet points.", messages=[ { "role": "user", "content": "What should I search for to find the latest developments in renewable energy?", } ], ) for block in message.content: if block.type == "text": print(block.text) print(message.stop_reason, message.usage) ```` 1. 在运行脚本的 shell 里导出密钥：`export ANTHROPIC_API_KEY="your-api-key-here"`。 2. 新建项目文件夹和虚拟环境，再安装 SDK：先执行 `python3 -m venv .venv && source .venv/bin/activate`，再执行 `pip install anthropic`。 3. 把上面的代码保存为 `quickstart.py`。 4. 运行 `python quickstart.py`。你会先看到回答文字，再看到一行停止原因和 token 数量。 5. 把 `max_tokens` 改成 20 再运行一次。回答会在句子中间被截断，`stop_reason` 变成 `max_tokens`。 ## 用 TypeScript 做同样的调用 依次运行 `npm init -y`、`npm pkg set type=module` 和 `npm install @anthropic-ai/sdk`，把代码保存为 `quickstart.ts`，再用 `npx tsx quickstart.ts` 启动，快速入门就是这样做的。 TypeScript 沿用 HTTP API 的字段名，所以 `max_tokens` 和 `stop_reason` 都保留下划线。[Messages API 参考](https://platform.claude.com/docs/en/api/messages/create)把 `model`、`max_tokens` 和 `messages` 标为必填字段。 ````typescript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // reads ANTHROPIC_API_KEY const message = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 1000, system: "You are a concise assistant. Answer in three bullet points.", messages: [ { role: "user", content: "What should I search for to find the latest developments in renewable energy?" } ] }); for (const block of message.content) { if (block.type === "text") { console.log(block.text); } } console.log(message.stop_reason, message.usage); ```` ## 读懂返回结果：内容块、用量和 stop_reason `message.content` 是一个内容块列表，不是字符串。普通回答只有一个 `text` 块，但同一个列表里也可能出现 `tool_use` 和 `thinking` 块，所以快速入门的写法是遍历列表，挑出文本块。直接写 `content[0].text`，只能在没出问题的时候用。 `usage` 里有 `input_tokens` 和 `output_tokens`，这是 API 计量的单位，[AI 里的 token 是什么](https://mindket.com/cn/blog/what-are-tokens-in-ai)那篇讲过。Python SDK 还能在发送之前先计数：`client.messages.count_tokens(model=..., messages=[...])` 会返回 `input_tokens`。 `stop_reason` 说明生成为什么结束。每次响应都要检查它，因为只读文本的代码会悄悄返回一个被截断的回答。 | stop_reason | 发生了什么 | 该怎么做 | | --- | --- | --- | | `end_turn` | Claude 自然说完了回答 | 直接使用响应 | | `max_tokens` | 回复达到了你设的 `max_tokens` 上限 | 调高上限，或者让 Claude 接着写 | | `stop_sequence` | Claude 输出了你设定的某个 `stop_sequences` | 读 `stop_sequence` 看是哪一个 | | `tool_use` | Claude 正在调用工具 | 运行工具，再把结果发回去 | | `pause_turn` | 服务端工具循环达到了迭代上限 | 把助手内容原样发回去继续 | | `refusal` | Claude 拒绝回答 | 读 `stop_details`，再换一个备用模型重试 | | `model_context_window_exceeded` | 回复占满了上下文窗口 | 把这次回复当作被截断的 | ## 用流式输出处理长回答 等完整回复出来再显示，体验慢，输出很大时在某些网络上还会失败。SDK 的辅助方法用服务器发送事件发出请求，让你边收边用文字。Python 里的 `get_final_message()`，TypeScript 里的 `finalMessage()`，会返回和普通调用相同的 `Message` 对象。 到了范围的上端，流式输出就不再是可选项。Python SDK 在预计非流式请求要跑上大约十分钟以上时，会抛出 `ValueError`，两个 SDK 都建议对较大的 `max_tokens` 使用流式输出。 ````python import anthropic client = anthropic.Anthropic() with client.messages.stream( max_tokens=1024, messages=[{"role": "user", "content": "Hello"}], model="claude-opus-5-5", ) as stream: for text in stream.text_stream: print(text, end="", flush=True) message = stream.get_final_message() print() print(message.stop_reason, message.usage) ```` - 事件顺序是 `message_start`，然后每个内容块依次有 `content_block_start`、一个或多个 `content_block_delta` 和 `content_block_stop`，最后是 `message_delta` 和 `message_stop`。可能出现未知的事件类型，不处理的就忽略（见[流式输出页面](https://platform.claude.com/docs/en/build-with-claude/streaming)）。 - `stop_reason` 在 `message_start` 里是 null，在 `message_delta` 里才出现。`message_delta` 里的 token 数是累计值。 - API 已经返回 200 之后，仍然可能出现错误。它会以 `error` 事件的形式到达，例如 `overloaded_error`，所以流式循环要有自己的错误分支。 ## 选一个模型 id，并预期它会变 2026 年 11 月 5 日，文档列出四个当前模型。每个 id 都是固定的快照，名字里没有日期，Anthropic 承诺在 Anthropic 自己运营的平台上，每个模型至少保留到表里的日期。[模型总览](https://platform.claude.com/docs/en/models/overview)建议大多数工作负载从 Opus 5.5 开始。 `anthropic-version` 请求头由 SDK 替你发送，新的 API 版本会随着 SDK 的新大版本到来。Python SDK 2.0.0 是第一个使用 `2026-10-21` 的版本，TypeScript SDK 则是 1.0.0。 四个模型在大约五周之内相继发布，最后一个发布两周后，新的 API 版本也来了。八月写的教程里一个都没有，所以[发布说明](https://platform.claude.com/docs/en/release-notes/overview)值得在复制模型 id 之前先翻一下。 > **现在会返回 400 的参数** > > Claude 4.7 及之后的模型不接受 `temperature`、`top_p` 和 `top_k`，在 API 版本 2026-10-21 上，任何取值都会失败。预填充，也就是让请求以一条助手消息结尾、由 Claude 接着写，在 4.6 及之后的模型上同样返回 400。老教程常用这两样，排查别的问题之前，先把它们去掉。 **2026 年 9 月以来的 Claude API 发布** 1. **2026年9月1日** Claude Fable 5.1 发布。面向高难度推理和长周期智能体任务的模型。 2. **2026年9月22日** Claude Opus 5.5 发布。文档建议先试的模型。 3. **2026年9月28日** Claude Sonnet 5.5 发布。产品线的中间档，兼顾速度和智能。 4. **2026年10月7日** Claude Haiku 5.5 发布。面向分类、路由这类高并发工作。 5. **2026年10月21日** API 版本 2026-10-21。随 Python SDK 2.0.0 和 TypeScript SDK 1.0.0 一起发布，它们是最早使用这个版本的 SDK。 6. **2026年11月2日** 消息线程进入 beta。之后的请求可以只带新消息，不必再发整段历史。 来源：[Claude Docs: Release notes](https://platform.claude.com/docs/en/release-notes/overview) (2026-11-05 查阅) | 模型 | API id | 上下文窗口 | 最大输出 | 退役时间 | | --- | --- | --- | --- | --- | | Claude Fable 5.1 | `claude-fable-5-1` | 1M tokens | 128K tokens | 不早于 2027-09-01 | | Claude Opus 5.5 | `claude-opus-5-5` | 1M tokens | 128K tokens | 不早于 2027-09-22 | | Claude Sonnet 5.5 | `claude-sonnet-5-5` | 1M tokens | 128K tokens | 不早于 2027-09-28 | | Claude Haiku 5.5 | `claude-haiku-5-5` | 1M tokens | 128K tokens | 不早于 2027-10-07 | ## 错误、重试与超时 两个 SDK 都会为 4xx 和 5xx 响应抛出带类型的错误，并自动重试其中一部分。[Python SDK 页面](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python)和 [TypeScript SDK 页面](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript)给出了默认值：重试两次，退避时间很短并按指数增长，适用于连接错误、408、409、429 和 5xx，超时时间是十分钟。Python 里用 `max_retries`，TypeScript 里用 `maxRetries` 来修改，并且每次调用都记录 `message._request_id`，联系支持时会被问到。 [错误页面](https://platform.claude.com/docs/en/api/errors)还提到一种重试解决不了的情况：速率限制错误其实表示触到了月度支出上限。它不带 `retry-after` 头，会一直失败到恢复访问为止。 | 状态码 | SDK 类 | API 错误类型 | | --- | --- | --- | | 400 | `BadRequestError` | `invalid_request_error` | | 401 | `AuthenticationError` | `authentication_error` | | 403 | `PermissionDeniedError` | `permission_error` | | 404 | `NotFoundError` | `not_found_error` | | 429 | `RateLimitError` | `rate_limit_error` | | 500 及以上 | `InternalServerError` | `api_error`，529 对应 `overloaded_error` | ## API 版本 2026-10-21 发布当天，ClaudeDevs 说了什么 ClaudeDevs 是 Anthropic 面向开发者的官方账号，新版本发布当天就[在 X 上宣布了它](https://x.com/ClaudeDevs/status/2113013247209021918)。这是 2023 年以来第一个正式的 API 版本。以后版本会发得更勤，好让你在新模型逼你改代码之前，先把不兼容的改动处理掉。旧的 `2023-06-01` 并没有被弃用。 [同一串帖子的下一条](https://x.com/ClaudeDevs/status/2113013248714744208)列出了具体改动，排在最前面的是：Messages API 去掉了 `temperature`、`top_p` 和 `top_k`。助手回合里的文档、用户回合里的引用，现在也会直接报错。 升级到 Python SDK 2.0.0 或 TypeScript SDK 1.0.0 之前，先在代码里搜一遍这三个参数名。没升级之前，你现在的 SDK 会继续发送旧版本号。 > 我们打算更频繁地发布版本，让你在新模型要求之前，就能处理好不兼容的改动。 > > ClaudeDevs, Anthropic 面向 Claude 开发者的官方账号，引文为译文, [X](https://x.com/ClaudeDevs/status/2113013247209021918) (2026-11-05 查阅) [![ClaudeDevs（@ClaudeDevs）2026 年 10 月 21 日在 X 上发帖：API 版本 2026-10-21 现已推出。Claude API 变化很大，但这是 2023 年以来我们第一次正式发布版本。我们打算更频繁地发布版本，让你在新模型要求之前处理好不兼容的改动。2023-06-01 没有被弃用。](https://mindket.com/blog/shots/x-claudedevs-api-version-2026-10-21.webp?v=1107e9f1ff91)](https://x.com/ClaudeDevs/status/2113013247209021918) ClaudeDevs 在 X 上，2026 年 10 月 21 日 [![ClaudeDevs（@ClaudeDevs）同日在同一串帖子里回复：这个版本的改动。Messages API 去掉了 temperature、top_p 和 top_k。助手回合里的文档和用户回合里的引用会返回 400。几个已弃用的 Admin 和 Enterprise Analytics API 字段被替换。](https://mindket.com/blog/shots/x-claudedevs-sampling-removed.webp?v=3e9e4d9e9771)](https://x.com/ClaudeDevs/status/2113013248714744208) ClaudeDevs 在 X 上，2026 年 10 月 21 日 > X 官方嵌入卡片的截图，拍摄于 2026-11-05，时间为 UTC。点击截图可到 X 上打开原帖。 ## 常见错误 - 读 `content[0].text`，哪天第一个块是 thinking 或 tool_use，代码就会出错。 - 只发送最新的一条消息。Messages API 是无状态的，每次请求都要带上完整历史，包括之前的助手回合。 - 从老教程里抄来 `temperature`，结果请求被当前模型拒绝。 - 把密钥放进浏览器代码。启用了零数据保留的组织根本不能从浏览器调用 API，请求会返回 401。 - 不用流式输出就设一个很大的 `max_tokens`，请求超时后又去怪网络。 - 开启缓存之后，把 `usage.input_tokens` 当成全部输入。第 3 课会解释它为什么变小了。 ## 自己试一试 - 加一个回合：把助手的回复和一个追问追加到 `messages`，再调用一次，看 `input_tokens` 怎样增长。 - 设置 `stop_sequences=["END"]`，让 Claude 数到十并以 END 结尾，再读响应里的 `stop_sequence`。 - 导出一个错误的密钥并捕获错误。你得到的是哪个类，状态码是多少？ - 把模型 id 换成 `claude-haiku-5-5`，用同一条提示词，凭感觉比较延迟。 ## 接下来 [第 2 课](https://mindket.com/cn/learn/claude-api/claude-tool-use)让 Claude 调用你写的函数。上面的系统提示词只有一句话，[系统提示词那一课](https://mindket.com/cn/learn/prompt-engineering/system-prompt)教你怎样写一条真正的。 每次调用都要重新发送完整历史，[上下文窗口那一课](https://mindket.com/cn/learn/prompt-engineering/context-window)讲了这笔账怎么算：对话越长，每次请求的输入 token 就越多，离窗口上限也越近。 ## 自测一下 1. 响应里的 stop_reason 是 "max_tokens"，这说明什么？ A. Claude 拒绝了请求 B. 回复达到了你设的 max_tokens 上限，被截断了 C. 某个停止序列匹配上了 D. API 密钥的额度用完了 答案：B。 max_tokens 表示生成在你设定的上限处停了，所以要调高上限，或者让 Claude 接着写。 2. 在调用 API 的脚本里，API 密钥应该放在哪里？ A. 放在 ANTHROPIC_API_KEY 环境变量里 B. 放在第一条用户消息里 C. 放在浏览器端代码里 D. 放在模型 id 里 答案：A。 两个 SDK 默认都读取 ANTHROPIC_API_KEY，密钥就不会出现在代码里，也不会进浏览器。 3. 为什么要遍历 message.content，而不是直接读 content[0]？ A. 第一个块总是空的 B. SDK 会按长度给块排序 C. content 是内容块列表，里面可能有 tool_use 或 thinking D. Python 列表从 1 开始计数 答案：C。 这个列表里可以有好几种块，所以要像快速入门那样挑出文本块。 4. 在当前模型上，设置 temperature 的请求返回 400，该怎么修？ A. 调高 max_tokens B. 换成 TypeScript SDK C. 加一个 beta 请求头 D. 删掉 temperature、top_p 和 top_k，用提示词来引导 答案：D。 Claude 4.7 及之后的模型不接受这些采样参数，API 版本 2026-10-21 对任何取值都会拒绝。 ## 常见问题 ### Claude API 免费吗？ 不免费。用量按 token 计费，文档在定价页面上给出了每个模型每百万 token 的基础价格。价格会变，所以本课没有写具体数字。 ### 什么时候该选 Haiku 或 Fable，而不是 Opus？ Haiku 适合高并发、对延迟敏感的工作，比如分类、信息抽取和路由。Fable 用于要求很高的推理和长周期的智能体任务，或者 Opus 在更高思考强度下评测仍不达标的时候。 ### 为什么设置 temperature 之后请求返回 400？ Claude 4.7 及之后的模型不接受 `temperature`、`top_p` 和 `top_k`，API 版本 2026-10-21 对任何取值都会拒绝。把它们删掉，用提示词来引导行为。 ### 能从浏览器里直接调用 Claude API 吗？ TypeScript SDK 在 `dangerouslyAllowBrowser` 之下允许这样做，但这会把你的密钥暴露给每一位访问者。启用了零数据保留或 Compliance API 的组织根本不能这样做，所以请从你自己的后端调用 API。 ### 能不能不重复发送整段历史？ 只有 beta 阶段可以。Anthropic 文档里的消息线程，之后的请求只发新消息，线程在最后一次请求五分钟后过期。离开这个 beta，就得每次发送全部历史，第 4 课会讲怎样让它保持精简。 ### 一定要用 SDK 吗，用 curl 行不行？ curl 可以。向 `https://api.anthropic.com/v1/messages` 发 POST，带上 `x-api-key`、`anthropic-version` 和 `content-type` 请求头。SDK 多提供了重试、带类型的错误和流式辅助方法。 ## 资料来源 - [Anthropic Docs: Get started with Claude](https://platform.claude.com/docs/en/get-started) (2026-11-04 查阅) - [Anthropic Docs: Get your Claude API key](https://platform.claude.com/docs/en/get-api-key) (2026-11-04 查阅) - [Anthropic Docs: Using the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) (2026-11-04 查阅) - [Anthropic Docs: Messages API reference](https://platform.claude.com/docs/en/api/messages/create) (2026-11-04 查阅) - [Anthropic Docs: Streaming messages](https://platform.claude.com/docs/en/build-with-claude/streaming) (2026-11-04 查阅) - [Anthropic Docs: Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons) (2026-11-04 查阅) - [Anthropic Docs: Models overview](https://platform.claude.com/docs/en/models/overview) (2026-11-05 查阅) - [Anthropic Docs: Claude API errors](https://platform.claude.com/docs/en/api/errors) (2026-11-04 查阅) - [Anthropic Docs: Python SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python) (2026-11-04 查阅) - [Anthropic Docs: TypeScript SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript) (2026-11-04 查阅) - [GitHub: anthropics/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python) (2026-11-04 查阅) - [GitHub: anthropics/anthropic-sdk-typescript](https://github.com/anthropics/anthropic-sdk-typescript) (2026-11-04 查阅) - [Claude Docs: Release notes](https://platform.claude.com/docs/en/release-notes/overview) (2026-11-05 查阅) - [X: ClaudeDevs announces API version 2026-10-21](https://x.com/ClaudeDevs/status/2113013247209021918) (2026-11-05 查阅) - [X: ClaudeDevs lists what changes in API version 2026-10-21](https://x.com/ClaudeDevs/status/2113013248714744208) (2026-11-05 查阅) [浏览 AI 智能体](https://mindket.com/cn/agents)