Claude API 教程：用 Python 和 TypeScript 完成第一次调用

开始之前

你需要一个 Claude Console 账号和一个 API 密钥。在控制台打开 API keys 页面，点 Create key，给它起名并选一个过期时间。控制台只会显示一次完整的密钥，它以 sk-ant- 开头，所以要马上复制到密钥管理工具里。个人密钥会在你离开组织后失效，所以文档建议共享的工作负载改用服务账号密钥。两种密钥的区别见Anthropic 的密钥页面。

SDK 要求 Python 3.10 或更高版本，或者 Node.js 20 LTS 或更高版本，加上 TypeScript 5.0 或更高版本。两个 SDK 默认都从环境变量里读取 ANTHROPIC_API_KEY，密钥不会出现在代码里。TypeScript SDK 在浏览器里默认拒绝运行，除非你设置 dangerouslyAllowBrowser。这个名字就是警告：能打开页面的人都能读到密钥。

用 Python 完成第一次调用

下面是文档里的快速入门代码，加了一条系统提示词和一行用量输出。模型 id 来自模型页面，复制之前也请先去那里核对一遍。

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 参考把 model、max_tokens 和 messages 标为必填字段。

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 是什么那篇讲过。Python SDK 还能在发送之前先计数：client.messages.count_tokens(model=..., messages=[...]) 会返回 input_tokens。

stop_reason 说明生成为什么结束。每次响应都要检查它，因为只读文本的代码会悄悄返回一个被截断的回答。

用流式输出处理长回答

等完整回复出来再显示，体验慢，输出很大时在某些网络上还会失败。SDK 的辅助方法用服务器发送事件发出请求，让你边收边用文字。Python 里的 get_final_message()，TypeScript 里的 finalMessage()，会返回和普通调用相同的 Message 对象。

到了范围的上端，流式输出就不再是可选项。Python SDK 在预计非流式请求要跑上大约十分钟以上时，会抛出 ValueError，两个 SDK 都建议对较大的 max_tokens 使用流式输出。

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。可能出现未知的事件类型，不处理的就忽略（见流式输出页面）。
• stop_reason 在 message_start 里是 null，在 message_delta 里才出现。message_delta 里的 token 数是累计值。
• API 已经返回 200 之后，仍然可能出现错误。它会以 error 事件的形式到达，例如 overloaded_error，所以流式循环要有自己的错误分支。

选一个模型 id，并预期它会变

2026 年 11 月 5 日，文档列出四个当前模型。每个 id 都是固定的快照，名字里没有日期，Anthropic 承诺在 Anthropic 自己运营的平台上，每个模型至少保留到表里的日期。模型总览建议大多数工作负载从 Opus 5.5 开始。

anthropic-version 请求头由 SDK 替你发送，新的 API 版本会随着 SDK 的新大版本到来。Python SDK 2.0.0 是第一个使用 2026-10-21 的版本，TypeScript SDK 则是 1.0.0。

四个模型在大约五周之内相继发布，最后一个发布两周后，新的 API 版本也来了。八月写的教程里一个都没有，所以发布说明值得在复制模型 id 之前先翻一下。

错误、重试与超时

两个 SDK 都会为 4xx 和 5xx 响应抛出带类型的错误，并自动重试其中一部分。Python SDK 页面和 TypeScript SDK 页面给出了默认值：重试两次，退避时间很短并按指数增长，适用于连接错误、408、409、429 和 5xx，超时时间是十分钟。Python 里用 max_retries，TypeScript 里用 maxRetries 来修改，并且每次调用都记录 message._request_id，联系支持时会被问到。

错误页面还提到一种重试解决不了的情况：速率限制错误其实表示触到了月度支出上限。它不带 retry-after 头，会一直失败到恢复访问为止。

API 版本 2026-10-21 发布当天，ClaudeDevs 说了什么

ClaudeDevs 是 Anthropic 面向开发者的官方账号，新版本发布当天就在 X 上宣布了它。这是 2023 年以来第一个正式的 API 版本。以后版本会发得更勤，好让你在新模型逼你改代码之前，先把不兼容的改动处理掉。旧的 2023-06-01 并没有被弃用。

同一串帖子的下一条列出了具体改动，排在最前面的是：Messages API 去掉了 temperature、top_p 和 top_k。助手回合里的文档、用户回合里的引用，现在也会直接报错。

升级到 Python SDK 2.0.0 或 TypeScript SDK 1.0.0 之前，先在代码里搜一遍这三个参数名。没升级之前，你现在的 SDK 会继续发送旧版本号。

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 课让 Claude 调用你写的函数。上面的系统提示词只有一句话，系统提示词那一课教你怎样写一条真正的。

每次调用都要重新发送完整历史，上下文窗口那一课讲了这笔账怎么算：对话越长，每次请求的输入 token 就越多，离窗口上限也越近。

常见问题

资料来源

1. Anthropic Docs: Get started with Claude (2026年11月4日 查阅)https://platform.claude.com/docs/en/get-started
2. Anthropic Docs: Get your Claude API key (2026年11月4日 查阅)https://platform.claude.com/docs/en/get-api-key
3. Anthropic Docs: Using the Messages API (2026年11月4日 查阅)https://platform.claude.com/docs/en/build-with-claude/working-with-messages
4. Anthropic Docs: Messages API reference (2026年11月4日 查阅)https://platform.claude.com/docs/en/api/messages/create
5. Anthropic Docs: Streaming messages (2026年11月4日 查阅)https://platform.claude.com/docs/en/build-with-claude/streaming
6. Anthropic Docs: Stop reasons and fallback (2026年11月4日 查阅)https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
7. Anthropic Docs: Models overview (2026年11月5日 查阅)https://platform.claude.com/docs/en/models/overview
8. Anthropic Docs: Claude API errors (2026年11月4日 查阅)https://platform.claude.com/docs/en/api/errors
9. Anthropic Docs: Python SDK (2026年11月4日 查阅)https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python
10. Anthropic Docs: TypeScript SDK (2026年11月4日 查阅)https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript
11. GitHub: anthropics/anthropic-sdk-python (2026年11月4日 查阅)https://github.com/anthropics/anthropic-sdk-python
12. GitHub: anthropics/anthropic-sdk-typescript (2026年11月4日 查阅)https://github.com/anthropics/anthropic-sdk-typescript
13. Claude Docs: Release notes (2026年11月5日 查阅)https://platform.claude.com/docs/en/release-notes/overview
14. X: ClaudeDevs announces API version 2026-10-21 (2026年11月5日 查阅)https://x.com/ClaudeDevs/status/2113013247209021918
15. X: ClaudeDevs lists what changes in API version 2026-10-21 (2026年11月5日 查阅)https://x.com/ClaudeDevs/status/2113013248714744208