1. 先说结论调用 Claude Sonnet 到底要准备什么如果你想在自己的脚本、网站后端、企业应用或者一些自动化工具里完成Claude Sonnet 调用其实准备工作并不复杂。通常来说先把下面几样东西准备好就够了第一需要一个可用的 API Key第二要确认当前还能正常使用的 Claude Sonnet 模型名另外还需要 Python、Node.js 或其他服务端运行环境再就是准备一段符合 Claude Messages API 格式的请求代码。这篇文章会按Claude API 教程的思路来讲API Key 怎么获取和管理/v1/messages的请求结构怎么看如何用 curl、Python、Node.js 调用 Claude Sonnet以及多轮对话、流式输出、JSON 返回、常见错误排查和成本控制这些实际开发中经常会遇到的问题。这里先说明一点ClaudeAPI 是第三方 Claude API 兼容接入服务平台并不是 Anthropic 官方平台。如果你用的是 ClaudeAPI那请求地址、模型名、鉴权方式和计费规则都应该以它官网的最新说明为准。本文主要讲 Anthropic 官方 Claude API 的原生调用逻辑同时也会顺带说明第三方兼容接入时容易搞混的地方。2. Claude API、Claude Sonnet、ClaudeAPI 分别是什么Claude API可以理解为 Anthropic 提供给开发者的模型调用接口。你不需要只在网页里手动和 Claude 聊天而是可以在程序里直接向 Claude 模型发送请求。比如客服机器人、代码助手、文档摘要、知识库问答、信息抽取或者更复杂一点的 Agent 工作流都可以用这种方式接入。Claude Sonnet是 Claude 模型家族里比较均衡的一类模型。简单来说Opus更偏向复杂推理和高价值任务Sonnet在能力、速度和成本之间比较平衡很多生产场景都适合用它Haiku更快、更轻量适合高并发、低成本、任务相对简单的场景。至于ClaudeAPI它是第三方 Claude API 兼容接入服务平台。它通常更面向那些希望降低接入门槛、需要中文支持、多线路选择、企业充值或开票的用户。需要注意的是它和 Anthropic 官方 API 不是同一个主体接口细节也可能不完全一样所以具体用法还是要看 ClaudeAPI 平台自己的文档。3. 该选哪种接入方式官方 API、云厂商还是 ClaudeAPI你在不同文章里看到的请求地址和示例代码可能完全不一样这并不奇怪原因通常是接入方式不同。接入方式适合人群优点注意事项Anthropic 官方 Claude API有官方账号、海外支付和合规需求的开发者官方接口、文档完整、模型信息比较透明注册、支付和网络环境可能有一定门槛Amazon BedrockAWS 企业用户方便接入 AWS 权限、日志和网络体系模型标识和鉴权方式不同Google Vertex AI / Agent PlatformGoogle Cloud 用户适合云上应用和企业工作流不是 Anthropic 官方 API 格式ClaudeAPI 等第三方兼容平台个人测试、中文支持、企业充值等场景接入门槛相对低也可能提供基础技术协助要关注隐私、合规、稳定性、模型版本和计费透明度本文主要使用 Anthropic 官方 Messages APIhttps://api.anthropic.com/v1/messages。如果你使用的是 ClaudeAPI那么就把请求地址、Key 和模型名替换成平台提供的对应信息。4. 获取 Claude API Key从 Console 到环境变量如果使用官方 Claude API一般需要先在 Anthropic Console 中创建 API Key。Key 创建后通常只会完整展示一次所以最好马上保存到安全的位置。不要把 Key 直接写死在代码里更不要提交到 GitHub也不要放在前端页面中。更稳妥的做法是使用环境变量。Linux / macOSexport ANTHROPIC_API_KEY你的_API_Key export CLAUDE_MODEL当前可用的 Claude Sonnet 模型名Windows PowerShell$env:ANTHROPIC_API_KEY你的_API_Key $env:CLAUDE_MODEL当前可用的 Claude Sonnet 模型名如果你习惯使用.env文件可以这样写ANTHROPIC_API_KEY你的_API_Key CLAUDE_MODEL当前可用的 Claude Sonnet 模型名同时别忘了在.gitignore里加上.env一旦 API Key 泄露别犹豫马上去控制台删除旧 Key然后重新生成新的 Key。5. 最小可用示例先用 curl 调用 Claude Sonnet正式写代码之前建议先用 curl 测一下 Key、网络和模型名是否都能正常工作。curl https://api.anthropic.com/v1/messages \ --header x-api-key: $ANTHROPIC_API_KEY \ --header anthropic-version: 2023-06-01 \ --header content-type: application/json \ --data { \model\: \$CLAUDE_MODEL\, \max_tokens\: 1024, \messages\: [ { \role\: \user\, \content\: \请用三句话介绍 Claude Sonnet。\ } ] }官方 Claude API 有几个地方很容易写错鉴权头是x-api-key不是Authorization: Bearer请求里需要带上anthropic-version原生接口是/v1/messages不是 OpenAI 风格的/v1/chat/completionssystem通常是顶层字段不是放在messages里的role: system。返回结果里文本内容一般在content[0].textToken 用量一般在usage.input_tokens usage.output_tokens6. 用 Python SDK 调用 Claude Sonnet先安装依赖pip install anthropic python-dotenv然后可以写一个最小示例import os from dotenv import load_dotenv from anthropic import Anthropic load_dotenv() client Anthropic(api_keyos.environ[ANTHROPIC_API_KEY]) MODEL_NAME os.getenv(CLAUDE_MODEL) if not MODEL_NAME: raise RuntimeError(请设置 CLAUDE_MODEL 为当前可用的 Claude Sonnet 模型名) try: message client.messages.create( modelMODEL_NAME, max_tokens1024, temperature0.3, system你是一个严谨的中文技术助手回答要简洁、准确。, messages[ { role: user, content: 请解释 Claude API 和 Claude 网页版的区别。 } ], ) print(message.content[0].text) print(input_tokens:, message.usage.input_tokens) print(output_tokens:, message.usage.output_tokens) except Exception as e: print(调用失败, repr(e))这段代码已经能覆盖不少常见场景比如 Python 后端、脚本任务和数据处理流程。这里要特别注意max_tokens指的是最大输出长度不是整个上下文的总长度。7. 用 Python requests 直接发 HTTP 请求如果你想更清楚地理解底层请求长什么样也可以不用 SDK直接用requests发 HTTP 请求。pip install requests python-dotenvimport os import requests from dotenv import load_dotenv load_dotenv() api_key os.environ[ANTHROPIC_API_KEY] model os.environ[CLAUDE_MODEL] url https://api.anthropic.com/v1/messages headers { x-api-key: api_key, anthropic-version: 2023-06-01, content-type: application/json, } payload { model: model, max_tokens: 800, temperature: 0.2, system: 你是一个代码审查助手只指出关键问题和修改建议。, messages: [ { role: user, content: 请审查这段 Python 代码print(hello) } ], } resp requests.post(url, headersheaders, jsonpayload, timeout60) if resp.status_code ! 200: print(HTTP 状态码, resp.status_code) print(resp.text) raise SystemExit(1) data resp.json() print(data[content][0][text]) print(data.get(usage, {}))如果你使用的是 ClaudeAPI 这类第三方兼容平台那这里的url、鉴权头或者模型名都可能需要替换具体还是以平台文档为准。8. 用 Node.js / TypeScript 调用 Claude Sonnet先安装 SDKnpm install anthropic-ai/sdk dotenv示例代码如下import dotenv/config; import Anthropic from anthropic-ai/sdk; const client new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, }); const model process.env.CLAUDE_MODEL; if (!model) { throw new Error(请设置 CLAUDE_MODEL); } async function main() { const msg await client.messages.create({ model, max_tokens: 1024, temperature: 0.3, system: 你是一个中文技术写作助手回答要有条理。, messages: [ { role: user, content: 写一个 Claude Sonnet 调用的应用场景列表。, }, ], }); const block msg.content[0]; if (block.type text) { console.log(block.text); } console.log(msg.usage); } main().catch(console.error);Node.js 很适合接入 Web 服务、聊天应用、企业内部工具或者前后端一体的项目。但有一点必须注意不要在浏览器前端直接暴露 API Key最好通过服务端代理来调用。9. 关键参数应该怎么设置常用参数大致如下参数作用建议model指定模型使用当前可用的 Claude Sonnet 官方模型名第三方平台的模型名可能不同max_tokens最大输出 token摘要、问答可以小一点长文生成可以适当调大temperature控制随机性代码、事实类任务用 0-0.2普通写作用 0.3-0.7创意任务可以更高system设定角色、边界和输出要求放在顶层字段不要写成 OpenAI 风格的 system rolemessages对话内容通常放user和assistant等对话消息stop_sequences指定停止输出标记适合模板化生成场景stream流式返回适合聊天界面和命令行实时输出模型名变化比较快所以示例里的模型名不要当成永久固定值。新项目开始前最好去 Anthropic 官方模型列表、Console或者你使用的接入平台里确认一下。10. 多轮对话怎么做Claude API 默认是无状态的。也就是说它不会自动记住上一轮聊了什么。每次请求时你都需要自己把历史messages带上。messages [ {role: user, content: 我想做一个文档摘要工具。}, {role: assistant, content: 可以文档摘要工具通常包括上传、切分、摘要和汇总。}, {role: user, content: 如果文档很长应该怎么处理} ] response client.messages.create( modelMODEL_NAME, max_tokens1000, messagesmessages, )但也不要把历史无限追加进去。历史越长输入 token 越多成本和响应延迟都会上升。比较常见的做法是只保留最近几轮对话把早期对话压缩成摘要长文档先分块处理再统一汇总同时记录每次响应里的usage看看 token 消耗是否合理。11. 流式输出让 Claude 像聊天一样返回流式输出不一定会让调用更便宜但它能明显改善用户体验。对聊天机器人、Web 应用和命令行工具来说这一点很实用。Python SDK 示例with client.messages.stream( modelMODEL_NAME, max_tokens1024, messages[ {role: user, content: 请写一段关于 Claude API 教程的开头。} ], ) as stream: for text in stream.text_stream: print(text, end, flushTrue)Node.js 示例const stream await client.messages.stream({ model: process.env.CLAUDE_MODEL!, max_tokens: 1024, messages: [ { role: user, content: 请用列表介绍 Claude Sonnet 的优势。 } ], }); for await (const text of stream.textStream) { process.stdout.write(text); }如果放到生产环境里还要处理用户中途断开、请求超时、服务端错误以及部分输出如何保存这些问题。12. 让 Claude Sonnet 返回 JSON结构化输出怎么做很多业务系统都需要结构化结果比如信息抽取、标签分类、简历解析等。这个时候可以通过system和提示词把输出格式约束清楚。import json prompt 请从下面文本中抽取信息只返回 JSON不要输出解释。 JSON 格式 { name: 姓名, skills: [技能1, 技能2], years: 数字 } 文本张三Python 后端工程师有 5 年 Django 和 FastAPI 经验。 resp client.messages.create( modelMODEL_NAME, max_tokens500, temperature0, system你是一个信息抽取助手。必须只返回合法 JSON。, messages[{role: user, content: prompt}], ) text resp.content[0].text try: data json.loads(text) print(data) except json.JSONDecodeError: print(JSON 解析失败需要重试或进入人工兜底) print(text)不过不能因为模型说“只返回 JSON”就完全信任它。后端还是要做 JSON 解析、字段校验、类型校验和异常兜底这样系统才更稳。13. 常见错误排查401、403、404、429、400 怎么处理错误类型常见原因解决方法401 authentication_errorAPI Key 错误或者缺少x-api-key检查环境变量、请求头和 Key 是否失效403 permission_error账号无权限、支付或地区限制、模型不可用检查账号状态、模型权限和平台规则404 not_found_errorURL 错误或模型名错误核对/v1/messages和当前可用模型名400 invalid_request_errorJSON 格式错误、messages 结构错误、参数非法检查请求体、max_tokens和system位置429 rate_limit_error请求太频繁降低并发加入指数退避重试500 / 529服务端繁忙或过载稍后重试并设置重试上限timeout网络问题或响应过慢设置超时和重试检查网络链路SDK 报错SDK 版本旧或者响应字段读取方式不对升级 SDK并判断contentblock 类型排错时建议先看四个关键点API Key、请求地址、模型名和请求体结构。很多问题其实都出在这几个地方。14. 成本与 token 控制怎样避免费用失控Claude API 通常按输入 token 和输出 token 计费。你传入的 prompt、历史对话、文档内容都算输入模型生成出来的内容则算输出。想降低成本可以从几个方面入手。比如不要把完整历史无限追加到messages长文档先分块再做汇总对早期对话做摘要压缩简单分类、短问答、轻量改写可以考虑更轻量的模型真正高价值、复杂的任务再使用 Sonnet 或 Opus。另外max_tokens要设置得合理不要动不动给一个很大的值。每次响应里的usage也建议记录下来方便后续分析成本。还有一点容易被忽略失败重试也会消耗 token所以重试次数一定要有上限。流式输出只是让体验更顺滑并不代表一定更省钱。15. Claude Sonnet 适合哪些场景又不太适合哪些场景Claude Sonnet 比较适合这些任务代码生成、代码解释和代码审查长文档总结以及多文档对比中文技术写作和内容润色结构化信息抽取企业知识库问答Agent 工作流里的规划、分析和工具调用环节。但它也不是所有场景都最合适。比如极低成本、高并发的简单分类任务对毫秒级延迟非常敏感的小任务不允许数据出境或第三方处理的敏感数据场景或者没有输出校验却要拿结果做关键决策的系统都需要谨慎使用。还有一些只需要简单规则判断的业务逻辑其实没必要上大模型。如果你用的是 ClaudeAPI 这类第三方兼容接入服务还要额外评估数据隐私、合规要求、模型版本透明度、限速规则和计费方式。16. 总结新手调用 Claude Sonnet 的推荐路径如果你是从零开始做 Claude Sonnet 调用可以按这个顺序来先确认接入方式是用官方 Claude API、云厂商还是 ClaudeAPI 这类第三方平台然后获取 API Key并用环境变量管理起来接下来用 curl 测试 Key、网络和模型名是否正常再用 Python SDK 跑通一个最小示例。在这个基础上再去理解/v1/messages的请求头、请求体和响应结构。等基础调用稳定后就可以逐步加入多轮对话、system prompt 和流式输出。如果业务里需要 JSON 输出也要做好解析和校验。最后再补上错误处理、日志记录、重试机制和 token 成本统计。这样做出来的 Claude API 集成就不只是一个 Hello World而是更接近真实项目里能稳定使用的调用方案。