人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载本指南系统讲解 claude-api Skill 中 curl/examples.md 所记载的 Claude API 原始 HTTP 调用方法当你需要发送裸 HTTP 请求、工作在 Shell/cURL 环境或使用的语言没有官方 SDK 时如何直接向POST /v1/messages发起请求完成基础对话、流式SSE、工具调用、提示缓存、扩展思考与拒绝回退等全部核心场景。读完本文你将掌握一套可复制、可运行的 cURL 命令集能够用jq正确解析响应、在无 SDK 环境中独立构建 Claude 应用并理解各请求头与参数的底层语义。何时应该选择 cURL / 原始 HTTPclaude-api Skill 的 SKILL.md 明确规定了一条选型原则默认情况下应使用官方 Anthropic SDKanthropic、anthropic-ai/sdk、com.anthropic.*等只有在以下场景才切换到原始 HTTP用户明确要求使用 cURL / REST / 原始 HTTP项目本身就是 Shell / cURL 项目项目所用语言没有官方 SDK例如 Rust、Swift、C、Elixir 等。同时该文档强调不要混用两种方式——不要在 Python 或 TypeScript 项目中为了看起来更轻而改用requests/fetch也不要退回 OpenAI 兼容的 shim 层。对于没有官方 SDK 的语言Skill 的建议正是从curl/目录获取 cURL / 原始 HTTP 示例。除此之外还需要留意 SKILL.md 的API Drift警告2025–2026 年间 Claude API 的若干常见形态已经变化例如扩展思考从thinking: {type: enabled, budget_tokens: N}演变为thinking: {type: adaptive}因此本文所有示例均以当前文档与源码为准模型 ID 默认使用claude-opus-5。环境准备API 密钥与认证方式最基础的认证方式是设置环境变量来自 curl/examples.mdexport ANTHROPIC_API_KEYyour-api-key需要说明的是ANTHROPIC_API_KEY未设置并不意味着没有凭据。根据 SKILL.md 的认证章节SDK 与antCLI 解析凭据的顺序是先匹配者胜出ANTHROPIC_API_KEY→ANTHROPIC_AUTH_TOKEN→ 由ANTHROPIC_PROFILE选择或当前激活的 OAuth 配置文件 → Workload Identity Federation 环境变量 → 磁盘上的默认配置文件。在原始 cURL 场景下如果环境变量未设置但ant auth status显示有激活的配置文件可以这样获取短时令牌# 获取一次性 access token并通过 Authorization: Bearer 发送 ant auth print-credentials --access-token curl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H Authorization: Bearer token \ -H anthropic-version: 2023-06-01 \ -H anthropic-beta: oauth-2025-04-20 \ -d {...}注意两点OAuth 令牌走Authorization: Bearer而不是x-api-key:且必须附带anthropic-beta: oauth-2025-04-20头——把使用 API key 的 curl 改成 OAuth 是一个换头操作而非换 key操作。仅当ant auth status报告没有任何激活的凭据源时才需要向用户索取 key。必填请求头四个头的含义无论请求体如何变化以下四个请求头是每次调用 Messages API 的基础源自 curl/examples.md 的 Required Headers 表格HeaderValue说明Content-Typeapplication/json必填声明 JSON 请求体x-api-key你的 API key认证anthropic-version2023-06-01API 版本anthropic-betaBeta 功能 ID 列表使用 Beta 功能时必填anthropic-beta是可选但关键的开启 Beta 功能如拒绝回退、快速模式、Managed Agents时必须携带对应的 Beta ID且某些功能例如本文后面介绍的server-side-fallback-2026-06-01对头值有严格校验写错会直接返回 400。基础消息请求第一次调用 Messages API最小可用的请求体来自 curl/examples.md 的 Basic Message Requestcurl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 16000, messages: [ {role: user, content: What is the capital of France?} ] }请求体字段说明model模型 ID。当前仓库 SKILL.md 的模型表中默认推荐claude-opus-5除非用户明确指定其他模型上下文窗口 1M。其余可用 ID 包括claude-fable-5-1、claude-sonnet-5、claude-opus-4-8等必须使用表中精确的 ID 字符串不要自行拼接日期后缀。max_tokens输出 token 上限。Skill 的建议是非流式请求默认约16000避免响应超出 SDK/HTTP 超时流式请求默认约64000无超时顾虑给模型留足空间。只有明确原因分类任务约256、成本上限、刻意短输出或预热缓存时用0才调低。messages对话历史数组每个元素包含roleuser/assistant与content。从架构上看SKILL.md 明确指出所有能力都通过POST /v1/messages这一个端点暴露——工具、结构化输出、思考等都是该端点的特性而不是独立的 API。用 jq 解析响应为什么不能用 grep/sed响应是 JSONcurl/examples.md 明确要求用jq提取字段不要用grep/sed——JSON 字符串可以包含任意字符正则解析会在引号、转义符或多行内容上出错。标准模式是先把响应捕获到变量再逐字段提取# 捕获响应然后提取字段 response$(curl -s https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d {model:claude-opus-5,max_tokens:16000,messages:[{role:user,content:Hello}]}) # 打印第一个文本块-r 去除 JSON 引号 echo $response | jq -r .content[0].text # 读取用量字段 input_tokens$(echo $response | jq -r .usage.input_tokens) output_tokens$(echo $response | jq -r .usage.output_tokens) # 读取停止原因用于工具调用循环 stop_reason$(echo $response | jq -r .stop_reason) # 提取所有文本块content 是数组过滤 typetext echo $response | jq -r .content[] | select(.type text) | .text这几个 jq 模式对应不同的实战需求content[0].text取首个文本块usage.input_tokens/usage.output_tokens用于记账与成本分析stop_reason用于判断对话是否以end_turn正常结束、以tool_use请求调用工具或以max_tokens被截断select(.type text)则适合在包含工具调用、思考块等混合类型的内容数组中稳健地只取文本。流式响应SSE实时输出与事件序列长输入、长输出或高max_tokens的请求应默认使用流式以避免触发请求超时这是 SKILL.md 的默认建议。流式请求只需在请求体中加stream: truecurl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 64000, stream: true, messages: [{role: user, content: Write a haiku}] }响应是一串 Server-Sent EventsSSE事件流顺序如下来自 curl/examples.mdevent: message_start data: {type:message_start,message:{id:msg_...,type:message,...}} event: content_block_start data: {type:content_block_start,index:0,content_block:{type:text,text:}} event: content_block_delta data: {type:content_block_delta,index:0,delta:{type:text_delta,text:Hello}} event: content_block_stop data: {type:content_block_stop,index:0} event: message_delta data: {type:message_delta,delta:{stop_reason:end_turn},usage:{output_tokens:12}} event: message_stop data: {type:message_stop}理解这个序列对构建聊天 UI 至关重要message_start携带消息元数据含idcontent_block_start标志一个新内容块开始index标识块序号content_block_delta是实际增量文本text_delta需要持续累积content_block_stop表示该内容块结束message_delta携带本次的stop_reason与增量usagemessage_stop是流的终结标志。对工具调用场景内容块类型会是tool_use增量类型对应input_json_delta客户端需要按index逐块累积 JSON 片段。工具调用定义工具与回传结果工具调用是构建 Agent 的基础能力。curl/examples.md 展示了完整的两步流程。第一步在请求体的tools数组中声明工具JSON Schema 描述输入curl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 16000, tools: [{ name: get_weather, description: Get current weather for a location, input_schema: { type: object, properties: { location: {type: string, description: City name} }, required: [location] } }], messages: [{role: user, content: What is the weather in Paris?}] }第二步当 Claude 以tool_use内容块携带id、name、input回应时把工具执行结果以tool_result形式回传形成一次完整的工具调用往返curl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 16000, tools: [{ name: get_weather, description: Get current weather for a location, input_schema: { type: object, properties: { location: {type: string, description: City name} }, required: [location] } }], messages: [ {role: user, content: What is the weather in Paris?}, {role: assistant, content: [ {type: text, text: Let me check the weather.}, {type: tool_use, id: toolu_abc123, name: get_weather, input: {location: Paris}} ]}, {role: user, content: [ {type: tool_result, tool_use_id: toolu_abc123, content: 72°F and sunny} ]} ] }需要注意的关联规则来自 SKILL.md 的 Tool Use Patterns并行工具调用默认开启一条 assistant 消息可包含多个tool_use块。应当并发执行这些调用然后在单条 user 消息中一次性返回全部tool_result——拆成多条消息会训练模型不再发起并行调用。工具失败时返回tool_result并带is_error: true不要丢弃该块。需要严格校验时可在工具定义顶层加strict: true与name/description/input_schema平级Schema 必须带additionalProperties: falserequired。解析工具调用的input字段时务必使用json.loads()/JSON.parse()等 JSON 解析器绝不要对序列化后的 input 做原始字符串匹配Fable 5、Opus 5 及 4.6/4.7/4.8 家族可能产生不同的 JSON 字符串转义。提示缓存前缀匹配与 cache_control 断点提示缓存是降低成本的第一免费杠杆。核心机制见 prompt-caching.md是缓存键由渲染后的提示词前缀的精确字节推导而来——前缀中任意位置的 1 个字节变化时间戳、JSON key 重排、工具列表变化都会使该位置之后的所有缓存断点全部失效。渲染顺序是tools→system→messages。curl/examples.md 给出的基础用法把cache_control放在稳定前缀的最后一个块上。curl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 16000, system: [ {type: text, text: large shared prompt..., cache_control: {type: ephemeral}} ], messages: [{role: user, content: Summarize the key points}] }参数细节TTL默认 5 分钟{type: ephemeral}如需 1 小时 TTL写cache_control: {type: ephemeral, ttl: 1h}。顶层自动断点在请求体顶层加cache_control会自动把断点放在最后一个可缓存块上。适用于多轮对话无需手动维护断点但每请求最多 4 个断点且最短可缓存前缀为模型相关约 512–4096 token更短的前缀静默不缓存。显式断点当提示词以每次请求都不同的尾部收尾检索结果、单次问题时应把显式断点放在共享部分末尾而不是整个提示词末尾——否则每次请求都写入不同的缓存条目永远没有命中。验证命中通过响应中的usage.cache_creation_input_tokens写缓存与usage.cache_read_input_tokens读缓存字段判断。如果重复请求前缀完全一致但cache_read_input_tokens恒为 0说明存在静默失效器如系统提示里的datetime.now()、未排序 JSON、变化的工具集需要逐字节 diff 两次请求的渲染后提示词来定位。预热缓存可以在启动时发送max_tokens: 0的请求API 会执行 prefill 写入缓存断点并立即返回content: []、stop_reason: max_tokens、usage已填充消除首个真实请求的缓存未命中延迟。扩展思考adaptive 模式的跨模型差异扩展思考的参数形态在近几代模型间发生了显著变化。curl/examples.md 对此给出了三条按模型区分的规则Fable 5、Claude Opus 5、Opus 4.8、Opus 4.7、Opus 4.6 与 Sonnet 4.6使用 adaptive 思考。budget_tokens在 Fable 5、Claude Opus 5、Opus 4.8、4.7 上已被移除发送会返回 400在 Opus 4.6 和 Sonnet 4.6 上已弃用。Claude Opus 5思考默认开启——省略thinking即运行 adaptive{type: adaptive}与之等价这与 Opus 4.8/4.7 不同它们省略该参数意味着不思考。{type: disabled}只在 effort 为high或更低时被接受与xhigh/max搭配会返回 400。更老的模型使用type: enabled配合budget_tokens: N必须小于max_tokens最小 1024。推荐的 adaptive 写法如下# Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended) curl https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-opus-5, max_tokens: 16000, thinking: { type: adaptive, display: summarized }, output_config: { effort: high }, messages: [{role: user, content: Solve this step by step...}] }补充说明源自 SKILL.md 的 Thinking Effort 章节effort是 GA 功能无需 beta 头取值low/medium/high/xhigh/max默认high放在output_config内不是顶层。它控制思考深度与整体 token 消耗是除缓存之外的首要质量/成本调节杠杆。display默认是omittedFable 5/5.1、Opus 5/4.8/4.7、Sonnet 5 上summarized会返回可读的推理摘要display只影响可见性思考本身始终发生并被计费。思考块的回放规则在同一模型上继续对话时应原样回传思考块切换到其他模型时这些块会被静默丢弃不收费——不要自己动手剥离。拒绝回退Refusal Fallbacks处理安全分类器的拒绝新一代模型如claude-fable-5-1的安全分类器可能拒绝请求返回的是HTTP 200且stop_reason: refusal而不是错误。此时回退是opt-in的不加回退参数请求就简单地停止。带上fallbacks参数及其 beta 头后一旦发生策略拒绝API 会在同一次调用内把相同请求在回退模型上重新运行。curl/examples.md 给出了完整的数组形式示例response$(curl -s https://api.anthropic.com/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H anthropic-beta: server-side-fallback-2026-06-01 \ -d { model: claude-fable-5-1, max_tokens: 16000, fallbacks: [{model: claude-opus-4-8}], messages: [{role: user, content: Hello}] }) # 实际产出消息的是哪个模型 echo $response | jq -r .model # 最终响应如果是 refusal说明整条回退链都拒绝了 echo $response | jq -r .stop_reason # 切换点每个在本轮运行过并拒绝的模型对应一个 fallback 块 echo $response | jq -r .content[] | select(.type fallback) | \(.from.model) declined; \(.to.model) continued # served-by 信号——覆盖 sticky 轮次这些轮次不带 fallback 块。 # 与 stop_reason 配合使用回退模型自身也可能拒绝。 if [ $(echo $response | jq -r .stop_reason) ! refusal ] \ echo $response | jq -e [.usage.iterations[]? | select(.type fallback_message)] | length 0 /dev/null; then echo fallback model served this turn fi需要严格遵守的语义细节beta 头与参数形式必须配对数组形式fallbacks: [{...}]必须使用server-side-fallback-2026-06-01更新的fallbacks: default标量形式由 Anthropic 按拒绝类别自动路由推荐优先使用改用server-side-fallback-2026-07-01详见 model-migration.md 中Migrating to Claude Opus 5 → New API features一节。把任一头与另一种形式配对都会返回 400。可用性边界该参数在 Batches API 上会被拒绝在 Amazon Bedrock、Vertex AI、Microsoft Foundry 上不可用这些平台改用 SDK 的客户端中间件方案。计费规则输出产生前的拒绝不计费流式中途拒绝会为已流出的部分计费回退尝试按回退模型自己的费率计费。sticky 路由一旦某轮对话发生回退后续请求在约 1 小时内直接由回退模型服务best-effort且 sticky 轮次不携带 fallback 块——这就是为什么上面要用usage.iterations中的fallback_message条目作为 served-by 信号。完整语义sticky routing、计费、流式、回退轮次回显规则见 model-migration.md 中Migrating to Claude Fable 5.1 →refusalstop reason一节。进阶技巧从示例到生产脚本的注意事项基于 SKILL.md 的若干实战约定在使用上述 cURL 示例时还应注意max_tokens不要设太低触顶会中途截断输出并需要重试。非流式默认约 16000、流式默认约 64000仅为分类约 256、成本上限或缓存预热0才调低。128K 输出上限的模型必须配合流式使用否则会触发 HTTP 超时。Beta 功能的头管理每次请求最多支持一组anthropic-beta值多个 Beta 功能用逗号分隔如 Managed Agents 文档 managed-agents.md 中的anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01。错误处理区分可重试429、500、网络错误与不可重试400/404的失败。429 时应尊重retry-after头。模型 ID 精确使用只用 SKILL.md 模型表中的精确 ID 字符串如claude-opus-5、claude-fable-5-1绝不追加日期后缀或自行构造。继续深入仓库内相关文档导航本文所有示例均可在 curl/examples.md 中找到原始出处。如需进一步深入curl/managed-agents.mdManaged Agents 的原始 HTTP 参考创建 Agent、启动 Session、SSE 事件流、上传文件等。shared/prompt-caching.md断点放置模式、失效层级与静默失效器审计清单的完整说明。shared/model-migration.md跨模型迁移指南含拒绝回退的完整语义与fallbacks: default新形态。shared/models.md模型 ID 与能力的权威参考。SKILL.md本 Skill 的总纲涵盖选型原则、认证、API Drift 对照表与各类快速参考。赞分享人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载相关推荐Agentic Awesome Skills 实战Claude Files API Python 开发指南——基于 file_id 的文档复用与 Messages API 集成Agentic Awesome Skills 实战Claude Files API Python 开发指南——基于 file_id 的文档复用与 MessagAI 技能AI 插件agentic-awesome-skills 实战TypeScript 流式调用 Claude Messages API 的完整指南agentic awesome skills 实战TypeScript 流式调用 Claude Messages API 的完整指南 导读 在构建聊天界面、实AI 技能AI 插件RikkaHub 中的 Claude API cURL 实战指南从原始 HTTP 请求到工具调用、流式与缓存RikkaHub 中的 Claude API cURL 实战指南从原始 HTTP 请求到工具调用、流式与缓存 本篇指南以 .agents/skills/cla人工智能大模型AI 应用移动开发交互助手上一篇frontend-tips 性能优化篇从图片懒加载到 DocumentFragment 的8个提速技巧下一篇PiliPlus 完整上手免费开源的跨平台B站客户端装一次五端通用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考