如何将 Claude API 集成到你的应用中

要集成 Claude API，请先在 Anthropic 的 Claude Console 中创建 API 密钥，把它保存为服务端机密（通常是 ANTHROPIC_API_KEY），然后使用 Anthropic 官方 SDK 之一，在你自己服务器上的路由中调用 Messages API。每个请求都需要指定一个模型，设置 max_tokens（你愿意接受的最长回复），并以 messages 的形式发送对话内容，而你的指令则放在单独的 system 系统提示词中。设置消费上限，对较长的回复使用流式输出，并通过重试来处理速率限制（429）和过载（529）错误。

本指南涵盖设置步骤、安全的请求流程、为 AI 构建器编写的提示词，以及需要提前规划的错误。Anthropic 的相关细节取自其截至2026年9月的官方文档。关于 Token 和定价的一般原理，请参阅如何使用 LLM API。

你能用它构建什么

• 聊天助手和帮助小组件（如何构建 AI 聊天机器人应用）
• 摘要、改写和起草回复
• 从文档、邮件和表单中提取字段
• 基于你自己的内容回答问题
• 通过工具调用（tool use）调用你应用中函数的智能体

更多想法请参阅如何为你的应用添加 AI 功能。

Messages API 简介

根据 Anthropic 的 API 参考文档，一个请求是向 https://api.anthropic.com/v1/messages 发出的 POST 请求，包含：

API 是无状态的：要延续对话，每次请求都需要重新发送之前的轮次。这就是为什么长对话每条消息的成本更高。

Anthropic 为 Python、TypeScript、C#、Go、Java、PHP 和 Ruby 提供官方 SDK。它们会设置请求头、解析响应，并支持流式输出。除非有特殊理由，否则请优先使用 SDK，而不是原始 HTTP 请求。

选择模型

Anthropic 提供多款 Claude 模型，它们在能力、速度和价格之间各有取舍，而且产品线会不断变化。请选择能很好完成你任务的最小模型，用真实示例进行测试，并把模型 ID 保存在配置中，这样无需修改代码即可切换。请查看 Anthropic 的模型与定价页面，以了解当前可用的选项和费率。

设置你的账户

1. 登录 Claude Console，地址为 platform.claude.com，并添加计费信息。
2. 创建 API 密钥。 测试环境和生产环境各使用一个密钥，这样撤销其中一个时，不会影响另一个。
3. 设置消费上限。 Anthropic 的错误页面指出，当用量达到你设置的消费上限时，API 会返回 400 错误，因此你的应用应该向用户显示清晰的提示。
4. 查看速率限制。 你可以在 Console 中查看账户的速率限制；这些限制是按组织计算的。

请求流程

1. 用户在你的应用中操作：发送消息，或点击“总结”。
2. 浏览器调用的是你自己的服务端路由，而绝不是直接调用 Anthropic。
3. 你的服务器检查用户是否已登录、是否有权使用该功能，并应用针对每位用户的限额。
4. 服务器构建请求：包含你规则的系统提示词、用户的输入，以及任务所需的数据库数据。
5. 服务器使用环境变量中的密钥，并设置合理的 max_tokens，调用 Messages API。
6. 服务器将回复以流式方式传回浏览器，并记录响应中的 Token 用量。

选项与取舍

给 AI 构建器的提示词

第一个功能：

添加一个“询问这份文档”面板。它调用服务端路由 POST /api/ask，该路由检查用户已登录且拥有该文档，然后使用官方 Anthropic SDK 和机密 ANTHROPIC_API_KEY 调用 Claude Messages API。从机密 CLAUDE_MODEL 读取模型 ID。系统提示词：“只根据提供的文档作答。如果答案不在其中，请直说。”发送文档文本和问题，将 max_tokens 设为 800，把答案流式输出到页面，并且绝不向浏览器暴露密钥。

防护与错误处理：

限制每位用户每小时最多 20 个问题，记录在数据库中。记录每次响应的输入和输出 Token，并附上用户 ID 和请求 ID。遇到 429 或 529 错误时，使用指数退避最多重试 3 次，并遵守任何 retry-after 请求头；之后显示“助手正忙，请稍后再试”。如果 API 报告消费上限错误，则显示“AI 功能已暂停”，并通知管理员。

需要预防的错误

以下内容来自 Anthropic 的错误文档，是你的应用实际会遇到的错误：

Anthropic 的文档说明，官方 SDK 默认会自动对暂时性失败（连接错误、速率限制和 5xx 错误）进行两次指数退避重试，并且你可以对此进行配置。每个响应都带有 request-id 请求头；请记录它，以便支持团队追踪问题。

常见错误

• 从浏览器调用 API。 你的密钥会因此公开。务必通过你自己的服务器。参见如何安全保管 API 密钥。
• 忘记 max_tokens 是上限，而不是目标值。 将它设为该功能所需的数值；过低会截断回答，过高则可能产生冗长且昂贵的回复。
• 把规则放在用户消息中。 稳定的指令应放在 system 系统提示词中；权限控制应放在你的代码里。
• 永远发送整个聊天记录。 随着对话变长，应裁剪或总结较早的轮次。
• 没有消费上限或针对每位用户的限额。
• 硬编码模型 ID。 模型会更新，也会退役。
• 忽略停止原因。 如果回复是因为达到 max_tokens 而停止的，请告知用户，或提高上限。

检查清单

• 已在 Claude Console 中创建 API 密钥，并保存为服务端机密
• 测试和生产环境使用不同的密钥
• 已设置消费上限，并在达到上限时显示清晰的提示
• 所有请求都经过你的服务器，并进行权限检查
• 系统提示词包含规则；模型 ID 可配置
• 每个功能都设置了 max_tokens；较长的回复采用流式输出
• 应用内有针对每位用户的速率限制
• 429 和 529 错误已通过退避处理；请求 ID 已记录
• 有友好的错误状态，且不会破坏页面
• 已用空输入、超长输入和恶意输入进行测试

在 Mythex 中使用 Claude API

在你使用 Mythex 构建的应用中，Claude 功能使用你自己的 Anthropic 密钥，费用计入你的 Anthropic 账户，而不是 Mythex 的构建积分。请通过 /secrets、项目设置或聊天中的机密卡片，将 ANTHROPIC_API_KEY 添加为项目机密，然后用类似上述的提示词描述该功能。在已发布的应用中更改机密后，请重新发布。入门提示词请参阅使用你自己的 API 密钥添加 AI 功能。如果你正在比较不同的服务商，如何集成 OpenAI API也涵盖了相同的内容，只是针对 OpenAI。

常见问题