尧图网页设计 
人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载导读Message Batches APIPOST /v1/messages/batches允许开发者把大量 Messages API 请求打包成批、异步处理并享受标准价格 50% 的折扣。本文以 skills/claude-api/typescript/claude-api/batches.md 为核心骨架结合仓库内 Python / cURL / C# / PHP 的对应实现与成本优化文档系统讲解在anthropic-ai/sdkTypeScript中如何创建批次、轮询状态、读取结果、取消批次以及如何用提示词缓存进一步压低批处理成本。读完本文你将能编写一套完整可运行的批量文本分类、批量摘要等离线任务流水线。一、什么是 Message Batches API异步处理与半价计费Batches API 的核心设计是把同步的messages.create请求转为异步队列任务客户端一次性提交一批请求每个请求就是一个完整的 Messages 参数集服务端异步排队执行全部完成后统一提供结果下载。这带来两个直接收益成本减半批次内所有 token 用量输入 输出按标准价格 50% 计费吞吐解耦适合没人等着实时返回的离线负载如夜间批量分类、批量摘要、大规模评测集打分、历史数据清洗。与普通 Messages API 相比批处理不是简单的接口换名——它引入了配额、生命周期与结果类型等一整套不同的约束下面逐一展开。关键事实Key Facts根据原文档使用前必须先记住这五条硬性约束约束项数值说明单批请求上限100,000 个请求按requests数组内条目计数单批体积上限256 MB所有请求体合计完成时长多数 1 小时内最长 24 小时不可阻塞等待必须轮询结果保留期创建后 29 天过期后结果不可再读取计费所有 token 用量 5 折对全部 token usage 生效此外所有 Messages API 特性在批处理中均可用vision图片输入、工具调用tool use、提示词缓存prompt caching等无需降级。仓库在 skills/claude-api/shared/cost-optimization.md 中将批处理定位为免费赢项free win之一它不降低输出质量只是把没人等待的那部分流量挪到半价档。二、环境准备安装 SDK 与初始化客户端批处理调用与普通消息调用共用同一个Anthropic客户端因此初始化方式完全一致。仓库的 typescript/claude-api/README.md 给出了安装与初始化标准做法npm install anthropic-ai/sdkimport Anthropic from anthropic-ai/sdk; // 推荐从环境变量解析凭据ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / ant auth login 配置不要硬编码 key const client new Anthropic(); // 仅在必须注入指定 key 时使用显式传参 // const client new Anthropic({ apiKey: your-api-key });ESM 注意在 ES 模块的.ts文件中__dirname/__filename是 undefined直接使用会抛ReferenceError。需要读取本地文件例如后续要打包进批次的图片 base64时cwd 相对读取请传裸相对路径如fs.readFileSync(./sample.png)脚本相对路径则基于import.meta.url推导。三、创建批次Create a Batch批次创建通过client.messages.batches.create()完成入参是一个requests数组。每个请求元素包含两大部分custom_id自定义字符串标识用于在结果中反查对应请求类似批次内的 request_idparams一个完整的非流式 Messages 请求参数对象model、max_tokens、messages、system、tools等与messages.create的参数同构。const messageBatch await client.messages.batches.create({ requests: [ { custom_id: request-1, params: { model: claude-opus-5, max_tokens: 16000, messages: [ { role: user, content: Summarize climate change impacts }, ], }, }, { custom_id: request-2, params: { model: claude-opus-5, max_tokens: 16000, messages: [ { role: user, content: Explain quantum computing basics }, ], }, }, ], }); console.log(Batch ID: ${messageBatch.id}); console.log(Status: ${messageBatch.processing_status});创建成功后返回的批次对象关键字段id批次唯一 ID后续 retrieve / results / cancel 都要用到processing_status当前处理状态见下节状态流转。设计建议custom_id应携带业务语义如classify-0、analysis-42而不是无意义序号这样解析结果时无需额外映射表。仓库的 python/claude-api/batches.md 中端到端示例即采用classify-{i}这类模式。原始 HTTP 形态cURL 视角如需理解底层协议或脱离 SDK 调试可以参照 curl/examples.md 中的请求头规范Content-Type: application/json、x-api-key、anthropic-version: 2023-06-01。批次端点与普通消息端点不同SDK 的batches命名空间正是封装了POST /v1/messages/batches及其子路径这与 csharp/claude-api/batches.mdclient.Messages.Batches.Create和 php/claude-api/batches.md$client-messages-batches-create的命名空间一一对应从源码结构可以推断三套 SDK 遵循同一套 REST 资源模型。四、轮询完成状态Poll for Completion批处理是异步的创建后需要轮询client.messages.batches.retrieve(batchId)直到终态。原文档给出的轮询模式如下let batch; while (true) { batch await client.messages.batches.retrieve(messageBatch.id); if (batch.processing_status ended) break; console.log( Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}, ); await new Promise((resolve) setTimeout(resolve, 60_000)); } console.log(Batch complete!); console.log(Succeeded: ${batch.request_counts.succeeded}); console.log(Errored: ${batch.request_counts.errored});关键字段说明processing_status批次状态。常见取值包括processing处理中、ended已结束以及取消路径上的canceling/ 已取消等request_counts计数统计对象包含processing处理中数量、succeeded成功数量、errored失败数量等子字段可在轮询过程中实时观察进度。轮询间隔建议多数批次 1 小时内完成原文档默认每 60 秒轮询一次对紧急度低的超大批次可放宽间隔以降低 API 调用次数。Python 版端到端示例python/claude-api/batches.md对小型批次用 10 秒间隔可作对照参考。五、读取结果Retrieve Results批次进入ended后通过client.messages.batches.results(batchId)以**异步迭代器async iterable**形式逐条读取结果。每条结果包含custom_id与result对象result.type是一个判别联合discriminated union必须在switch中按类型分支处理for await (const result of await client.messages.batches.results( messageBatch.id, )) { switch (result.result.type) { case succeeded: console.log( [${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}, ); break; case errored: if (result.result.error.type invalid_request) { console.log([${result.custom_id}] Validation error - fix and retry); } else { console.log([${result.custom_id}] Server error - safe to retry); } break; case expired: console.log([${result.custom_id}] Expired - resubmit); break; } }结果类型与重试语义result.result.type含义处理建议succeeded请求成功从result.result.message中取内容块注意content是ContentBlock[]应先按type text收窄再取.texterrored请求失败细看result.result.error.typeinvalid_request表示请求本身有校验问题修好参数后重新提交其他类型表示服务端错误可直接安全重试expired结果过期重新提交请求canceled已被取消按业务需要决定是否重建批次原文档的 TypeScript 版覆盖succeeded / errored / expired三类python/claude-api/batches.md 额外展示了canceled分支说明底层结果类型集合中还存在已取消这一状态TS 项目中如处理取消流程建议一并判断。六、取消批次Cancel a Batch当批次仍在处理中、但你决定不再需要它时例如上游数据出错可以调用取消接口const cancelled await client.messages.batches.cancel(messageBatch.id); console.log(Status: ${cancelled.processing_status}); // canceling取消是异步生效的返回的processing_status为canceling取消中随后通过 retrieve 轮询会看到它过渡到已取消终态。已ended的批次无法再取消。七、端到端实战批量情感分类流水线把以上四个步骤串起来即构成一个完整的批处理流水线。下面是一个基于原文档模式、并参考仓库 Python 端到端示例python/claude-api/batches.md整合出的 TypeScript 完整示例——对多条评论文本做情感分类import Anthropic from anthropic-ai/sdk; const client new Anthropic(); async function classifyInBatch(items: string[]): PromiseMapstring, string { // 1. 构造请求每个 item 生成一个带语义 custom_id 的请求 const requests items.map((text, i) ({ custom_id: classify-${i}, params: { model: claude-opus-5, max_tokens: 50, messages: [ { role: user, content: Classify as positive/negative/neutral (one word): ${text}, }, ], }, })); // 2. 创建批次 const batch await client.messages.batches.create({ requests }); console.log(Created batch: ${batch.id}); // 3. 轮询直至结束 while (true) { const current await client.messages.batches.retrieve(batch.id); if (current.processing_status ended) break; console.log( Status: ${current.processing_status}, processing: ${current.request_counts.processing}, ); await new Promise((resolve) setTimeout(resolve, 10_000)); } // 4. 收集结果按 custom_id 组织便于排序输出 const results new Mapstring, string(); for await (const result of await client.messages.batches.results(batch.id)) { if (result.result.type succeeded) { const text (result.result.message.content[0] as Anthropic.TextBlock).text; results.set(result.custom_id, text); } } return results; } // 用法results.get(classify-0) 即第一条文本的分类结果此处的content[0]直接断言为TextBlock实际生产代码建议先用block.type text收窄仓库 TypeScript 文档在基本消息请求一节反复强调这一点避免 TypeScript 类型报错。八、进阶批处理 × 提示词缓存组合批处理 5 折优惠可与提示词缓存prompt caching叠加是离线任务压成本最有效的组合。核心技巧把所有请求共享的稳定前缀如同一个大型背景文档、统一角色设定放进system并用cache_control标记让批次内的多个请求共享同一份缓存。仓库 python/claude-api/batches.md 给出了共享 system 的构建方式TS 版结构完全相同只是类型书写不同const sharedSystem: Anthropic.TextBlockParam[] [ { type: text, text: You are a literary analyst. }, { type: text, text: largeDocumentText, // 所有请求共享的上下文 cache_control: { type: ephemeral }, }, ]; const messageBatch await client.messages.batches.create({ requests: questions.map((question, i) ({ custom_id: analysis-${i}, params: { model: claude-opus-5, max_tokens: 16000, system: sharedSystem, messages: [{ role: user, content: question }], }, })), });缓存相关验证字段在普通消息响应中同样适用usage.cache_creation_input_tokens写入缓存的 token约 1.25 倍成本、usage.cache_read_input_tokens命中缓存的 token约 0.1 倍成本、usage.input_tokens未命中部分全价。完整的放置模式与静默失效项排查清单见 skills/claude-api/shared/prompt-caching.md。并发批次中的缓存是 best-effortskills/claude-api/shared/cost-optimization.md 明确指出并发批处理场景下的缓存命中并不保证排查缓存命中率异常时不要把并发批次带来的 miss 当作缓存被破坏的故障。九、设计约束与成本优化视角从仓库成本优化文档skills/claude-api/shared/cost-optimization.md可以提炼出批处理场景的两条重要设计事实批内请求是单发的single-shot无中间工具循环。批次执行期间不会像交互式对话那样自动执行模型调用工具 → 回填结果 → 再调用的循环。如果你的任务包含工具循环有两种处理路径保持交互式实时调用放弃半价预先拉取工具所需输入、把工具循环扁平化为一个可批处理的单请求。文档中的实践案例显示扁平化后的批处理运行成本约为原交互配置的一半但这是架构决策而非参数调整——它改变了模型推理方式文中示例的通过率保持不如交互式稳定需结合评测权衡。批处理上限就是成本上限成本优化文档将批处理定位为标准档流量中无人等待部分的 5 折天花板建议先用service_tier分组观测哪些流量已在批次档、哪些可以迁移再据此规划迁移范围。此外还有一处易被忽略的成本细节上下文编辑context editing会重写缓存对话是省缓存钱的反面操作。批处理任务里若每个请求都从同一共享上下文出发且频繁清空旧内容缓存收益会被抵消共享前缀应保持字节级稳定任何动态内容如Date.now()、UUID都要放在user消息而非共享前缀中。十、跨语言对照一套 REST 模型五套 SDK 绑定Message Batches API 的资源模型在各语言 SDK 中高度一致便于团队多语言协作时对齐语言创建轮询读结果取消文档位置TypeScriptclient.messages.batches.create.retrieve.results.canceltypescript/claude-api/batches.mdPythonclient.messages.batches.create.retrieve.results.cancelpython/claude-api/batches.mdC#client.Messages.Batches.CreateMessages.Batches.RetrieveMessages.Batches.Results—csharp/claude-api/batches.mdPHP$client-messages-batches-create-retrieve-results—php/claude-api/batches.mdcURL / 裸 HTTPPOST /v1/messages/batchesGET 轮询GET 结果DELETEcurl/examples.md其中 Python 版还额外展示了列出批次client.messages.batches.list(limit20)能力迭代list()返回值会自动跨页翻完所有批次如需手动控制分页可用first_page.has_next_page()/get_next_page()/last_id游标。TS SDK 的batches.list命名空间与之对应可按同样模式使用。十一、注意事项清单Checklist收尾前把本文涉及的易错点集中成清单方便直接对照落地配额先行单批 ≤ 100,000 请求且 ≤ 256 MB超限会创建失败不要同步等待批次最长 24 小时客户端必须设计为提交 → 轮询 → 取结果的异步流水线任务队列 / cron / worker 均可结果会过期29 天保留期务必在期限内消费并落盘expired结果需重新提交结果按 custom_id 归位读取结果时用custom_id做映射不要在succeeded之外的类型上访问message字段区分两类错误errored中invalid_request需修参数重提服务端错误可直接重试取消是异步的cancel()返回canceling需轮询确认进入取消终态内容块先收窄再取文本content[0].text在 TS 类型上不是安全访问务必按block.type判别后再读取缓存前缀要稳定共享 system 加cache_control动态内容全部下沉到user消息工具循环不适用批次内请求是单发的涉及工具链的任务要么预拉取输入扁平化要么保持实时调用模型与版本以现状为准文中示例模型claude-opus-5取自本仓库文档具体模型可用性、beta 头等信息请以 skills/claude-api/shared/models.md 及 SDK 发行说明为准。小结Message Batches API 是 Claude 平台上低成本、高吞吐离线工作负载的标准解法用 50% 的价格换取最长 24 小时的异步排队配合提示词缓存可在批内进一步共享上下文成本。TypeScript 侧只需掌握create → retrieve → results → cancel四个方法即可搭建完整流水线而仓库内 Python / C# / PHP / cURL 的同构实现为多语言团队提供了统一的可对照参考。赞分享人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载相关推荐用 PHP SDK 调用 Claude Message Batches API异步批量处理与结果收集实战指南用 PHP SDK 调用 Claude Message Batches API异步批量处理与结果收集实战指南 导读 本文以 .agents/skills/cl人工智能大模型AI 应用移动开发交互助手agentic-awesome-skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南agentic awesome skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南 导读 本文以AI 技能AI 插件使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线 导读 本文聚焦于 Claude APIAI 技能AI 插件上一篇fanqienovel-downloader格式转换全攻略EPUB、HTML、Latex输出配置详解下一篇防止 API 路由瀑布链在 Polar 服务端践行 Vercel 异步并行最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 TypeScript 调用 Claude Message Batches API：异步批处理、结果轮询与成本优化实战指南
人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载导读Message Batches APIPOST /v1/messages/batches允许开发者把大量 Messages API 请求打包成批、异步处理并享受标准价格 50% 的折扣。本文以 skills/claude-api/typescript/claude-api/batches.md 为核心骨架结合仓库内 Python / cURL / C# / PHP 的对应实现与成本优化文档系统讲解在anthropic-ai/sdkTypeScript中如何创建批次、轮询状态、读取结果、取消批次以及如何用提示词缓存进一步压低批处理成本。读完本文你将能编写一套完整可运行的批量文本分类、批量摘要等离线任务流水线。一、什么是 Message Batches API异步处理与半价计费Batches API 的核心设计是把同步的messages.create请求转为异步队列任务客户端一次性提交一批请求每个请求就是一个完整的 Messages 参数集服务端异步排队执行全部完成后统一提供结果下载。这带来两个直接收益成本减半批次内所有 token 用量输入 输出按标准价格 50% 计费吞吐解耦适合没人等着实时返回的离线负载如夜间批量分类、批量摘要、大规模评测集打分、历史数据清洗。与普通 Messages API 相比批处理不是简单的接口换名——它引入了配额、生命周期与结果类型等一整套不同的约束下面逐一展开。关键事实Key Facts根据原文档使用前必须先记住这五条硬性约束约束项数值说明单批请求上限100,000 个请求按requests数组内条目计数单批体积上限256 MB所有请求体合计完成时长多数 1 小时内最长 24 小时不可阻塞等待必须轮询结果保留期创建后 29 天过期后结果不可再读取计费所有 token 用量 5 折对全部 token usage 生效此外所有 Messages API 特性在批处理中均可用vision图片输入、工具调用tool use、提示词缓存prompt caching等无需降级。仓库在 skills/claude-api/shared/cost-optimization.md 中将批处理定位为免费赢项free win之一它不降低输出质量只是把没人等待的那部分流量挪到半价档。二、环境准备安装 SDK 与初始化客户端批处理调用与普通消息调用共用同一个Anthropic客户端因此初始化方式完全一致。仓库的 typescript/claude-api/README.md 给出了安装与初始化标准做法npm install anthropic-ai/sdkimport Anthropic from anthropic-ai/sdk; // 推荐从环境变量解析凭据ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / ant auth login 配置不要硬编码 key const client new Anthropic(); // 仅在必须注入指定 key 时使用显式传参 // const client new Anthropic({ apiKey: your-api-key });ESM 注意在 ES 模块的.ts文件中__dirname/__filename是 undefined直接使用会抛ReferenceError。需要读取本地文件例如后续要打包进批次的图片 base64时cwd 相对读取请传裸相对路径如fs.readFileSync(./sample.png)脚本相对路径则基于import.meta.url推导。三、创建批次Create a Batch批次创建通过client.messages.batches.create()完成入参是一个requests数组。每个请求元素包含两大部分custom_id自定义字符串标识用于在结果中反查对应请求类似批次内的 request_idparams一个完整的非流式 Messages 请求参数对象model、max_tokens、messages、system、tools等与messages.create的参数同构。const messageBatch await client.messages.batches.create({ requests: [ { custom_id: request-1, params: { model: claude-opus-5, max_tokens: 16000, messages: [ { role: user, content: Summarize climate change impacts }, ], }, }, { custom_id: request-2, params: { model: claude-opus-5, max_tokens: 16000, messages: [ { role: user, content: Explain quantum computing basics }, ], }, }, ], }); console.log(Batch ID: ${messageBatch.id}); console.log(Status: ${messageBatch.processing_status});创建成功后返回的批次对象关键字段id批次唯一 ID后续 retrieve / results / cancel 都要用到processing_status当前处理状态见下节状态流转。设计建议custom_id应携带业务语义如classify-0、analysis-42而不是无意义序号这样解析结果时无需额外映射表。仓库的 python/claude-api/batches.md 中端到端示例即采用classify-{i}这类模式。原始 HTTP 形态cURL 视角如需理解底层协议或脱离 SDK 调试可以参照 curl/examples.md 中的请求头规范Content-Type: application/json、x-api-key、anthropic-version: 2023-06-01。批次端点与普通消息端点不同SDK 的batches命名空间正是封装了POST /v1/messages/batches及其子路径这与 csharp/claude-api/batches.mdclient.Messages.Batches.Create和 php/claude-api/batches.md$client-messages-batches-create的命名空间一一对应从源码结构可以推断三套 SDK 遵循同一套 REST 资源模型。四、轮询完成状态Poll for Completion批处理是异步的创建后需要轮询client.messages.batches.retrieve(batchId)直到终态。原文档给出的轮询模式如下let batch; while (true) { batch await client.messages.batches.retrieve(messageBatch.id); if (batch.processing_status ended) break; console.log( Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}, ); await new Promise((resolve) setTimeout(resolve, 60_000)); } console.log(Batch complete!); console.log(Succeeded: ${batch.request_counts.succeeded}); console.log(Errored: ${batch.request_counts.errored});关键字段说明processing_status批次状态。常见取值包括processing处理中、ended已结束以及取消路径上的canceling/ 已取消等request_counts计数统计对象包含processing处理中数量、succeeded成功数量、errored失败数量等子字段可在轮询过程中实时观察进度。轮询间隔建议多数批次 1 小时内完成原文档默认每 60 秒轮询一次对紧急度低的超大批次可放宽间隔以降低 API 调用次数。Python 版端到端示例python/claude-api/batches.md对小型批次用 10 秒间隔可作对照参考。五、读取结果Retrieve Results批次进入ended后通过client.messages.batches.results(batchId)以**异步迭代器async iterable**形式逐条读取结果。每条结果包含custom_id与result对象result.type是一个判别联合discriminated union必须在switch中按类型分支处理for await (const result of await client.messages.batches.results( messageBatch.id, )) { switch (result.result.type) { case succeeded: console.log( [${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}, ); break; case errored: if (result.result.error.type invalid_request) { console.log([${result.custom_id}] Validation error - fix and retry); } else { console.log([${result.custom_id}] Server error - safe to retry); } break; case expired: console.log([${result.custom_id}] Expired - resubmit); break; } }结果类型与重试语义result.result.type含义处理建议succeeded请求成功从result.result.message中取内容块注意content是ContentBlock[]应先按type text收窄再取.texterrored请求失败细看result.result.error.typeinvalid_request表示请求本身有校验问题修好参数后重新提交其他类型表示服务端错误可直接安全重试expired结果过期重新提交请求canceled已被取消按业务需要决定是否重建批次原文档的 TypeScript 版覆盖succeeded / errored / expired三类python/claude-api/batches.md 额外展示了canceled分支说明底层结果类型集合中还存在已取消这一状态TS 项目中如处理取消流程建议一并判断。六、取消批次Cancel a Batch当批次仍在处理中、但你决定不再需要它时例如上游数据出错可以调用取消接口const cancelled await client.messages.batches.cancel(messageBatch.id); console.log(Status: ${cancelled.processing_status}); // canceling取消是异步生效的返回的processing_status为canceling取消中随后通过 retrieve 轮询会看到它过渡到已取消终态。已ended的批次无法再取消。七、端到端实战批量情感分类流水线把以上四个步骤串起来即构成一个完整的批处理流水线。下面是一个基于原文档模式、并参考仓库 Python 端到端示例python/claude-api/batches.md整合出的 TypeScript 完整示例——对多条评论文本做情感分类import Anthropic from anthropic-ai/sdk; const client new Anthropic(); async function classifyInBatch(items: string[]): PromiseMapstring, string { // 1. 构造请求每个 item 生成一个带语义 custom_id 的请求 const requests items.map((text, i) ({ custom_id: classify-${i}, params: { model: claude-opus-5, max_tokens: 50, messages: [ { role: user, content: Classify as positive/negative/neutral (one word): ${text}, }, ], }, })); // 2. 创建批次 const batch await client.messages.batches.create({ requests }); console.log(Created batch: ${batch.id}); // 3. 轮询直至结束 while (true) { const current await client.messages.batches.retrieve(batch.id); if (current.processing_status ended) break; console.log( Status: ${current.processing_status}, processing: ${current.request_counts.processing}, ); await new Promise((resolve) setTimeout(resolve, 10_000)); } // 4. 收集结果按 custom_id 组织便于排序输出 const results new Mapstring, string(); for await (const result of await client.messages.batches.results(batch.id)) { if (result.result.type succeeded) { const text (result.result.message.content[0] as Anthropic.TextBlock).text; results.set(result.custom_id, text); } } return results; } // 用法results.get(classify-0) 即第一条文本的分类结果此处的content[0]直接断言为TextBlock实际生产代码建议先用block.type text收窄仓库 TypeScript 文档在基本消息请求一节反复强调这一点避免 TypeScript 类型报错。八、进阶批处理 × 提示词缓存组合批处理 5 折优惠可与提示词缓存prompt caching叠加是离线任务压成本最有效的组合。核心技巧把所有请求共享的稳定前缀如同一个大型背景文档、统一角色设定放进system并用cache_control标记让批次内的多个请求共享同一份缓存。仓库 python/claude-api/batches.md 给出了共享 system 的构建方式TS 版结构完全相同只是类型书写不同const sharedSystem: Anthropic.TextBlockParam[] [ { type: text, text: You are a literary analyst. }, { type: text, text: largeDocumentText, // 所有请求共享的上下文 cache_control: { type: ephemeral }, }, ]; const messageBatch await client.messages.batches.create({ requests: questions.map((question, i) ({ custom_id: analysis-${i}, params: { model: claude-opus-5, max_tokens: 16000, system: sharedSystem, messages: [{ role: user, content: question }], }, })), });缓存相关验证字段在普通消息响应中同样适用usage.cache_creation_input_tokens写入缓存的 token约 1.25 倍成本、usage.cache_read_input_tokens命中缓存的 token约 0.1 倍成本、usage.input_tokens未命中部分全价。完整的放置模式与静默失效项排查清单见 skills/claude-api/shared/prompt-caching.md。并发批次中的缓存是 best-effortskills/claude-api/shared/cost-optimization.md 明确指出并发批处理场景下的缓存命中并不保证排查缓存命中率异常时不要把并发批次带来的 miss 当作缓存被破坏的故障。九、设计约束与成本优化视角从仓库成本优化文档skills/claude-api/shared/cost-optimization.md可以提炼出批处理场景的两条重要设计事实批内请求是单发的single-shot无中间工具循环。批次执行期间不会像交互式对话那样自动执行模型调用工具 → 回填结果 → 再调用的循环。如果你的任务包含工具循环有两种处理路径保持交互式实时调用放弃半价预先拉取工具所需输入、把工具循环扁平化为一个可批处理的单请求。文档中的实践案例显示扁平化后的批处理运行成本约为原交互配置的一半但这是架构决策而非参数调整——它改变了模型推理方式文中示例的通过率保持不如交互式稳定需结合评测权衡。批处理上限就是成本上限成本优化文档将批处理定位为标准档流量中无人等待部分的 5 折天花板建议先用service_tier分组观测哪些流量已在批次档、哪些可以迁移再据此规划迁移范围。此外还有一处易被忽略的成本细节上下文编辑context editing会重写缓存对话是省缓存钱的反面操作。批处理任务里若每个请求都从同一共享上下文出发且频繁清空旧内容缓存收益会被抵消共享前缀应保持字节级稳定任何动态内容如Date.now()、UUID都要放在user消息而非共享前缀中。十、跨语言对照一套 REST 模型五套 SDK 绑定Message Batches API 的资源模型在各语言 SDK 中高度一致便于团队多语言协作时对齐语言创建轮询读结果取消文档位置TypeScriptclient.messages.batches.create.retrieve.results.canceltypescript/claude-api/batches.mdPythonclient.messages.batches.create.retrieve.results.cancelpython/claude-api/batches.mdC#client.Messages.Batches.CreateMessages.Batches.RetrieveMessages.Batches.Results—csharp/claude-api/batches.mdPHP$client-messages-batches-create-retrieve-results—php/claude-api/batches.mdcURL / 裸 HTTPPOST /v1/messages/batchesGET 轮询GET 结果DELETEcurl/examples.md其中 Python 版还额外展示了列出批次client.messages.batches.list(limit20)能力迭代list()返回值会自动跨页翻完所有批次如需手动控制分页可用first_page.has_next_page()/get_next_page()/last_id游标。TS SDK 的batches.list命名空间与之对应可按同样模式使用。十一、注意事项清单Checklist收尾前把本文涉及的易错点集中成清单方便直接对照落地配额先行单批 ≤ 100,000 请求且 ≤ 256 MB超限会创建失败不要同步等待批次最长 24 小时客户端必须设计为提交 → 轮询 → 取结果的异步流水线任务队列 / cron / worker 均可结果会过期29 天保留期务必在期限内消费并落盘expired结果需重新提交结果按 custom_id 归位读取结果时用custom_id做映射不要在succeeded之外的类型上访问message字段区分两类错误errored中invalid_request需修参数重提服务端错误可直接重试取消是异步的cancel()返回canceling需轮询确认进入取消终态内容块先收窄再取文本content[0].text在 TS 类型上不是安全访问务必按block.type判别后再读取缓存前缀要稳定共享 system 加cache_control动态内容全部下沉到user消息工具循环不适用批次内请求是单发的涉及工具链的任务要么预拉取输入扁平化要么保持实时调用模型与版本以现状为准文中示例模型claude-opus-5取自本仓库文档具体模型可用性、beta 头等信息请以 skills/claude-api/shared/models.md 及 SDK 发行说明为准。小结Message Batches API 是 Claude 平台上低成本、高吞吐离线工作负载的标准解法用 50% 的价格换取最长 24 小时的异步排队配合提示词缓存可在批内进一步共享上下文成本。TypeScript 侧只需掌握create → retrieve → results → cancel四个方法即可搭建完整流水线而仓库内 Python / C# / PHP / cURL 的同构实现为多语言团队提供了统一的可对照参考。赞分享人工智能AI 技能AI 评测【免费下载链接】skillsPublic repository for Agent Skills项目地址https://gitcode.com/GitHub_Trending/skills3/skills点击查看免费下载相关推荐用 PHP SDK 调用 Claude Message Batches API异步批量处理与结果收集实战指南用 PHP SDK 调用 Claude Message Batches API异步批量处理与结果收集实战指南 导读 本文以 .agents/skills/cl人工智能大模型AI 应用移动开发交互助手agentic-awesome-skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南agentic awesome skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南 导读 本文以AI 技能AI 插件使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线 导读 本文聚焦于 Claude APIAI 技能AI 插件上一篇fanqienovel-downloader格式转换全攻略EPUB、HTML、Latex输出配置详解下一篇防止 API 路由瀑布链在 Polar 服务端践行 Vercel 异步并行最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考