diff --git a/.gitattributes b/.gitattributes index 5b3ce84a..ffca92d4 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,6 @@ * text=auto eol=lf +# Official fixture captures keep their original bytes and vendor formatting. +tests/fixtures/official-model-registry/sources/** -text -whitespace docs/embedded-browser-development-evidence/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol docs/embedded-browser-release-evidence/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol docs/embedded-browser-rejected-candidate-evidence/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol diff --git a/docs/M2-OFFICIAL-REGISTRY-PLAN.md b/docs/M2-OFFICIAL-REGISTRY-PLAN.md new file mode 100644 index 00000000..de54401b --- /dev/null +++ b/docs/M2-OFFICIAL-REGISTRY-PLAN.md @@ -0,0 +1,13 @@ +# M2 第三批:官方模型能力注册表 + +2026-11-07;基线 `3278c1851a650e320352698bd0ff4fa0ce8cac11`,工作树干净、既有 GitAtlas 分支逐 SHA 一致。承接 I10 用量和 I13 完整账本,推进 I15 与 I28 的注册表来源部分;I09/I11/I12/I14 请求版本/缓存状态与 I27 CI 仍独立验收。 + +1. [complete] 17份官方来源/813289字节及双方SHA固定于[来源清单](../tests/fixtures/official-model-registry/SOURCE.json),完整捕获留自有QA根。6旧源码/4配置和目录基线显示nextPageToken与原字段遗漏;精确协议/型号/版本/条件已核对。首次夹具脚本把M1清单路径误当basename,原失败保持,第二独立脚本按实际路径验封通过。官方Anthropic示例使用2026-10-21,与当前固定2023-06-01的有效性不能混称已验证,I14另核对实际请求版本。 +2. [in_progress] 建立可版本化、可校验与可更新的纯注册表;保留精确 ID、逐字段来源/冲突/有效范围、容量/推理/工具/媒体/缓存/结构化/弃用事实。替代重复的精确 Claude 表,不从型号子串或显示品牌猜能力;手选透传不变。 +3. [pending] 上游目录保留完整原始声明、正确分页并在选择/刷新时保持原凭据、用户字段与旧 Run;新连接取得官方后备元数据。现有模型中心/参数面板展示来源与冲突,提供显式兼容覆盖并持久保存。 +4. [pending] 固定官方来源/条件矩阵、多页/未知/退役/冲突/旧配置/参数/真实本机 wire 和恢复;独立冻结构建与网页/实际 Electron 宽窄屏核心路径,检查源码/编译/原件身份。首失败完整保留,不为通过降低检查。 +5. [pending] 回顾、限定本地提交与既有 GitAtlas 普通增量推送,更新准确接续。下一缓存块/状态/指纹/请求版本与 CI,再 M3 统一发行。 + +官方已确认的差异包括 GPT-6.1 Sol/Terra 工具要求 Responses、GPT-6 Sol/Luna 在 Chat 中要求 reasoning_effort=none。它们属于有来源的型号/协议条件,不代表代理拒发、真实模型通过或本地额度。兼容线路可显式声明差异,保留双方来源和实际错误。 + +本批不委派、不读真实 Key、不请求真实模型、不改正式数据/配置、不发行/安装/重启、不续旧实验或用户工程。默认 unrestricted/passthrough/preserve 和持久 ask/auto/full 不变;原账本/工件/SHA/unknown 保持。I13 的 schema2 安装增量和激活后回退仍由 M3 实际验证,不能简单放行新表或删旧守卫。历史 W/AD/AE/AG 网络、unknown、真实缓存/重复读/Purge收益unknown全部保留。 diff --git a/findings.md b/findings.md index b1af3073..7f08b6b8 100644 --- a/findings.md +++ b/findings.md @@ -1,5 +1,9 @@ # 汇总发现 +M2 I15来源/基线已验:17份官方来源813289字节、6旧源码/4配置固定。DeepSeek当前Models API给出1048576上下文/393216最大输出、effort.supported_levels/default_level和api_capabilities;Messages max_tokens在其HTTP层可选、thinking预算被忽略,不能套Anthropic必填语义。Anthropic新版官方例用2026-10-21,现固定2023-06-01的有效性另由I14核对。首夹具把M1清单完整路径误当basename,原脚本/工具错误记录保留,第二按实际路径核SHA通过;无产品或旧证据写入。 + +M2 I15起点:当前仅有四Claude精确容量/推理表,其他参数仍从DeepSeek品牌/型号正则猜配置档;目录丢失原字段且不认识nextPageToken。官方OpenAI当前页面明确Sol/Terra工具要求Responses、Sol/Luna旧代Chat工具需reasoning_effort=none,不能用一份通用tools支持代替。将保留官方条件/逐字段来源、代理差异、用户覆盖与实际验证;未知不猜。本次数次过长读输出和猜错客户端路径已纠正为文件列表/明确字段,未当产品验证。 + M2 I13:1107旧记录开放实际全存但只显100,有限只存1000、文案错误。源码da2e6313改为schema2增量表、原metadata原字节/初始记录保留、当前尝试独立更新、完整seq游标/筛选/快照NDJSON。HTTP真实导出只等drain停滞改等实际写回调;首JSON undefined夹具、HTTP超时/中断、桌面初始导航、candidate-4复制失误和网页历史筛选修复均保留。最终build-4独立39/39、candidate-app-5两端各5组/7图/23页/1本机请求,830输入/285产品源码/29编译、4328原件、16源码Git blob核对通过;相关102/102在最后公开数据库版本修正前。M3需明确迁移增量及新处理器回退,不删新记录/回写旧metadata或直接去掉逐表全等守卫;仅同步接续失败的未变初始化撤销已验。真实供应商/缓存/重复读/Purge收益unknown。 M2首批I10源码cb60fb11完成缓存读/写/未缓存/推理及TTL来源、unknown/冲突保留和失败上下文用量;透传证据核验允许必填/显式输出字段,原SHA/归属/冻结预算不变。最终相关93/93、独立23/23、网页与实际Electron各5组/6图/1280及390通过,822输入/29编译一致;2948原件1018919970字节见[验收](docs/QA-M2-CACHE-USAGE.md)与[机器记录](docs/m2-cache-usage-2026-11-07.json)(docs内使用同级文件名)。首12/15及网页/桌面验收器失败保持。0真实模型/Key/正式写入,不委派/安装/重启或续旧工程,未作新正式health声明。下一I13完整账本/逐请求存储,再M2官方注册表/原生缓存块/状态/指纹/版本与CI、M3统一发行;手机性能/宿主原因/物理手机及历史真实异常、重复读/Purge收益unknown保持。正在验收文档提交与既有GitAtlas普通增量推送,下方按原时点理解。 diff --git a/progress.md b/progress.md index 10a66d4d..cb81c5e7 100644 --- a/progress.md +++ b/progress.md @@ -1,5 +1,9 @@ # 统一执行进度 +M2 I15阶段1完成:官方17份813289字节和6旧源码/4配置观察已封于自有根,来源fixture含精确URL、捕获/原源SHA、时间和表示范围。下一纯注册表实现与相关确定性验证;本阶段没有产品/正式改动,公开文档请求不是模型调用。首夹具路径表示错误原件保留。 + +M2 I15开始:3278c185工作树干净且远端一致,官方文档工具先搜索并取得Models与五精确GPT6当前页面,原文本已保存到自有证据根。先补官方注册表与来源/条件,再目录/现有UI及独立候选;尚无本批产品改动/模型请求/正式操作,不委派。 + M2 I13普通增量推送完成:da2e6313/a2c6e6f5已在既有GitAtlas分支、ls-remote逐SHA一致,回执docs/gitatlas-m2-request-ledger-push.json随最后接续提交再复核。原封存根不追加,下一I15;正式/历史unknown不变。 M2 I13源码da2e6313与独立候选验收完成:相关第4轮102/102在最后公开版本修正前,最后build-4独立39/39;candidate-app-5网页与实际Electron各5组/7图/23页/1本机请求、1107→1108全量下载/当前和初始SHA/重启保持。830输入/285产品源码/29编译及4328份1620432307字节原件、12原字节/4仅LF归一源码Git blob只读复核通过,原失败保持。验收文档和授权GitAtlas普通增量推送收尾中,下一I15/缓存块状态版本/CI;正式未部署/重启或新health复查,M3安装增量与新处理器回退及历史unknown保持。 diff --git a/task_plan.md b/task_plan.md index a92649e3..f7a21e01 100644 --- a/task_plan.md +++ b/task_plan.md @@ -1,5 +1,7 @@ # Agent Workbench:核心代理能力研究与产品计划 +当前M2第三批I15:从3278c185干净/远端一致基线开始,见[官方注册表计划](docs/M2-OFFICIAL-REGISTRY-PLAN.md)。已取得OpenAI当前模型官方页面,先固定精确型号/协议/版本/条件和逐字段来源,再接目录与现有参数界面;不触正式/真实Key/模型,不委派,不重启。历史异常和M3安装回退待办保持。 + 当前M2第二批I13:[计划](docs/M2-REQUEST-LEDGER-PLAN.md)阶段1–5完成,源码da2e6313/验收a2c6e6f5已普通增量推送并逐SHA一致,[回执](docs/gitatlas-m2-request-ledger-push.json)另随最后接续提交复核。最终build-4独立39/39、candidate-app-5网页与实际Electron各5组/7图/23页通过,830输入/285产品源码/29编译及4328原件/16源码Git blob核对;相关102/102在最后公开版本修正前。下一I15及I09/I11/I12/I14、CI,再M3明确schema2安装/回退。正式未部署/重启或新health复查,默认透传/持久权限和历史unknown保持。 M2首批I10:源码cb60fb11/相关93/独立23/网页与实际Electron各5组已完成,2948原件SHA封存;验收文档提交与授权GitAtlas增量推送收尾。下一I13完整请求账本/逐请求存储,再M2其余和M3,正式未部署/重启,真实收益unknown。 diff --git a/tests/fixtures/official-model-registry/SOURCE.json b/tests/fixtures/official-model-registry/SOURCE.json new file mode 100644 index 00000000..661d6178 --- /dev/null +++ b/tests/fixtures/official-model-registry/SOURCE.json @@ -0,0 +1,194 @@ +{ + "schemaVersion": 1, + "registryVersion": "2026-11-07.1", + "sources": [ + { + "id": "claude-models__overview", + "provider": "anthropic", + "url": "https://platform.claude.com/docs/en/models/overview", + "checkedAt": "2026-11-06", + "sha256": "58a0bd14d9badfe29071397995bc87c1ced653a8b0acde20d34d85e3a9df5562", + "file": "sources/claude-models-overview.md", + "originalSha256": "04ced1978ad32f6015dfd82c4b4a89812f673411d4d0bd10aedb2957431d9907", + "representation": "extracted-official-markdown", + "scope": "complete-target-article-excerpt" + }, + { + "id": "claude-build-with-claude__thinking", + "provider": "anthropic", + "url": "https://platform.claude.com/docs/en/build-with-claude/thinking", + "checkedAt": "2026-11-06", + "sha256": "ff24b4c309610835c57611e4f5b6f8870b27950a8d4548bfae680c9eec1dfb42", + "file": "sources/claude-build-with-claude-thinking.md", + "originalSha256": "ff24b4c309610835c57611e4f5b6f8870b27950a8d4548bfae680c9eec1dfb42", + "representation": "extracted-official-markdown", + "scope": "complete-captured-source" + }, + { + "id": "claude-build-with-claude__thinking-steering-and-cost", + "provider": "anthropic", + "url": "https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost", + "checkedAt": "2026-11-06", + "sha256": "28b1226b41557efa8d43e3eb28aa038c70b96866939bf1e7cbfd976d82482854", + "file": "sources/claude-build-with-claude-thinking-steering-and-cost.md", + "originalSha256": "28b1226b41557efa8d43e3eb28aa038c70b96866939bf1e7cbfd976d82482854", + "representation": "extracted-official-markdown", + "scope": "complete-captured-source" + }, + { + "id": "claude-build-with-claude__prompt-caching", + "provider": "anthropic", + "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching", + "checkedAt": "2026-11-06", + "sha256": "ff35232788f3f7fbd0f9aae002351567a9ea8e68e5b749069d96dab52882747d", + "file": "sources/claude-build-with-claude-prompt-caching.md", + "originalSha256": "ff35232788f3f7fbd0f9aae002351567a9ea8e68e5b749069d96dab52882747d", + "representation": "extracted-official-markdown", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-create", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/api/create-chat-completion", + "checkedAt": "2026-11-06", + "sha256": "b43ca950bd04ae7f6f537b42e6cb729f543d942dcd848ec43ad4e9bfe059fe1f", + "file": "sources/deepseek-create.body", + "originalSha256": "b43ca950bd04ae7f6f537b42e6cb729f543d942dcd848ec43ad4e9bfe059fe1f", + "representation": "received-html-bytes", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-thinking", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/guides/thinking_mode", + "checkedAt": "2026-11-06", + "sha256": "42151b5f86827bff663a61693080a61cdbf99074dee94af756c9fce855baa7cd", + "file": "sources/deepseek-thinking.body", + "originalSha256": "42151b5f86827bff663a61693080a61cdbf99074dee94af756c9fce855baa7cd", + "representation": "received-html-bytes", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-cache", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/guides/kv_cache", + "checkedAt": "2026-11-06", + "sha256": "061c0c7055ceb96d0a522ae1829ff5f7126ff08f26af217643e371abb740a081", + "file": "sources/deepseek-cache.body", + "originalSha256": "061c0c7055ceb96d0a522ae1829ff5f7126ff08f26af217643e371abb740a081", + "representation": "received-html-bytes", + "scope": "complete-captured-source" + }, + { + "id": "openai-gpt-6.1-sol", + "provider": "openai", + "url": "https://developers.openai.com/api/docs/models/gpt-6.1-sol", + "checkedAt": "2026-11-07", + "sha256": "a128083565678e6a47a74a737a891a7df050309df19925db6902535fcb1f5f23", + "file": "sources/openai-gpt-6.1-sol.md", + "originalSha256": "a128083565678e6a47a74a737a891a7df050309df19925db6902535fcb1f5f23", + "representation": "official-documentation-tool-text", + "scope": "complete-captured-source" + }, + { + "id": "openai-gpt-6-astra", + "provider": "openai", + "url": "https://developers.openai.com/api/docs/models/gpt-6-astra", + "checkedAt": "2026-11-07", + "sha256": "7f2f28cf1a8dfdf2557eb1a51f1540e41396397795fe6c39f1f419c922d896ca", + "file": "sources/openai-gpt-6-astra.md", + "originalSha256": "7f2f28cf1a8dfdf2557eb1a51f1540e41396397795fe6c39f1f419c922d896ca", + "representation": "official-documentation-tool-text", + "scope": "complete-captured-source" + }, + { + "id": "openai-gpt-6-sol", + "provider": "openai", + "url": "https://developers.openai.com/api/docs/models/gpt-6-sol", + "checkedAt": "2026-11-07", + "sha256": "cae6df84b71d6ce278072a5e565db585ad8f946fd5a92492a9fdfa23eaca4e7f", + "file": "sources/openai-gpt-6-sol.md", + "originalSha256": "cae6df84b71d6ce278072a5e565db585ad8f946fd5a92492a9fdfa23eaca4e7f", + "representation": "official-documentation-tool-text", + "scope": "complete-captured-source" + }, + { + "id": "openai-gpt-6-luna", + "provider": "openai", + "url": "https://developers.openai.com/api/docs/models/gpt-6-luna", + "checkedAt": "2026-11-07", + "sha256": "be1678c26b17547a9b004286dd18065c9e08dfcaf53cb9e80517284fd1cba76e", + "file": "sources/openai-gpt-6-luna.md", + "originalSha256": "be1678c26b17547a9b004286dd18065c9e08dfcaf53cb9e80517284fd1cba76e", + "representation": "official-documentation-tool-text", + "scope": "complete-captured-source" + }, + { + "id": "openai-gpt-6.1-terra", + "provider": "openai", + "url": "https://developers.openai.com/api/docs/models/gpt-6.1-terra", + "checkedAt": "2026-11-07", + "sha256": "bab1c30e8d49d9be5e7ad0edf90508fb06fffb908123b97c4779f933e8b4bd2a", + "file": "sources/openai-gpt-6.1-terra.md", + "originalSha256": "bab1c30e8d49d9be5e7ad0edf90508fb06fffb908123b97c4779f933e8b4bd2a", + "representation": "official-documentation-tool-text", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-model-list", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/api/list-models", + "checkedAt": "2026-11-07", + "sha256": "5c8a4e4fe7256742a2d11218e6b155bb7210524a048cd0a14e733bee90194723", + "file": "sources/deepseek-model-list.html", + "originalSha256": "5c8a4e4fe7256742a2d11218e6b155bb7210524a048cd0a14e733bee90194723", + "representation": "received-html-bytes", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-models", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/quick_start/pricing", + "checkedAt": "2026-11-07", + "sha256": "af6679690eb9a7838c47727bfc5ffdc4ac91c4445a0c1219741ffe00c076ece5", + "file": "sources/deepseek-models.html", + "originalSha256": "af6679690eb9a7838c47727bfc5ffdc4ac91c4445a0c1219741ffe00c076ece5", + "representation": "received-html-bytes", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-response", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/api/create-response.md", + "checkedAt": "2026-11-07", + "sha256": "5e56e45d25db47f2b6966bbb0b2471d324035c33f0c8f81eaaf8fc444e6869da", + "file": "sources/deepseek-response.md", + "originalSha256": "5e56e45d25db47f2b6966bbb0b2471d324035c33f0c8f81eaaf8fc444e6869da", + "representation": "received-document-bytes", + "scope": "complete-captured-source" + }, + { + "id": "deepseek-message", + "provider": "deepseek", + "url": "https://api-docs.deepseek.com/api/create-message.md", + "checkedAt": "2026-11-07", + "sha256": "46b31d10f429910bf93ea2166537fb803cd2f49f7c5b4ad2ee4f08257b2e17e8", + "file": "sources/deepseek-message.md", + "originalSha256": "46b31d10f429910bf93ea2166537fb803cd2f49f7c5b4ad2ee4f08257b2e17e8", + "representation": "received-document-bytes", + "scope": "complete-captured-source" + }, + { + "id": "claude-effort", + "provider": "anthropic", + "url": "https://platform.claude.com/docs/en/build-with-claude/effort", + "checkedAt": "2026-11-06", + "sha256": "b19219d51d1ced67deb1451b8a0e243b13925d6e49454f0165d45e06a739704d", + "file": "sources/claude-effort.md", + "originalSha256": "b19219d51d1ced67deb1451b8a0e243b13925d6e49454f0165d45e06a739704d", + "representation": "extracted-official-markdown", + "scope": "complete-captured-source" + } + ], + "note": "Pinned official declarations and contract examples; not live-provider evidence. Original whole captures and first failures remain in the owned QA roots." +} diff --git a/tests/fixtures/official-model-registry/sources/claude-build-with-claude-prompt-caching.md b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-prompt-caching.md new file mode 100644 index 00000000..86445928 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-prompt-caching.md @@ -0,0 +1,3384 @@ +--- +title: Prompt caching +url: https://platform.claude.com/docs/en/build-with-claude/prompt-caching +description: Cache prompt prefixes with `cache_control` to cut costs and latency, using automatic caching or explicit breakpoints with 5-minute or 1-hour TTLs. +featureMetadata: + zdr: + eligibility: eligible + note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Your prompts and Claude's outputs are not stored. KV cache representations and cryptographic hashes are held in memory for the cache TTL and promptly deleted after expiry. + supportedModels: + - claude-fable-5-1 + - claude-mythos-5-1 + - claude-fable-5 + - claude-mythos-5 + - claude-mythos-preview + - claude-opus-5-5 + - claude-opus-5 + - claude-sonnet-5-5 + - claude-sonnet-5 + - claude-haiku-5-5 + - claude-haiku-4-5-20251001 + - claude-opus-4-8 + - claude-opus-4-7 + - claude-opus-4-6 + - claude-sonnet-4-6 + - claude-opus-4-5-20251101 + - claude-sonnet-4-5-20250929 + supportedPlatforms: + Claude API: stable + Claude Platform on AWS: stable + Claude Models on Google Cloud (Anthropic managed): stable + Amazon Bedrock: stable + Amazon Bedrock (InvokeModel): stable + Claude Models on Google Cloud (Google managed): stable + Microsoft Foundry: stable +--- + +**API support**: Usage differs by product. + +* **Messages API**: Opt in with `cache_control`, at the top level or on blocks. +* **Managed Agents**: Always on. Cache entries use a 5-minute lifetime by default, and cache reads and writes show up in the session’s usage. + +Prompt caching optimizes your API usage by letting the API resume from specific prefixes in your prompts. This significantly reduces processing time and costs for repetitive tasks or prompts with consistent elements. + +There are two ways to enable prompt caching: + +* **[Automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching):** Add a single `cache_control` field at the top level of your request. The system automatically applies the cache breakpoint to the last cacheable block and moves it forward as conversations grow. Best for multi-turn conversations where the growing message history should be cached automatically. +* **[Explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints):** Place `cache_control` directly on individual content blocks for fine-grained control over exactly what gets cached. + +The simplest way to start is with automatic caching: + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "content-type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "cache_control": {"type": "ephemeral"}, + "system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.", + "messages": [ + { + "role": "user", + "content": "Analyze the major themes in Pride and Prejudice." + } + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + cache_control: + type: ephemeral + system: >- + You are an AI assistant tasked with analyzing literary works. Your goal is + to provide insightful commentary on themes, characters, and writing style. + messages: + - role: user + content: Analyze the major themes in Pride and Prejudice. + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + cache_control={"type": "ephemeral"}, + system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.", + messages=[ + { + "role": "user", + "content": "Analyze the major themes in 'Pride and Prejudice'.", + } + ], + ) + print(response.usage.model_dump_json()) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + cache_control: { type: "ephemeral" }, + system: + "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.", + messages: [ + { + role: "user", + content: "Analyze the major themes in 'Pride and Prejudice'." + } + ] + }); + console.log(response.usage); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + CacheControl = new CacheControlEphemeral(), + System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.", + Messages = + [ + new UserMessageParam { Content = "Analyze the major themes in 'Pride and Prejudice'." } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + CacheControl: anthropic.NewCacheControlEphemeralParam(), + System: []anthropic.TextBlockParam{ + {Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."}, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + .cacheControl(CacheControlEphemeral.builder().build()) + .system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.") + .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.") + .build(); + + Message message = client.messages().create(params); + IO.println(message.usage()); + } + ``` + + ```php PHP + use Anthropic\Messages\CacheControlEphemeral; + use Anthropic\Messages\Model; + // ... + $client = new Client(); + + $response = $client->messages->create( + maxTokens: 1024, + messages: [ + ['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."] + ], + model: Model::CLAUDE_OPUS_5_5, + cacheControl: CacheControlEphemeral::with(), + system: 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.', + ); + echo json_encode($response->usage); + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + response = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + cache_control: {type: "ephemeral"}, + system_: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.", + messages: [ + { + role: "user", + content: "Analyze the major themes in 'Pride and Prejudice'." + } + ] + ) + puts response.usage + ``` + + +With automatic caching, the system caches all content up to and including the last cacheable block. On subsequent requests with the same prefix, cached content is reused automatically. + +*** + +## How prompt caching works + +When you send a request with prompt caching enabled: + +1. The system checks if a prompt prefix, up to a specified cache breakpoint, is already cached from a recent query. +2. If found, it uses the cached version, reducing processing time and costs. +3. Otherwise, it processes the full prompt and caches the prefix once the response starts. + +This is especially useful for: + +* Prompts with many examples +* Large amounts of context or background information +* Repetitive tasks with consistent instructions +* Long multi-turn conversations + +By default, the cache has a 5-minute lifetime. The cache is refreshed for no additional cost each time the cached content is used. + +The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime: if a response takes 4 minutes to stream, a follow-up request that reuses the same cached prefix must start within about 1 minute of that response completing. + + + If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing). + + For more information, see [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). + + + + **Prompt caching caches the full prefix** + + Prompt caching references the entire prompt: `tools`, `system`, and `messages` (in that order), up to and including the block designated with `cache_control`. + + +*** + +## Pricing + +Prompt caching has its own pricing. The following table shows the price per million tokens for each supported model: + +| Model | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ | +| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok | +| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok | +| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok | +| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok | +| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok | +| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok | +| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok | +| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok | +| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok | +| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok | +| Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok | +| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok | +| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok | +| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok | +| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok | +| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok | +| Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok | +| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok | +| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok | +| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok | + +*1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.* + +*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.* + +*All other models use the standard 0.1x multiplier.* + + + The previous table reflects the following pricing multipliers for prompt caching: + + * Cache write tokens with a 5-minute TTL are 1.25 times the base input tokens price. + * Cache write tokens with a 1-hour TTL are 2 times the base input tokens price. + * Cache read tokens are 0.1 times the base input tokens price (see the table footnote for per-model exceptions). + + These multipliers stack with other pricing modifiers such as the Batch API discount, [long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing), and data residency. On a model priced by prompt length, cache reads and cache writes count toward a request’s prompt length. See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for full details. + + +*** + +## Supported models + +Prompt caching (both automatic and explicit) is supported on all [active Claude models](https://platform.claude.com/docs/en/models/overview). + +*** + +## Automatic caching + +Automatic caching is the simplest way to enable prompt caching. Instead of placing `cache_control` on individual content blocks, add a single `cache_control` field at the top level of your request body. The system automatically applies the cache breakpoint to the last cacheable block. + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "content-type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "cache_control": {"type": "ephemeral"}, + "system": "You are a helpful assistant that remembers our conversation.", + "messages": [ + {"role": "user", "content": "My name is Alex. I work on machine learning."}, + {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"}, + {"role": "user", "content": "What did I say I work on?"} + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + cache_control: + type: ephemeral + system: You are a helpful assistant that remembers our conversation. + messages: + - role: user + content: My name is Alex. I work on machine learning. + - role: assistant + content: Nice to meet you, Alex! How can I help with your ML work today? + - role: user + content: What did I say I work on? + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + cache_control={"type": "ephemeral"}, + system="You are a helpful assistant that remembers our conversation.", + messages=[ + {"role": "user", "content": "My name is Alex. I work on machine learning."}, + { + "role": "assistant", + "content": "Nice to meet you, Alex! How can I help with your ML work today?", + }, + {"role": "user", "content": "What did I say I work on?"}, + ], + ) + print(response.usage.model_dump_json()) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + cache_control: { type: "ephemeral" }, + system: "You are a helpful assistant that remembers our conversation.", + messages: [ + { role: "user", content: "My name is Alex. I work on machine learning." }, + { + role: "assistant", + content: "Nice to meet you, Alex! How can I help with your ML work today?" + }, + { role: "user", content: "What did I say I work on?" } + ] + }); + console.log(response.usage); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + CacheControl = new CacheControlEphemeral(), + System = "You are a helpful assistant that remembers our conversation.", + Messages = + [ + new UserMessageParam { Content = "My name is Alex. I work on machine learning." }, + new AssistantMessageParam + { + Content = "Nice to meet you, Alex! How can I help with your ML work today?" + }, + new UserMessageParam { Content = "What did I say I work on?" } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + CacheControl: anthropic.NewCacheControlEphemeralParam(), + System: []anthropic.TextBlockParam{ + {Text: "You are a helpful assistant that remembers our conversation."}, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")), + anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")), + anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + .cacheControl(CacheControlEphemeral.builder().build()) + .system("You are a helpful assistant that remembers our conversation.") + .addUserMessage("My name is Alex. I work on machine learning.") + .addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?") + .addUserMessage("What did I say I work on?") + .build(); + + Message message = client.messages().create(params); + IO.println(message.usage()); + } + ``` + + ```php PHP + use Anthropic\Messages\CacheControlEphemeral; + use Anthropic\Messages\Model; + // ... + $client = new Client(); + + $response = $client->messages->create( + maxTokens: 1024, + messages: [ + ['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'], + ['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'], + ['role' => 'user', 'content' => 'What did I say I work on?'], + ], + model: Model::CLAUDE_OPUS_5_5, + cacheControl: CacheControlEphemeral::with(), + system: 'You are a helpful assistant that remembers our conversation.', + ); + echo json_encode($response->usage); + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + response = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + cache_control: {type: "ephemeral"}, + system_: "You are a helpful assistant that remembers our conversation.", + messages: [ + {role: "user", content: "My name is Alex. I work on machine learning."}, + {role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"}, + {role: "user", content: "What did I say I work on?"} + ] + ) + puts response.usage + ``` + + +### How automatic caching works in multi-turn conversations + +With automatic caching, the cache point moves forward automatically as conversations grow. Each new request caches everything up to the last cacheable block, and previous content is read from cache. + +| Request | Content | Cache behavior | +| --------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| Request 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ cache | Everything written to cache | +| Request 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ cache | System through User(2) read from cache;
Asst(2) + User(3) written to cache | +| Request 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ cache | System through User(3) read from cache;
Asst(3) + User(4) written to cache | + +The cache breakpoint automatically moves to the last cacheable block in each request, so you don’t need to update any `cache_control` markers as the conversation grows. + +### TTL support + +By default, automatic caching uses a 5-minute TTL. You can specify a 1-hour TTL at 2x the base input token price: + +```json +{ "cache_control": { "type": "ephemeral", "ttl": "1h" } } +``` + +### Combining with block-level caching + +Automatic caching is compatible with [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints). When used together, the automatic cache breakpoint uses one of the 4 available breakpoint slots. + +This lets you combine both approaches. For example, use an explicit breakpoint to cache your system prompt, while automatic caching handles the conversation: + +```json +{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "cache_control": { "type": "ephemeral" }, + "system": [ + { + "type": "text", + "text": "You are a helpful assistant.", + "cache_control": { "type": "ephemeral" } + } + ], + "messages": [{ "role": "user", "content": "What are the key terms?" }] +} +``` + +### What stays the same + +Automatic caching uses the same underlying caching infrastructure. Pricing, minimum token thresholds, context ordering requirements, and the 20-block lookback window all apply the same as with explicit breakpoints. + +### Edge cases + +* If the last block already has an explicit `cache_control` with the same TTL, automatic caching is a no-op. +* If the last block has an explicit `cache_control` with a different TTL, the API returns a 400 error. +* If 4 explicit block-level breakpoints already exist, the API returns a 400 error (no slots left for automatic caching). +* If the last block is not eligible as an automatic cache breakpoint target, the system silently walks backward to find the nearest eligible block. If none is found, caching is skipped. + + + Automatic caching is available on every platform except the legacy [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) integration. On that integration, the API returns a 400 error for a top-level `cache_control` field, so use [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) instead. + + +*** + +## Explicit cache breakpoints + +For more control over caching, you can place `cache_control` directly on individual content blocks. This is useful when you need to cache different sections that change at different frequencies, or need fine-grained control over exactly what gets cached. + +### Structuring your prompt + +Place static content (tool definitions, system instructions, context, examples) at the beginning of your prompt. Mark the end of the reusable content for caching using the `cache_control` parameter. + +Cache prefixes are created in the following order: `tools`, `system`, then `messages`. This order forms a hierarchy where each level builds upon the previous ones. + +#### How automatic prefix checking works + +You can use just one cache breakpoint at the end of your static content, and the system automatically finds the longest prefix that a prior request already wrote to the cache. Understanding how this works helps you optimize your caching strategy. + +**Three core principles:** + +1. **Cache writes occur only at your breakpoint.** Marking a block with `cache_control` writes exactly one cache entry: a hash of the prefix ending at that block. The system does not write entries for any earlier position. Because the hash is cumulative, covering everything up to and including the breakpoint, changing any block at or before the breakpoint produces a different hash on the next request. + +2. **Cache reads look backward for entries that prior requests wrote.** On each request the system computes the prefix hash at your breakpoint and checks for a matching cache entry. If none exists, it walks backward one block at a time, checking whether the prefix hash at each earlier position matches something already in the cache. It is looking for prior writes, not for stable content. + +3. **The lookback window is 20 blocks.** The system checks at most 20 positions for each breakpoint, counting the breakpoint itself as the first. If the system finds no matching entry in that window, checking stops (or resumes from the next explicit breakpoint, if any). On the Claude API, a run of consecutive `tool_use` blocks counts as one position, and so does a run of consecutive `tool_result` blocks, so a turn with many parallel tool calls doesn’t push the previous request’s entry out of the window on its own. + +**Example: Lookback in a growing conversation** + +You append new blocks each turn and set `cache_control` on the final block of each request: + +* **Turn 1:** 10 blocks, breakpoint on block 10. No prior cache entries exist. The system writes an entry at block 10. +* **Turn 2:** 15 blocks, breakpoint on block 15. Block 15 has no entry, so the system walks back to block 10 and finds the turn-1 entry. Cache hit at block 10. The system processes only blocks 11 through 15 fresh and writes a new entry at block 15. +* **Turn 3:** 35 blocks, breakpoint on block 35. The system checks 20 positions (blocks 35 through 16) and finds nothing. The turn-2 entry at block 15 is one position outside the window, so there is no cache hit. Adding a second breakpoint at block 15 starts a second lookback window there, which finds the turn-2 entry. + +**Common mistake: Breakpoint on content that changes every request** + +Your prompt has a large static system context (blocks 1 through 5) followed by a per-request block containing a timestamp and the user message (block 6). You set `cache_control` on block 6: + +* **Request 1:** Cache write at block 6. The hash includes the timestamp. +* **Request 2:** The timestamp differs, so the prefix hash at block 6 differs. The lookback walks through blocks 5, 4, 3, 2, and 1, but the system never wrote an entry at any of those positions. No cache hit. You pay for a fresh cache write on every request and never get a read. + +The lookback does not find stable content behind your breakpoint and cache it. It finds entries that prior requests already wrote, and writes occur only at breakpoints. Move `cache_control` to block 5, the last block that stays the same across requests, and every subsequent request reads the cached prefix. [Automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) has the same problem: it places the breakpoint on the last cacheable block, which in this structure is the one that changes every request, so use an explicit breakpoint on block 5 instead. + +**Key takeaway:** Place `cache_control` on the last block whose prefix is identical across the requests you want to share a cache. In a growing conversation the final block works as long as each turn adds fewer than 20 blocks: earlier content never changes, so the next request’s lookback finds the prior write. For a prompt with a varying suffix (timestamps, per-request context, the incoming message), place the breakpoint at the end of the static prefix, not on the varying block. + +#### When to use multiple breakpoints + +You can define up to 4 cache breakpoints if you want to: + +* Cache different sections that change at different frequencies (for example, tools rarely change, but context updates daily) +* Have more control over exactly what gets cached +* Ensure a cache hit when a growing conversation pushes your breakpoint 20 or more blocks past the last cache write + + + **Important limitation:** The lookback can only find entries that earlier requests already wrote. If a growing conversation pushes your breakpoint 20 or more blocks past the last write, the lookback window misses it. Add a second breakpoint closer to that position from the start so a write accumulates there before you need it. + + +### Understanding cache breakpoint costs + +**Cache breakpoints themselves don’t add any cost.** You are only charged for: + +* **Cache writes:** When new content is written to the cache (25 percent more than base input tokens for 5-minute TTL) +* **Cache reads:** When cached content is used (10 percent of base input token price, with [per-model exceptions](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)) +* **Regular input tokens:** For any uncached content + +Adding more `cache_control` breakpoints doesn’t increase your costs; you still pay the same amount based on what content is actually cached and read. The breakpoints give you control over what sections can be cached independently. + +*** + +## Caching strategies and considerations + +### Cache limitations + +On the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), the minimum cacheable prompt length is: + +* 512 tokens for Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), and Claude Haiku 5.5 +* 2,048 tokens for [Claude Mythos Preview](https://anthropic.com/glasswing) and Claude Opus 4.7 +* 4,096 tokens for Claude Opus 4.6 and Claude Opus 4.5 +* 1,024 tokens for Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), and Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)) +* 4,096 tokens for Claude Haiku 4.5 + +These minimums apply on every platform where each model is available. + +Shorter prompts cannot be cached, even if marked with `cache_control`. Any requests to cache fewer than this number of tokens are processed without caching, and no error is returned. To check whether a prompt was cached, look at the [response usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance): if both `cache_creation_input_tokens` and `cache_read_input_tokens` are 0, the prompt was not cached (likely because it did not meet the minimum length requirement). + +If your prompt falls just short of the minimum for your model and platform, expanding the cached content to reach the threshold is often worthwhile. Cache reads cost significantly less than uncached input tokens, so reaching the minimum can reduce costs for frequently reused prompts. + + + [Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) is an AWS-operated platform. On Bedrock, see the [Bedrock prompt caching documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) for the per-model minimums, failure behavior, and usage-field names that apply. + + +For concurrent requests, note that a cache entry only becomes available after the first response starts. If you need cache hits for parallel requests, wait for the first response before sending subsequent requests. + +Currently, `ephemeral` is the only supported cache type, which by default has a 5-minute lifetime. + +### What can be cached + +Most blocks in the request can be cached. This includes: + +* Tools: Tool definitions in the `tools` array +* System messages: Content blocks in the `system` array +* Text messages: Content blocks in the `messages.content` array, for both user and assistant turns +* Images and documents: Content blocks in the `messages.content` array, in user turns +* Tool use and tool results: Content blocks in the `messages.content` array, in both user and assistant turns + +Each of these elements can be cached, either automatically or by marking them with `cache_control`. + +### What cannot be cached + +Although most request blocks can be cached, there are some exceptions: + +* Thinking blocks cannot be cached directly with `cache_control`. However, thinking blocks CAN be cached alongside other content when they appear in previous assistant turns. When cached this way, they DO count as input tokens when read from cache. + +* Sub-content blocks (such as [citations](https://platform.claude.com/docs/en/build-with-claude/citations)) themselves cannot be cached directly. Instead, cache the top-level block. + + In the case of citations, the top-level document content blocks that serve as the source material for citations can be cached. This allows you to use prompt caching with citations effectively by caching the documents that citations reference. + +* Empty text blocks cannot be cached. + +### What invalidates the cache + +Modifications to cached content can invalidate some or all of the cache. + +As described in [Structuring your prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#structuring-your-prompt), the cache follows the hierarchy: `tools` → `system` → `messages`. Changes at each level invalidate that level and all subsequent levels. + +The following table shows which parts of the cache are invalidated by different types of changes. ✘ indicates that the cache is invalidated, whereas ✓ indicates that the cache remains valid. + +| What changes | Tools cache | System cache | Messages cache | Impact | +| ----------------------------------------------------- | -------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Tool definitions** | ✘ | ✘ | ✘ | Modifying tool definitions (names, descriptions, parameters) invalidates the entire cache | +| **Web search toggle** | ✓ | ✘ | ✘ | Enabling/disabling web search modifies the system prompt | +| **Citations toggle** | ✓ | ✘ | ✘ | Enabling/disabling citations modifies the system prompt | +| **Speed setting** | ✓ | ✘ | ✘ | Switching between [`speed: "fast"` and standard speed](https://platform.claude.com/docs/en/build-with-claude/fast-mode) invalidates system and message caches | +| **Tool choice** | ✓ | ✓ | ✘ | Changes to the `tool_choice` parameter only affect message blocks | +| **Images** | ✓ | ✓ | ✘ | Adding/removing images anywhere in the prompt affects message blocks | +| **Thinking parameters** | Model-specific | Model-specific | ✘ | The thinking configuration (mode, and `budget_tokens` in extended mode) is rendered into the prompt, so changing it always invalidates message blocks; tool and system caches are also invalidated on models that render the configuration ahead of them. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). | +| **Effort setting** | Model-specific | Model-specific | ✘ | Changing the [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value always invalidates message blocks, with the same model-specific effect on tool and system caches as thinking parameters. Setting effort explicitly to the model’s default is equivalent to omitting it and does not invalidate. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. | +| **Non-tool results passed to requests with thinking** | ✓ | ✓ | Model-specific | On Opus 4.5+, Sonnet 4.6+, and Haiku 5.5, thinking blocks are preserved by default, so the cache remains valid (✓). On earlier Opus/Sonnet models and Haiku models through Claude Haiku 4.5, all previously-cached thinking blocks are stripped from context, and any messages that follow those thinking blocks are removed from the cache (✘). For more details, see [Caching with thinking blocks](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks). | +| **Dropped thinking blocks** | ✓ | ✓ | ✘ | When the API drops a Claude 5.1 or later model’s thinking block that isn’t [preserved](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) on that request, the cached prefix changes from that block’s position onward on that request. Blocks the receiving model can read, passed back unchanged, keep the cache intact. | + +On models that support [mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), the `inline-tools-2026-09-15` beta header lets you add a tool, or change a tool’s definition, partway through a conversation without editing `tools`. Send the definition in a `tool_addition` block in a mid-conversation system message and leave `tools` exactly as you first sent it. The cached prefix still matches, so only the appended message is processed as new input. The one exception is a `tools` array with no non-deferred tool, where the first tool defined this way costs one full cache miss on that request. See [Define tools in a message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). + + + On Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5, you can add a new system instruction partway through a conversation without invalidating the system or message caches. Append a `{"role": "system"}` message to `messages` instead of editing the top-level `system` field, so the cached prefix stays unchanged. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. See [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). + + +### Tracking cache performance + +Monitor cache performance using these API response fields, within `usage` in the response (or `message_start` event if [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)): + +* `cache_creation_input_tokens`: Number of tokens written to the cache when creating a new entry +* `cache_read_input_tokens`: Number of tokens retrieved from the cache for this request +* `input_tokens`: Number of input tokens that were not read from or used to create a cache (that is, tokens after the last cache breakpoint) + + + **Understanding the token breakdown** + + The `input_tokens` field represents only the tokens that come **after the last cache breakpoint** in your request, not all the input tokens you sent. + + To calculate total input tokens: + + ```text wrap + total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens + ``` + + **Spatial explanation:** + + * `cache_read_input_tokens` = tokens before breakpoint already cached (reads) + * `cache_creation_input_tokens` = tokens before breakpoint being cached now (writes) + * `input_tokens` = tokens after your last breakpoint (not eligible for cache) + + **Example:** If you have a request with 100,000 tokens of cached content (read from cache), 0 tokens of new content being cached, and 50 tokens in your user message (after the cache breakpoint): + + * `cache_read_input_tokens`: 100,000 + * `cache_creation_input_tokens`: 0 + * `input_tokens`: 50 + * **Total input tokens processed:** 100,050 tokens + + This is important for understanding both costs and rate limits, as `input_tokens` is typically much smaller than your total input when using caching effectively. + + +### Caching with thinking blocks + +When using [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) with prompt caching, thinking blocks have special behavior: + +**Automatic caching alongside other content:** Although thinking blocks cannot be explicitly marked with `cache_control`, they get cached as part of the request content when you make subsequent API calls with tool results. This commonly occurs during tool use when you pass thinking blocks back to continue the conversation. + +**Input token counting:** When thinking blocks are read from cache, they count as input tokens in your usage metrics. This is important for cost calculation and token budgeting. + +**Cache invalidation patterns:** + +* Cache remains valid when only tool results are provided as user messages. +* On Opus 4.5+, Sonnet 4.6+, and Haiku 5.5, thinking blocks are preserved by default even when non-tool-result user content is added, so the cache remains valid. +* On earlier Opus/Sonnet models and Haiku models through Claude Haiku 4.5, cache gets invalidated when non-tool-result user content is added, causing all previous thinking blocks to be stripped from context. +* This caching behavior occurs even without explicit `cache_control` markers. + +For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache). + +**Example with tool use:** + +```text wrap +Request 1: User: "What's the weather in Paris?" +Response: [thinking_block_1] + [tool_use block 1] + +Request 2: +User: ["What's the weather in Paris?"], +Assistant: [thinking_block_1] + [tool_use block 1], +User: [tool_result_1, cache=True] +Response: [thinking_block_2] + [text block 2] +# Request 2 caches its request content (not the response) +# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1 + +Request 3: +User: ["What's the weather in Paris?"], +Assistant: [thinking_block_1] + [tool_use block 1], +User: [tool_result_1, cache=True], +Assistant: [thinking_block_2] + [text block 2], +User: [Text response, cache=True] +# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph) +``` + +On earlier Opus/Sonnet models and Haiku models through Claude Haiku 4.5, all previous thinking blocks are removed from context at this point. On Opus 4.5+, Sonnet 4.6+, and Haiku 5.5, prior thinking blocks are kept by default and remain part of the cached prefix. + +For more detailed information, see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). + +### Cache storage and sharing + + + Prompt caching uses [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces)-level isolation. Caches are isolated by workspace, ensuring data separation between workspaces within the same organization. This applies to the Claude API, Claude Platform on AWS, and Microsoft Foundry; Claude Models on Google Cloud (Google managed) and Bedrock maintain organization-level cache isolation. If you use multiple workspaces, review your caching strategy to account for this difference. + + +* **Organization and workspace isolation:** Caches are isolated between organizations. Different organizations never share caches, even if they use identical prompts. Caches are also isolated by workspace within an organization on the Claude API, Claude Platform on AWS, and Microsoft Foundry; Claude Models on Google Cloud (Google managed) and Bedrock use organization-level isolation only. + +* **Exact matching:** Cache hits require 100 percent identical prompt segments, including all text and images up to and including the block marked with cache control. + +* **Output token generation:** Prompt caching has no effect on output token generation. The response you receive is identical to what you would get if prompt caching were not used. + +### Best practices for effective caching + +To optimize prompt caching performance: + +* Start with [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) for multi-turn conversations. It handles breakpoint management automatically. +* Use [explicit block-level breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) when you need to cache different sections with different change frequencies. +* Cache stable, reusable content such as system instructions, background information, large contexts, or frequent tool definitions. +* Place cached content at the prompt’s beginning for best performance. +* Use cache breakpoints strategically to separate different cacheable prefix sections. +* Place the breakpoint on the last block that stays identical across requests. For a prompt with a static prefix and a varying suffix (timestamps, per-request context, the incoming message), that is the end of the prefix, not the varying block. +* Regularly analyze cache hit rates and adjust your strategy as needed. + +### Optimizing for different use cases + +Tailor your prompt caching strategy to your scenario: + +* Conversational agents: Reduce cost and latency for extended conversations, especially those with long instructions or uploaded documents. +* Coding assistants: Improve auto-complete and code base Q\&A by keeping relevant sections or a summarized version of the code base in the prompt. +* Large document processing: Incorporate complete long-form material including images in your prompt without increasing response latency. +* Detailed instruction sets: Share extensive lists of instructions, procedures, and examples to fine-tune Claude’s responses. Developers often include an example or two in the prompt, but with prompt caching you can get even better performance by including 20+ diverse examples of high-quality answers. +* Agentic tool use: Enhance performance for scenarios involving multiple tool calls and iterative code changes, where each step typically requires a new API call. +* Books, papers, documentation, podcast transcripts, and other long-form content: Make any knowledge base interactive by embedding the entire document(s) into the prompt, and letting users ask it questions. + +### Troubleshooting common issues + +If you experience unexpected behavior: + + + [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) has the API compare consecutive requests and report where the prompt prefix diverged, which automatically handles many of the steps in this list. + + +* Ensure cached sections are identical across calls. For explicit breakpoints, verify that `cache_control` markers are in the same locations. +* Check that calls are made within the cache lifetime (5 minutes by default). +* Verify that `tool_choice`, image usage, the thinking configuration, and `output_config.effort` remain consistent between calls. +* Validate that you are caching at least the minimum number of tokens for your model and platform (see [Cache limitations](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations)). +* Confirm your breakpoint is on a block that stays identical across requests. Cache writes occur only at the breakpoint, and if that block changes (timestamps, per-request context, the incoming message), the prefix hash never matches. The lookback does not find stable content behind the breakpoint; it only finds entries that earlier requests wrote at their own breakpoints. +* Verify that the keys in your `tool_use` content blocks have stable ordering as some languages (for example, Swift, Go) randomize key order during JSON conversion, breaking caches. +* Use [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) to have the API compare consecutive requests and report which part of the prompt diverged. + + + Changes to `tool_choice` or the presence/absence of images anywhere in the prompt invalidate the cache, requiring a new cache entry to be created. For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache). + + +*** + +## 1-hour cache duration + +If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing). + + + The 1-hour cache duration is available on the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). + + +To use the extended cache, include `ttl` in the `cache_control` definition like this: + +```json +"cache_control": { + "type": "ephemeral", + "ttl": "1h" +} +``` + +The response includes detailed cache information like the following: + +```json Output +{ + "usage": { + "input_tokens": 2048, + "cache_read_input_tokens": 1800, + "cache_creation_input_tokens": 248, + "output_tokens": 503, + + "cache_creation": { + "ephemeral_5m_input_tokens": 148, + "ephemeral_1h_input_tokens": 100 + } + } +} +``` + +The `cache_creation_input_tokens` field equals the sum of the values in the `cache_creation` object. + +If you see `ephemeral_5m_input_tokens` writes you didn’t request while using server tools such as web search, see [Server tool results are cached automatically](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically). + +### When to use the 1-hour cache + +If you use a prompt at a regular cadence (for example, a system prompt that you send more often than every 5 minutes), continue to use the 5-minute cache, because it keeps refreshing at no additional charge. + +The 1-hour cache is best used in the following scenarios: + +* When you have prompts that are likely used less frequently than every 5 minutes, but more frequently than every hour. For example, when an agentic side-agent takes longer than 5 minutes, or when storing a long chat conversation with a user and you generally expect that user might not respond in the next 5 minutes. +* When latency is important and your follow-up prompts might be sent beyond 5 minutes. +* When you want to improve your rate limit utilization, because cache hits are not deducted against your rate limit. + + + The 5-minute and 1-hour caches behave the same with respect to latency. You generally see improved time-to-first-token for long documents. + + +### Mixing different TTLs + +You can use both 1-hour and 5-minute cache controls in the same request, but with an important constraint: Cache entries with longer TTL must appear before shorter TTLs (that is, a 1-hour cache entry must appear before any 5-minute cache entries). + +When mixing TTLs, the Claude API determines three billing locations in your prompt: + +1. Position `A`: The token count at the last cache hit in your prompt (or 0 if no hits). + + * A hit on an entry cached with a 5-minute TTL doesn’t count if a 1-hour `cache_control` block after it is a cache miss. + * A request that reads an entry cached with a 5-minute TTL restarts its 5-minute lifetime, even if the request now sets `"ttl": "1h"`. + +2. Position `B`: The token count at the last 1-hour `cache_control` block after `A` (or equals `A` if none exist). + +3. Position `C`: The token count at the last `cache_control` block. + + + If `B` or `C` is larger than `A`, it is necessarily a cache miss. + + +You are charged for: + +1. Cache read tokens for `A`. +2. 1-hour cache write tokens for `(B - A)`. +3. 5-minute cache write tokens for `(C - B)`. + +Here are three example requests, each with different cache hits and cache misses. Each has a different calculated price, shown in the boxes. + + + ![Three requests with different cache hits and misses: A, B, and C mark where reads, 1-hour writes, and 5-minute writes end](https://platform.claude.com/docs/images/prompt-cache-mixed-ttl.svg) + + +*** + +## Pre-warming the cache + +Cache pre-warming lets you load your system prompt or tool definitions into the prompt cache before a user triggers a real request. This eliminates the cache-miss latency penalty on the first user interaction, reducing time-to-first-token (TTFT) for latency-sensitive applications. + +### How it works + +Set `max_tokens: 0` in your request. The API reads your prompt into the model and writes the cache at any `cache_control` breakpoint, then returns immediately without generating any output. The response has an empty `content` array, `stop_reason: "max_tokens"`, and a fully populated `usage` block. + +Place the `cache_control` breakpoint on the last block that is shared with the follow-up request (typically your system prompt or tool definitions), not on the placeholder user message. Otherwise the cache entry is keyed to the placeholder and the follow-up request won’t hit it. Use the same thinking configuration and `output_config.effort` as your follow-up requests too: those values are rendered into the prompt (see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache)), so a pre-warm with a different configuration can write an entry your real traffic never hits. This means using an [explicit cache breakpoint](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) rather than [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching), because automatic caching places the breakpoint on the last block, which here is the placeholder. The placeholder user message can be any string with non-whitespace content (the examples here use `"warmup"`); its content is read into the model but never answered. + + + A pre-warm request incurs a **cache write** charge if the prefix is not already cached, the same as any other request. Check `usage.cache_creation_input_tokens` in the response to confirm a write occurred. Zero output tokens are billed. + + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "content-type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 0, + "system": [ + { + "type": "text", + "text": "You are an expert software engineer with deep knowledge of distributed systems...", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [{"role": "user", "content": "warmup"}] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 0 + system: + - type: text + text: >- + You are an expert software engineer with deep knowledge of + distributed systems... + cache_control: + type: ephemeral + messages: + - role: user + content: warmup + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + # Fire this before users arrive to warm the shared system-prompt cache. + prewarm = client.messages.create( + model="claude-opus-5-5", + max_tokens=0, + system=[ + { + "type": "text", + "text": "You are an expert software engineer with deep knowledge of distributed systems...", + "cache_control": {"type": "ephemeral"}, + } + ], + messages=[{"role": "user", "content": "warmup"}], + ) + print(prewarm.stop_reason) # "max_tokens" + print(prewarm.content) # [] + print(prewarm.usage) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + // Fire this before users arrive to warm the shared system-prompt cache. + const prewarm = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 0, + system: [ + { + type: "text", + text: "You are an expert software engineer with deep knowledge of distributed systems...", + cache_control: { type: "ephemeral" } + } + ], + messages: [{ role: "user", content: "warmup" }] + }); + console.log(prewarm.stop_reason); // "max_tokens" + console.log(prewarm.content); // [] + console.log(prewarm.usage); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var prewarm = await client.Messages.Create( + new() + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 0, + System = new( + [ + new TextBlockParam + { + Text = "You are an expert software engineer with deep knowledge of distributed systems...", + CacheControl = new(), + }, + ] + ), + Messages = [new UserMessageParam { Content = "warmup" }], + } + ); + + Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens" + Console.WriteLine(prewarm.Content.Count); // 0 + Console.WriteLine(prewarm.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 0, + System: []anthropic.TextBlockParam{ + { + Text: "You are an expert software engineer with deep knowledge of distributed systems...", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")), + }, + }) + if err != nil { + panic(err) + } + + fmt.Println(prewarm.StopReason) // "max_tokens" + fmt.Println(prewarm.Content) // [] + fmt.Println(prewarm.Usage.RawJSON()) + ``` + + ```java Java + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + Message prewarm = client.messages().create(MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(0) + .systemOfTextBlockParams(List.of(TextBlockParam.builder() + .text("You are an expert software engineer with deep knowledge of distributed systems...") + .cacheControl(CacheControlEphemeral.builder().build()) + .build())) + .addUserMessage("warmup") + .build()); + + IO.println(prewarm.stopReason()); // Optional[max_tokens] + IO.println(prewarm.content()); // [] + IO.println(prewarm.usage()); + ``` + + ```php PHP + $client = new Client(); + + $prewarm = $client->messages->create( + model: Model::CLAUDE_OPUS_5_5, + maxTokens: 0, + system: [ + [ + 'type' => 'text', + 'text' => 'You are an expert software engineer with deep knowledge of distributed systems...', + 'cache_control' => ['type' => 'ephemeral'], + ], + ], + messages: [['role' => 'user', 'content' => 'warmup']], + ); + + echo $prewarm->stopReason, PHP_EOL; // "max_tokens" + echo json_encode($prewarm->content), PHP_EOL; // [] + echo json_encode($prewarm->usage), PHP_EOL; + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + prewarm = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 0, + system_: [ + { + type: "text", + text: "You are an expert software engineer with deep knowledge of distributed systems...", + cache_control: {type: "ephemeral"} + } + ], + messages: [{role: "user", content: "warmup"}] + ) + + puts prewarm.stop_reason # :max_tokens + puts prewarm.content # [] + puts prewarm.usage + ``` + + +The API returns an empty `content` array: + +```json Output +{ + "id": "msg_01XFDUDYJgAACzvnptvVoYEL", + "type": "message", + "role": "assistant", + "content": [], + "model": "claude-opus-5-5", + "stop_reason": "max_tokens", + "stop_sequence": null, + "usage": { + "input_tokens": 8, + "cache_creation_input_tokens": 5120, + "cache_read_input_tokens": 0, + "cache_creation": { + "ephemeral_5m_input_tokens": 5120, + "ephemeral_1h_input_tokens": 0 + }, + "iterations": [ + { + "input_tokens": 8, + "output_tokens": 0, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 5120, + "cache_creation": { + "ephemeral_5m_input_tokens": 5120, + "ephemeral_1h_input_tokens": 0 + }, + "type": "message" + } + ], + "output_tokens": 0, + "service_tier": "standard", + "inference_geo": "global" + } +} +``` + +### Typical usage pattern + +Make a pre-warm request when your application starts (or on a scheduled interval), then send real user requests after the pre-warm completes: + + + ```bash cURL + # Warm the cache at application startup or on a scheduled interval. + curl https://api.anthropic.com/v1/messages \ + -H "content-type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 0, + "system": [ + { + "type": "text", + "text": "You are an expert software engineer with deep knowledge of distributed systems...", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [{"role": "user", "content": "warmup"}] + }' + + # Later, when the user submits a message, the system-prompt prefix is already cached. + curl https://api.anthropic.com/v1/messages \ + -H "content-type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "system": [ + { + "type": "text", + "text": "You are an expert software engineer with deep knowledge of distributed systems...", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [{"role": "user", "content": "How do I implement a binary search tree?"}] + }' + ``` + + ```bash CLI + # Warm the cache at application startup or on a scheduled interval. + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 0 + system: + - type: text + text: >- + You are an expert software engineer with deep knowledge of + distributed systems... + cache_control: + type: ephemeral + messages: + - role: user + content: warmup + YAML + + # Later, when the user submits a message, the system-prompt prefix is already cached. + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + system: + - type: text + text: >- + You are an expert software engineer with deep knowledge of + distributed systems... + cache_control: + type: ephemeral + messages: + - role: user + content: How do I implement a binary search tree? + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + SYSTEM_PROMPT = [ + { + "type": "text", + "text": "You are an expert software engineer with deep knowledge of distributed systems...", + "cache_control": {"type": "ephemeral"}, + } + ] + + + def prewarm_cache() -> None: + """Call this at application startup or on a scheduled interval.""" + client.messages.create( + model="claude-opus-5-5", + max_tokens=0, + system=SYSTEM_PROMPT, + messages=[{"role": "user", "content": "warmup"}], + ) + + + def respond(user_message: str) -> anthropic.types.Message: + """The real user request; benefits from a warm cache.""" + return client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + system=SYSTEM_PROMPT, + messages=[{"role": "user", "content": user_message}], + ) + + + # Warm the cache before any user traffic arrives. + prewarm_cache() + + # Later, when the user submits a message, the system-prompt prefix is already cached. + response = respond("How do I implement a binary search tree?") + for block in response.content: + if block.type == "text": + print(block.text) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [ + { + type: "text", + text: "You are an expert software engineer with deep knowledge of distributed systems...", + cache_control: { type: "ephemeral" } + } + ]; + + // Call this at application startup or on a scheduled interval. + async function prewarmCache(): Promise { + await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 0, + system: SYSTEM_PROMPT, + messages: [{ role: "user", content: "warmup" }] + }); + } + + // The real user request; benefits from a warm cache. + async function respond(userMessage: string): Promise { + return client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + system: SYSTEM_PROMPT, + messages: [{ role: "user", content: userMessage }] + }); + } + + // Warm the cache before any user traffic arrives. + await prewarmCache(); + + // Later, when the user submits a message, the system-prompt prefix is already cached. + const response = await respond("How do I implement a binary search tree?"); + const textBlock = response.content.find((block) => block.type === "text"); + console.log(textBlock?.text); + ``` + + ```csharp C# + AnthropicClient client = new(); + + List systemPrompt = + [ + new TextBlockParam + { + Text = "You are an expert software engineer with deep knowledge of distributed systems...", + CacheControl = new(), + }, + ]; + + // Call this at application startup or on a scheduled interval. + async Task PrewarmCache() => + await client.Messages.Create( + new() + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 0, + System = new(systemPrompt), + Messages = [new UserMessageParam { Content = "warmup" }], + } + ); + + // The real user request; benefits from a warm cache. + async Task Respond(string userMessage) => + await client.Messages.Create( + new() + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + System = new(systemPrompt), + Messages = [new UserMessageParam { Content = userMessage }], + } + ); + + // Warm the cache before any user traffic arrives. + await PrewarmCache(); + + // Later, when the user submits a message, the system-prompt prefix is already cached. + var response = await Respond("How do I implement a binary search tree?"); + foreach (var block in response.Content) + { + if (block.TryPickText(out var textBlock)) + { + Console.WriteLine(textBlock.Text); + } + } + ``` + + ```go Go + var client = anthropic.NewClient() + + var systemPrompt = []anthropic.TextBlockParam{ + { + Text: "You are an expert software engineer with deep knowledge of distributed systems...", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + } + + // Call this at application startup or on a scheduled interval. + func prewarmCache() error { + _, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 0, + System: systemPrompt, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")), + }, + }) + return err + } + + // The real user request; benefits from a warm cache. + func respond(userMessage string) (*anthropic.Message, error) { + return client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + System: systemPrompt, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)), + }, + }) + } + + func main() { + // Warm the cache before any user traffic arrives. + if err := prewarmCache(); err != nil { + log.Fatal(err) + } + + // Later, when the user submits a message, the system-prompt prefix is already cached. + response, err := respond("How do I implement a binary search tree?") + if err != nil { + log.Fatal(err) + } + for _, block := range response.Content { + if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { + fmt.Println(textBlock.Text) + } + } + } + ``` + + ```java Java + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + List systemPrompt = List.of(TextBlockParam.builder() + .text("You are an expert software engineer with deep knowledge of distributed systems...") + .cacheControl(CacheControlEphemeral.builder().build()) + .build()); + + // Call this at application startup or on a scheduled interval. + void prewarmCache() { + client.messages().create(MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(0) + .systemOfTextBlockParams(systemPrompt) + .addUserMessage("warmup") + .build()); + } + + // The real user request; benefits from a warm cache. + Message respond(String userMessage) { + return client.messages().create(MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + .systemOfTextBlockParams(systemPrompt) + .addUserMessage(userMessage) + .build()); + } + + void main() { + // Warm the cache before any user traffic arrives. + prewarmCache(); + + // Later, when the user submits a message, the system-prompt prefix is already cached. + Message response = respond("How do I implement a binary search tree?"); + response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> IO.println(textBlock.text())); + } + ``` + + ```php PHP + $client = new Client(); + + $systemPrompt = [ + [ + 'type' => 'text', + 'text' => 'You are an expert software engineer with deep knowledge of distributed systems...', + 'cache_control' => ['type' => 'ephemeral'], + ], + ]; + + // Call this at application startup or on a scheduled interval. + $prewarmCache = fn () => $client->messages->create( + model: Model::CLAUDE_OPUS_5_5, + maxTokens: 0, + system: $systemPrompt, + messages: [['role' => 'user', 'content' => 'warmup']], + ); + + // The real user request; benefits from a warm cache. + $respond = fn (string $userMessage) => $client->messages->create( + model: Model::CLAUDE_OPUS_5_5, + maxTokens: 1024, + system: $systemPrompt, + messages: [['role' => 'user', 'content' => $userMessage]], + ); + + // Warm the cache before any user traffic arrives. + $prewarmCache(); + + // Later, when the user submits a message, the system-prompt prefix is already cached. + $response = $respond('How do I implement a binary search tree?'); + foreach ($response->content as $block) { + if ($block instanceof \Anthropic\Messages\TextBlock) { + echo $block->text, PHP_EOL; + } + } + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + SYSTEM_PROMPT = [ + { + type: "text", + text: "You are an expert software engineer with deep knowledge of distributed systems...", + cache_control: {type: "ephemeral"} + } + ] + + # Call this at application startup or on a scheduled interval. + def prewarm_cache(client) + client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 0, + system_: SYSTEM_PROMPT, + messages: [{role: "user", content: "warmup"}] + ) + end + + # The real user request; benefits from a warm cache. + def respond(client, user_message) + client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + system_: SYSTEM_PROMPT, + messages: [{role: "user", content: user_message}] + ) + end + + # Warm the cache before any user traffic arrives. + prewarm_cache(client) + + # Later, when the user submits a message, the system-prompt prefix is already cached. + response = respond(client, "How do I implement a binary search tree?") + response.content.each do |block| + puts block.text if block.is_a?(Anthropic::Models::TextBlock) + end + ``` + + +Keep in mind that the cache TTL still applies. For the default 5-minute cache, send a new pre-warm request at least every 5 minutes to keep the cache warm. For longer gaps between user requests, use the [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) instead. + +### Limitations + +A `max_tokens: 0` request is rejected with an `invalid_request_error` if any of the following are set, because each implies output that a zero-token budget cannot produce: + +* `stream: true` +* [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) (`thinking.type: "enabled"`) +* [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) (`output_config.format`) +* `tool_choice` of `{"type": "tool", ...}` or `{"type": "any"}` + +`max_tokens: 0` is also rejected inside a [Message Batches](https://platform.claude.com/docs/en/build-with-claude/batch-processing) request. Pre-warming targets time-to-first-token, which does not apply to batch processing, and a cache entry written during batch processing would likely expire before the follow-up request runs. + +### Replacing the `max_tokens=1` workaround + +Some applications send `max_tokens: 1` requests to warm the cache. Prefer `max_tokens: 0` where the request allows it: no output is produced, so there is no single-token reply to discard, no output tokens are billed, and the intent of the request is unambiguous. + +*** + +## Prompt caching examples + +To help you get started with prompt caching, the [prompt caching recipe](https://platform.claude.com/cookbook/misc-prompt-caching) in the Claude Cookbook provides detailed examples and best practices. + +The following code snippets showcase various prompt caching patterns. These examples demonstrate how to implement caching in different scenarios, helping you understand the practical applications of this feature: + + + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "system": [ + { + "type": "text", + "text": "You are an AI assistant tasked with analyzing legal documents." + }, + { + "type": "text", + "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [ + { + "role": "user", + "content": "What are the key terms and conditions in this agreement?" + } + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + system: + - type: text + text: You are an AI assistant tasked with analyzing legal documents. + - type: text + text: >- + Here is the full text of a complex legal agreement: + [Insert full text of a 50-page legal agreement here] + cache_control: + type: ephemeral + messages: + - role: user + content: What are the key terms and conditions in this agreement? + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + system=[ + { + "type": "text", + "text": "You are an AI assistant tasked with analyzing legal documents.", + }, + { + "type": "text", + "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + "cache_control": {"type": "ephemeral"}, + }, + ], + messages=[ + { + "role": "user", + "content": "What are the key terms and conditions in this agreement?", + } + ], + ) + print(response.usage.model_dump_json()) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + system: [ + { + type: "text", + text: "You are an AI assistant tasked with analyzing legal documents." + }, + { + type: "text", + text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + { + role: "user", + content: "What are the key terms and conditions in this agreement?" + } + ] + }); + console.log(response.usage); + ``` + + ```csharp C# + AnthropicClient client = new() + { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") + }; + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + System = new MessageCreateParamsSystem(new List + { + new TextBlockParam() + { + Text = "You are an AI assistant tasked with analyzing legal documents.", + }, + new TextBlockParam() + { + Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + CacheControl = new CacheControlEphemeral(), + }, + }), + Messages = + [ + new UserMessageParam + { + Content = "What are the key terms and conditions in this agreement?" + } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + System: []anthropic.TextBlockParam{ + { + Text: "You are an AI assistant tasked with analyzing legal documents.", + }, + { + Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + .systemOfTextBlockParams( + List.of( + TextBlockParam.builder() + .text("You are an AI assistant tasked with analyzing legal documents.") + .build(), + TextBlockParam.builder() + .text( + "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]" + ) + .cacheControl(CacheControlEphemeral.builder().build()) + .build() + ) + ) + .addUserMessage("What are the key terms and conditions in this agreement?") + .build(); + + Message message = client.messages().create(params); + IO.println(message.usage()); + } + ``` + + ```php PHP + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 1024, + messages: [ + [ + 'role' => 'user', + 'content' => 'What are the key terms and conditions in this agreement?' + ] + ], + model: Model::CLAUDE_OPUS_5_5, + system: [ + [ + 'type' => 'text', + 'text' => 'You are an AI assistant tasked with analyzing legal documents.' + ], + [ + 'type' => 'text', + 'text' => 'Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]', + 'cache_control' => ['type' => 'ephemeral'] + ] + ], + ); + + echo json_encode($message->usage), PHP_EOL; + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + system_: [ + { + type: "text", + text: "You are an AI assistant tasked with analyzing legal documents." + }, + { + type: "text", + text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + { + role: "user", + content: "What are the key terms and conditions in this agreement?" + } + ] + ) + puts message.usage + ``` + + + This example demonstrates basic prompt caching usage, caching the full text of the legal agreement as a prefix while keeping the user instruction uncached. + + For the first request: + + * `input_tokens`: Number of tokens in the user message only + * `cache_creation_input_tokens`: Number of tokens in the entire system message, including the legal document + * `cache_read_input_tokens`: 0 (no cache hit on first request) + + For subsequent requests within the cache lifetime: + + * `input_tokens`: Number of tokens in the user message only + * `cache_creation_input_tokens`: 0 (no new cache creation) + * `cache_read_input_tokens`: Number of tokens in the entire cached system message + + + + Tool definitions can be cached by placing `cache_control` on the last tool in your `tools` array. All tools defined before and including that tool are cached as a single prefix. + + ```json + { + "model": "claude-opus-5-5", + "max_tokens": 1024, + "tools": [ + { + "name": "get_weather", + "description": "Get the current weather in a given location", + "input_schema": { + "type": "object", + "properties": { "location": { "type": "string" } }, + "required": ["location"] + } + }, + { + "name": "get_time", + "description": "Get the current time in a given time zone", + "input_schema": { + "type": "object", + "properties": { "timezone": { "type": "string" } }, + "required": ["timezone"] + }, + "cache_control": { "type": "ephemeral" } + } + ], + "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }] + } + ``` + + On the first request, `cache_creation_input_tokens` reflects the token count of all tool definitions. On subsequent requests within the cache lifetime, those tokens appear under `cache_read_input_tokens` instead. + + For detailed interaction between tool definitions, `defer_loading`, and cache invalidation, see [Tool use with prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching). + + + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "system": [ + { + "type": "text", + "text": "...long system prompt", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Hello, can you tell me more about the solar system?" + } + ] + }, + { + "role": "assistant", + "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?" + }, + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Good to know." + }, + { + "type": "text", + "text": "Tell me more about Mars.", + "cache_control": {"type": "ephemeral"} + } + ] + } + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + system: + - type: text + text: "...long system prompt" + cache_control: + type: ephemeral + messages: + - role: user + content: + - type: text + text: Hello, can you tell me more about the solar system? + - role: assistant + content: >- + Certainly! The solar system is the collection of celestial bodies that + orbit our Sun. It consists of eight planets, numerous moons, asteroids, + comets, and other objects. The planets, in order from closest to farthest + from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, + and Neptune. Each planet has its own unique characteristics and features. + Is there a specific aspect of the solar system you would like to know + more about? + - role: user + content: + - type: text + text: Good to know. + - type: text + text: Tell me more about Mars. + cache_control: + type: ephemeral + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + system=[ + { + "type": "text", + "text": "...long system prompt", + "cache_control": {"type": "ephemeral"}, + } + ], + messages=[ + # ...long conversation so far + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Hello, can you tell me more about the solar system?", + } + ], + }, + { + "role": "assistant", + "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?", + }, + { + "role": "user", + "content": [ + {"type": "text", "text": "Good to know."}, + { + "type": "text", + "text": "Tell me more about Mars.", + "cache_control": {"type": "ephemeral"}, + }, + ], + }, + ], + ) + print(response.usage.model_dump_json()) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + system: [ + { + type: "text", + text: "...long system prompt", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + // ...long conversation so far + { + role: "user", + content: [ + { + type: "text", + text: "Hello, can you tell me more about the solar system?" + } + ] + }, + { + role: "assistant", + content: + "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?" + }, + { + role: "user", + content: [ + { + type: "text", + text: "Good to know." + }, + { + type: "text", + text: "Tell me more about Mars.", + cache_control: { type: "ephemeral" } + } + ] + } + ] + }); + console.log(response.usage); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + System = new MessageCreateParamsSystem(new List + { + new TextBlockParam() + { + Text = "...long system prompt", + CacheControl = new CacheControlEphemeral(), + }, + }), + Messages = + [ + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")), + }, + }, + new AssistantMessageParam + { + Content = "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?" + }, + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam("Good to know.")), + new ContentBlockParam(new TextBlockParam() + { + Text = "Tell me more about Mars.", + CacheControl = new CacheControlEphemeral(), + }), + } + } + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + System: []anthropic.TextBlockParam{ + { + Text: "...long system prompt", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")), + anthropic.NewAssistantMessage(anthropic.NewTextBlock("Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?")), + anthropic.NewUserMessage( + anthropic.NewTextBlock("Good to know."), + anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{ + Text: "Tell me more about Mars.", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }}, + ), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + // Create ephemeral system prompt + TextBlockParam systemPrompt = TextBlockParam.builder() + .text("...long system prompt") + .cacheControl(CacheControlEphemeral.builder().build()) + .build(); + + // Create message params + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + .systemOfTextBlockParams(List.of(systemPrompt)) + // First user message (without cache control) + .addUserMessage("Hello, can you tell me more about the solar system?") + // Assistant response + .addAssistantMessage( + "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?" + ) + // Second user message (with cache control) + .addUserMessageOfContentBlockParams( + List.of( + ContentBlockParam.ofText(TextBlockParam.builder() + .text("Good to know.") + .build()), + ContentBlockParam.ofText( + TextBlockParam.builder() + .text("Tell me more about Mars.") + .cacheControl(CacheControlEphemeral.builder().build()) + .build() + ) + ) + ) + .build(); + + Message message = client.messages().create(params); + IO.println(message.usage()); + } + ``` + + ```php PHP + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 1024, + messages: [ + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'text', + 'text' => 'Hello, can you tell me more about the solar system?' + ] + ] + ], + [ + 'role' => 'assistant', + 'content' => 'Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?' + ], + [ + 'role' => 'user', + 'content' => [ + ['type' => 'text', 'text' => 'Good to know.'], + [ + 'type' => 'text', + 'text' => 'Tell me more about Mars.', + 'cache_control' => ['type' => 'ephemeral'] + ] + ] + ] + ], + model: Model::CLAUDE_OPUS_5_5, + system: [ + [ + 'type' => 'text', + 'text' => '...long system prompt', + 'cache_control' => ['type' => 'ephemeral'] + ] + ], + ); + + echo json_encode($message->usage), PHP_EOL; + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + system_: [ + { + type: "text", + text: "...long system prompt", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "Hello, can you tell me more about the solar system?" + } + ] + }, + { + role: "assistant", + content: "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?" + }, + { + role: "user", + content: [ + { type: "text", text: "Good to know." }, + { + type: "text", + text: "Tell me more about Mars.", + cache_control: { type: "ephemeral" } + } + ] + } + ] + ) + puts message.usage + ``` + + + This example demonstrates how to use prompt caching in a multi-turn conversation. + + During each turn, the final block of the final message is marked with `cache_control` so the conversation can be incrementally cached. The system automatically looks up and uses the longest previously cached sequence of blocks for follow-up messages. Blocks that were marked with `cache_control` on an earlier turn aren’t marked again, but a request within 5 minutes still reads them from the cache and refreshes their lifetime. + + The `cache_control` parameter is also on the system message. If the system message is evicted from the cache after more than 5 minutes without use, the next request adds it back. + + This approach is useful for maintaining context in ongoing conversations without repeatedly processing the same information. + + When this is set up properly, you should see the following in the usage response of each request: + + * `input_tokens`: Number of tokens in the new user message (minimal) + * `cache_creation_input_tokens`: Number of tokens in the new assistant and user turns + * `cache_read_input_tokens`: Number of tokens in the conversation up to the previous turn + + + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 1024, + "tools": [ + { + "name": "search_documents", + "description": "Search through the knowledge base", + "input_schema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Search query" + } + }, + "required": ["query"] + } + }, + { + "name": "get_document", + "description": "Retrieve a specific document by ID", + "input_schema": { + "type": "object", + "properties": { + "doc_id": { + "type": "string", + "description": "Document ID" + } + }, + "required": ["doc_id"] + }, + "cache_control": {"type": "ephemeral"} + } + ], + "system": [ + { + "type": "text", + "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + "cache_control": {"type": "ephemeral"} + }, + { + "type": "text", + "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [ + { + "role": "user", + "content": "Can you search for information about Mars rovers?" + }, + { + "role": "assistant", + "content": [ + { + "type": "tool_use", + "id": "tool_1", + "name": "search_documents", + "input": {"query": "Mars rovers"} + } + ] + }, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "tool_1", + "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)" + } + ] + }, + { + "role": "assistant", + "content": [ + { + "type": "text", + "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document." + } + ] + }, + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Yes, please tell me about the Perseverance rover specifically.", + "cache_control": {"type": "ephemeral"} + } + ] + } + ] + }' + ``` + + ```bash CLI + ant messages create <<'YAML' + model: claude-opus-5-5 + max_tokens: 1024 + tools: + - name: search_documents + description: Search through the knowledge base + input_schema: + type: object + properties: + query: + type: string + description: Search query + required: [query] + - name: get_document + description: Retrieve a specific document by ID + input_schema: + type: object + properties: + doc_id: + type: string + description: Document ID + required: [doc_id] + cache_control: + type: ephemeral + system: + - type: text + text: |- + You are a helpful research assistant with access to a document knowledge base. + + # Instructions + - Always search for relevant documents before answering + - Provide citations for your sources + - Be objective and accurate in your responses + - If multiple documents contain relevant information, synthesize them + - Acknowledge when information is not available in the knowledge base + cache_control: + type: ephemeral + - type: text + text: |- + # Knowledge Base Context + + Here are the relevant documents for this conversation: + + ## Document 1: Solar System Overview + The solar system consists of the Sun and all objects that orbit it... + + ## Document 2: Planetary Characteristics + Each planet has unique features. Mercury is the smallest planet... + + ## Document 3: Mars Exploration + Mars has been a target of exploration for decades... + + [Additional documents...] + cache_control: + type: ephemeral + messages: + - role: user + content: Can you search for information about Mars rovers? + - role: assistant + content: + - type: tool_use + id: tool_1 + name: search_documents + input: + query: Mars rovers + - role: user + content: + - type: tool_result + tool_use_id: tool_1 + content: >- + Found 3 relevant documents: Document 3 (Mars Exploration), + Document 7 (Rover Technology), Document 9 (Mission History) + - role: assistant + content: + - type: text + text: >- + I found 3 relevant documents about Mars rovers. Let me get more + details from the Mars Exploration document. + - role: user + content: + - type: text + text: Yes, please tell me about the Perseverance rover specifically. + cache_control: + type: ephemeral + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=1024, + tools=[ + { + "name": "search_documents", + "description": "Search through the knowledge base", + "input_schema": { + "type": "object", + "properties": { + "query": {"type": "string", "description": "Search query"} + }, + "required": ["query"], + }, + }, + { + "name": "get_document", + "description": "Retrieve a specific document by ID", + "input_schema": { + "type": "object", + "properties": { + "doc_id": {"type": "string", "description": "Document ID"} + }, + "required": ["doc_id"], + }, + "cache_control": {"type": "ephemeral"}, + }, + ], + system=[ + { + "type": "text", + "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + "cache_control": {"type": "ephemeral"}, + }, + { + "type": "text", + "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + "cache_control": {"type": "ephemeral"}, + }, + ], + messages=[ + { + "role": "user", + "content": "Can you search for information about Mars rovers?", + }, + { + "role": "assistant", + "content": [ + { + "type": "tool_use", + "id": "tool_1", + "name": "search_documents", + "input": {"query": "Mars rovers"}, + } + ], + }, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "tool_1", + "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)", + } + ], + }, + { + "role": "assistant", + "content": [ + { + "type": "text", + "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.", + } + ], + }, + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Yes, please tell me about the Perseverance rover specifically.", + "cache_control": {"type": "ephemeral"}, + } + ], + }, + ], + ) + print(response.usage.model_dump_json()) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 1024, + tools: [ + { + name: "search_documents", + description: "Search through the knowledge base", + input_schema: { + type: "object", + properties: { + query: { + type: "string", + description: "Search query" + } + }, + required: ["query"] + } + }, + { + name: "get_document", + description: "Retrieve a specific document by ID", + input_schema: { + type: "object", + properties: { + doc_id: { + type: "string", + description: "Document ID" + } + }, + required: ["doc_id"] + }, + cache_control: { type: "ephemeral" } + } + ], + system: [ + { + type: "text", + text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + { + role: "user", + content: "Can you search for information about Mars rovers?" + }, + { + role: "assistant", + content: [ + { + type: "tool_use", + id: "tool_1", + name: "search_documents", + input: { query: "Mars rovers" } + } + ] + }, + { + role: "user", + content: [ + { + type: "tool_result", + tool_use_id: "tool_1", + content: + "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)" + } + ] + }, + { + role: "assistant", + content: [ + { + type: "text", + text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document." + } + ] + }, + { + role: "user", + content: [ + { + type: "text", + text: "Yes, please tell me about the Perseverance rover specifically.", + cache_control: { type: "ephemeral" } + } + ] + } + ] + }); + console.log(response.usage); + ``` + + ```csharp C# + AnthropicClient client = new() + { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") + }; + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 1024, + Tools = + [ + new ToolUnion(new Tool() + { + Name = "search_documents", + Description = "Search through the knowledge base", + InputSchema = new InputSchema() + { + Properties = new Dictionary + { + ["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }), + }, + Required = ["query"], + }, + }), + new ToolUnion(new Tool() + { + Name = "get_document", + Description = "Retrieve a specific document by ID", + InputSchema = new InputSchema() + { + Properties = new Dictionary + { + ["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }), + }, + Required = ["doc_id"], + }, + CacheControl = new CacheControlEphemeral(), + }), + ], + System = new MessageCreateParamsSystem(new List + { + new TextBlockParam() + { + Text = "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + CacheControl = new CacheControlEphemeral(), + }, + new TextBlockParam() + { + Text = "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + CacheControl = new CacheControlEphemeral(), + }, + }), + Messages = + [ + new UserMessageParam { Content = "Can you search for information about Mars rovers?" }, + new AssistantMessageParam + { + Content = new List + { + new ContentBlockParam(new ToolUseBlockParam() + { + ID = "tool_1", + Name = "search_documents", + Input = new Dictionary + { + ["query"] = JsonSerializer.SerializeToElement("Mars rovers"), + }, + }), + }, + }, + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new ToolResultBlockParam() + { + ToolUseID = "tool_1", + Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)", + }), + }, + }, + new AssistantMessageParam + { + Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.", + }, + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam() + { + Text = "Yes, please tell me about the Perseverance rover specifically.", + CacheControl = new CacheControlEphemeral(), + }), + }, + }, + ] + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message.Usage); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 1024, + Tools: []anthropic.ToolUnionParam{ + {OfTool: &anthropic.ToolParam{ + Name: "search_documents", + Description: anthropic.String("Search through the knowledge base"), + InputSchema: anthropic.ToolInputSchemaParam{ + Properties: map[string]any{ + "query": map[string]any{ + "type": "string", + "description": "Search query", + }, + }, + Required: []string{"query"}, + }, + }}, + {OfTool: &anthropic.ToolParam{ + Name: "get_document", + Description: anthropic.String("Retrieve a specific document by ID"), + InputSchema: anthropic.ToolInputSchemaParam{ + Properties: map[string]any{ + "doc_id": map[string]any{ + "type": "string", + "description": "Document ID", + }, + }, + Required: []string{"doc_id"}, + }, + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }}, + }, + System: []anthropic.TextBlockParam{ + { + Text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + { + Text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")), + anthropic.NewAssistantMessage(anthropic.NewToolUseBlock( + "tool_1", + map[string]any{"query": "Mars rovers"}, + "search_documents", + )), + anthropic.NewUserMessage(anthropic.NewToolResultBlock( + "tool_1", + "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)", + false, + )), + anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")), + anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{ + Text: "Yes, please tell me about the Perseverance rover specifically.", + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }}), + }, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(response.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + // Search tool schema + InputSchema searchSchema = InputSchema.builder() + .properties( + JsonValue.from( + Map.of("query", Map.of("type", "string", "description", "Search query")) + ) + ) + .putAdditionalProperty("required", JsonValue.from(List.of("query"))) + .build(); + + // Get document tool schema + InputSchema getDocSchema = InputSchema.builder() + .properties( + JsonValue.from( + Map.of("doc_id", Map.of("type", "string", "description", "Document ID")) + ) + ) + .putAdditionalProperty("required", JsonValue.from(List.of("doc_id"))) + .build(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(1024) + // Tools with cache control on the last one + .addTool( + Tool.builder() + .name("search_documents") + .description("Search through the knowledge base") + .inputSchema(searchSchema) + .build() + ) + .addTool( + Tool.builder() + .name("get_document") + .description("Retrieve a specific document by ID") + .inputSchema(getDocSchema) + .cacheControl(CacheControlEphemeral.builder().build()) + .build() + ) + // System prompts with cache control on instructions and context separately + .systemOfTextBlockParams( + List.of( + TextBlockParam.builder() + .text( + "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base" + ) + .cacheControl(CacheControlEphemeral.builder().build()) + .build(), + TextBlockParam.builder() + .text( + "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]" + ) + .cacheControl(CacheControlEphemeral.builder().build()) + .build() + ) + ) + // Conversation history + .addUserMessage("Can you search for information about Mars rovers?") + .addAssistantMessageOfContentBlockParams( + List.of( + ContentBlockParam.ofToolUse( + ToolUseBlockParam.builder() + .id("tool_1") + .name("search_documents") + .input(JsonValue.from(Map.of("query", "Mars rovers"))) + .build() + ) + ) + ) + .addUserMessageOfContentBlockParams( + List.of( + ContentBlockParam.ofToolResult( + ToolResultBlockParam.builder() + .toolUseId("tool_1") + .content( + "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)" + ) + .build() + ) + ) + ) + .addAssistantMessageOfContentBlockParams( + List.of( + ContentBlockParam.ofText( + TextBlockParam.builder() + .text( + "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document." + ) + .build() + ) + ) + ) + .addUserMessageOfContentBlockParams( + List.of( + ContentBlockParam.ofText( + TextBlockParam.builder() + .text("Yes, please tell me about the Perseverance rover specifically.") + .cacheControl(CacheControlEphemeral.builder().build()) + .build() + ) + ) + ) + .build(); + + Message message = client.messages().create(params); + IO.println(message.usage()); + } + ``` + + ```php PHP + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 1024, + messages: [ + [ + 'role' => 'user', + 'content' => 'Can you search for information about Mars rovers?' + ], + [ + 'role' => 'assistant', + 'content' => [ + [ + 'type' => 'tool_use', + 'id' => 'tool_1', + 'name' => 'search_documents', + 'input' => ['query' => 'Mars rovers'] + ] + ] + ], + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'tool_result', + 'tool_use_id' => 'tool_1', + 'content' => 'Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)' + ] + ] + ], + [ + 'role' => 'assistant', + 'content' => [ + [ + 'type' => 'text', + 'text' => 'I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.' + ] + ] + ], + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'text', + 'text' => 'Yes, please tell me about the Perseverance rover specifically.', + 'cache_control' => ['type' => 'ephemeral'] + ] + ] + ] + ], + model: Model::CLAUDE_OPUS_5_5, + system: [ + [ + 'type' => 'text', + 'text' => "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + 'cache_control' => ['type' => 'ephemeral'] + ], + [ + 'type' => 'text', + 'text' => "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + 'cache_control' => ['type' => 'ephemeral'] + ] + ], + tools: [ + [ + 'name' => 'search_documents', + 'description' => 'Search through the knowledge base', + 'input_schema' => [ + 'type' => 'object', + 'properties' => [ + 'query' => [ + 'type' => 'string', + 'description' => 'Search query' + ] + ], + 'required' => ['query'] + ] + ], + [ + 'name' => 'get_document', + 'description' => 'Retrieve a specific document by ID', + 'input_schema' => [ + 'type' => 'object', + 'properties' => [ + 'doc_id' => [ + 'type' => 'string', + 'description' => 'Document ID' + ] + ], + 'required' => ['doc_id'] + ], + 'cache_control' => ['type' => 'ephemeral'] + ] + ], + ); + + echo json_encode($message->usage), PHP_EOL; + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 1024, + tools: [ + { + name: "search_documents", + description: "Search through the knowledge base", + input_schema: { + type: "object", + properties: { + query: { + type: "string", + description: "Search query" + } + }, + required: ["query"] + } + }, + { + name: "get_document", + description: "Retrieve a specific document by ID", + input_schema: { + type: "object", + properties: { + doc_id: { + type: "string", + description: "Document ID" + } + }, + required: ["doc_id"] + }, + cache_control: { type: "ephemeral" } + } + ], + system_: [ + { + type: "text", + text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base", + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]", + cache_control: { type: "ephemeral" } + } + ], + messages: [ + { + role: "user", + content: "Can you search for information about Mars rovers?" + }, + { + role: "assistant", + content: [ + { + type: "tool_use", + id: "tool_1", + name: "search_documents", + input: { query: "Mars rovers" } + } + ] + }, + { + role: "user", + content: [ + { + type: "tool_result", + tool_use_id: "tool_1", + content: "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)" + } + ] + }, + { + role: "assistant", + content: [ + { + type: "text", + text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document." + } + ] + }, + { + role: "user", + content: [ + { + type: "text", + text: "Yes, please tell me about the Perseverance rover specifically.", + cache_control: { type: "ephemeral" } + } + ] + } + ] + ) + puts message.usage + ``` + + + This comprehensive example demonstrates how to use all 4 available cache breakpoints to optimize different parts of your prompt: + + 1. **Tools cache** (cache breakpoint 1): The `cache_control` parameter on the last tool definition caches all tool definitions. + + 2. **Reusable instructions cache** (cache breakpoint 2): The static instructions in the system prompt are cached separately. These instructions rarely change between requests. + + 3. **RAG context cache** (cache breakpoint 3): The knowledge base documents are cached independently, allowing you to update the RAG documents without invalidating the tools or instructions cache. + + 4. **Conversation history cache** (cache breakpoint 4): The final user message is marked with `cache_control` to enable incremental caching of the conversation as it progresses. + + This approach provides maximum flexibility: + + * If you append a new turn to the conversation without changing earlier content, all four cache segments are reused. + * If you update the RAG documents but keep the same tools and instructions, the first two cache segments are reused. + * If you change the conversation but keep the same tools, instructions, and documents, the first three segments are reused. + * Changes at any breakpoint invalidate that segment and everything after it, whereas earlier cached segments remain valid. + + For the first request: + + * `input_tokens`: Minimal (tokens after the final cache breakpoint, near 0 in this example) + * `cache_creation_input_tokens`: Tokens in all cached segments (tools + instructions + RAG documents + conversation history) + * `cache_read_input_tokens`: 0 (no cache hits) + + For subsequent requests with only a new user message (and the fourth breakpoint moved to that new final message, as in the example): + + * `input_tokens`: Minimal (tokens after the final cache breakpoint, near 0 in this example) + * `cache_creation_input_tokens`: Tokens in the new user message and the previous assistant turn (the new conversation segment being cached) + * `cache_read_input_tokens`: All previously cached tokens (tools + instructions + RAG documents + previous conversation) + + This pattern is especially powerful for: + + * RAG applications with large document contexts + * Agent systems that use multiple tools + * Long-running conversations that need to maintain context + * Applications that need to optimize different parts of the prompt independently + + + +## Data retention + +Prompt caching (both automatic and explicit) is ZDR eligible. Anthropic does not store the raw text of your prompts or Claude’s responses. + +KV (key-value) cache representations and cryptographic hashes of cached content are held in memory only and are not stored at rest. Cached entries have a minimum lifetime of 5 minutes (standard) or 1 hour (extended), after which they are promptly, though not immediately, deleted. Cache entries are isolated between organizations and, on the Claude API, Claude Platform on AWS, and Microsoft Foundry, between workspaces within an organization. + +*** + +## FAQ + + + + **In most cases, a single cache breakpoint at the end of your static content is sufficient.** Cache writes occur only at the block you mark. Place it on the last block that stays identical across requests, and every subsequent request reads that same entry. If a later block varies with each request (a timestamp, the incoming message), keep the breakpoint before it, on the last stable block. + + You only need multiple breakpoints if: + + * A growing conversation pushes your breakpoint 20 or more blocks past the last cache write, putting the prior entry outside the lookback window + * You want to cache sections that update at different frequencies independently + * You need explicit control over what gets cached for cost optimization + + Example: If you have system instructions (rarely change) and RAG context (changes daily), you might use two breakpoints to cache them separately. + + + + No, cache breakpoints themselves are free. You only pay for: + + * Writing content to cache (25 percent more than base input tokens for 5-minute TTL) + * Reading from cache ([a fraction of the base input token price](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)) + * Regular input tokens for uncached content + + The number of breakpoints doesn’t affect pricing; only the amount of content cached and read matters. + + + + The usage response includes three separate input token fields that together represent your total input: + + ```text wrap + total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens + ``` + + * `cache_read_input_tokens`: Tokens retrieved from cache (everything before cache breakpoints that was cached) + * `cache_creation_input_tokens`: New tokens being written to cache (at cache breakpoints) + * `input_tokens`: Tokens **after the last cache breakpoint** that aren’t cached + + **Important:** `input_tokens` does NOT represent all input tokens, only the portion after your last cache breakpoint. If you have cached content, `input_tokens` is typically much smaller than your total input. + + **Example:** With a 200k-token document cached and a 50-token user question: + + * `cache_read_input_tokens`: 200,000 + * `cache_creation_input_tokens`: 0 + * `input_tokens`: 50 + * **Total:** 200,050 tokens + + This breakdown is critical for understanding both your costs and rate limit usage. See [Tracking cache performance](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) for more details. + + + + The cache’s default minimum lifetime (TTL) is 5 minutes. This lifetime is refreshed each time the cached content is used. + + If you find that 5 minutes is too short, Anthropic also offers a [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). + + + + The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime, so the window for a follow-up request to reuse the cache is the lifetime minus the generation time. + + If your requests produce long responses and the next request might not start until after the lifetime elapses, use the [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). + + + + You can define up to 4 cache breakpoints (using `cache_control` parameters) in your prompt. + + + + Prompt caching is supported on all [active Claude models](https://platform.claude.com/docs/en/models/overview). + + + + Changing thinking parameters (switching modes, or changing the budget in extended mode) invalidates cached message prefixes, and can invalidate cached system prompts and tools as well, because the thinking configuration is rendered into the prompt. The [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value behaves the same way. + + For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache). + + For more on thinking, including its interaction with tool use and prompt caching, see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). + + + + The easiest way is to add `"cache_control": {"type": "ephemeral"}` at the top level of your request body ([automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching)). Alternatively, include at least one `cache_control` breakpoint on individual content blocks ([explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)). + + + + Yes, prompt caching can be used alongside other API features such as tool use and vision capabilities. However, changing whether there are images in a prompt or modifying tool use settings breaks the cache. + + For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache). + + + + Prompt caching has its own pricing: 5-minute cache writes cost 25 percent more than base input tokens, 1-hour cache writes cost 2x base input tokens, and cache hits cost [a fraction of the base input token price](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing), with a multiplier for each model. + + + + Currently, there’s no way to manually clear the cache. Cached prefixes automatically expire after a minimum of 5 minutes of inactivity. + + + + You can monitor cache performance using the `cache_creation_input_tokens` and `cache_read_input_tokens` fields in the API response. + + + + See [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache) for more details on cache invalidation, including a list of changes that require creating a new cache entry. + + + + Prompt caching is designed with strong privacy and data separation measures: + + 1. Cache keys are generated using a cryptographic hash of the prompts up to the cache control point. This means only requests with identical prompts can access a specific cache. + + 2. On the Claude API, Claude Platform on AWS, and Microsoft Foundry, caches are isolated by workspace within an organization. On Claude Models on Google Cloud (Google managed) and Bedrock, caches are isolated by organization. In every case, caches are never shared across organizations, even for identical prompts. See [Cache storage and sharing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing) for details. + + 3. The caching mechanism is designed to maintain the integrity and privacy of each unique conversation or context. + + 4. It’s safe to use `cache_control` anywhere in your prompts. For caching to produce reads, place the breakpoint at the end of a stable prefix: placing it on a block that changes every request (such as a timestamp or the user’s arbitrary input) writes a fresh entry each time and never hits. + + These measures ensure that prompt caching maintains data privacy and security while offering performance benefits. + + + + Yes, you can use prompt caching with your [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) requests. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis. + + The [1-hour cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) can help improve your cache hits. The most cost-effective way of using it is the following: + + * Gather a set of message requests that have a shared prefix. + * Send a batch request with a single request that has this shared prefix and a 1-hour cache block. This writes the prefix to the 1-hour cache. + * As soon as this is complete, submit the rest of the requests. You have to monitor the job to know when it completes. + + This is typically better than using the 5-minute cache because it’s common for batch requests to take between 5 minutes and 1 hour to complete. + + + + This error typically appears when you have upgraded your SDK or you are using outdated code examples. Prompt caching is available on `client.messages`, without the beta prefix. Instead of: + + + ```python Python + client.beta.prompt_caching.messages.create(**params) + ``` + + + Use: + + + ```python Python + client.messages.create(**params) + ``` + + + + + This error typically appears when you have upgraded your SDK or you are using outdated code examples. Prompt caching is available on `client.messages`, without the beta prefix. Instead of: + + ```typescript TypeScript + client.beta.promptCaching.messages.create(/* ... */); + ``` + + Use: + + ```typescript + client.messages.create(/* ... */); + ``` + + + +## Availability + +Prompt caching is available or in beta, depending on the API, and eligible for zero data retention and HIPAA readiness. + +### API support + +#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) + +* Availability: Available +* Usage: Opt in with `cache_control`, at the top level or on blocks. + +| Status | Cloud platforms | Models | +| --------- | ----------------------- | ----------------------------------------------------------------- | +| Available | All supported platforms | [All models](https://platform.claude.com/docs/en/models/overview) | + +#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) + +* Availability: Always on +* Usage: Cache entries use a 5-minute lifetime by default, and cache reads and writes show up in the session’s usage. + +| Status | Cloud platforms | Models | +| ------ | ----------------------- | ----------------------------------------------------------------- | +| Beta | All supported platforms | [All models](https://platform.claude.com/docs/en/models/overview) | + +### Data handling + +[Data handling overview](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility) + +| Item | Zero data retention | HIPAA | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| Status | Eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Eligible | +| Details | Your prompts and Claude’s outputs are not stored. KV cache representations and cryptographic hashes are held in memory for the cache TTL and promptly deleted after expiry. [Learn more](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#data-retention) | — | + +Applicable endpoints: + +* `/v1/messages` + + diff --git a/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking-steering-and-cost.md b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking-steering-and-cost.md new file mode 100644 index 00000000..30439454 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking-steering-and-cost.md @@ -0,0 +1,922 @@ +--- +title: Steering thinking +url: https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost +description: Steer how often and how deeply Claude thinks with effort levels, system prompt guidance, and per-message steering, and understand thinking's cost and pricing. +--- + + + To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention). + + +Claude’s thinking is adaptive: the model evaluates each request and determines whether to think and how much. You set an intent, optionally specify the effort, and the model allocates reasoning where reasoning is likely to help. + +This makes thinking a strong fit for workloads that mix trivial and complex requests, and for long-horizon agentic workflows where the right amount of reasoning varies from step to step. + +To learn how to turn thinking on and how to read thinking output, see the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview. This page covers how Claude determines when to think, how to steer thinking, and the caching, cost, and pricing mechanics that follow from it. + +## How Claude determines when to think + +Thinking is optional for the model. On each request, Claude evaluates the complexity of the input and determines whether deeper reasoning would improve the answer. A simple factual question might get a direct response with no thinking block at all; a multistep math problem or a tricky debugging task triggers deeper reasoning. + +This determination occurs for each request. The same conversation can contain turns with and without thinking, and a turn where Claude skips thinking contains no thinking block. Don’t build application logic that assumes every assistant turn starts with one. + +The primary control over this determination is the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) parameter, which acts as soft guidance for how often and how deeply Claude uses thinking; see [Effort levels](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#effort-levels) on this page for what each level does. + +If you want Claude to think less often, lower the effort level before reaching for prompt-based steering. + +Thinking also interleaves with tool use automatically: Claude can think between tool calls, evaluating each tool result before determining what to do next ([interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking)). You don’t need a beta header or any additional configuration for this. + +For full details on how the thinking configuration and the effort parameter interact, see [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort). + +## Steering how often Claude thinks + +Whether Claude thinks on a given turn is promptable. Effort sets the overall posture, but you can also shape that behavior directly with natural-language guidance, either globally in the system prompt or for individual messages in the user turn. + +Use the two levers together in this order: + +1. Set the effort level that matches your workload’s default balance of quality and latency. +2. Add prompt guidance only if Claude’s triggering still doesn’t match your needs at that level. + + + To get less thinking on Claude Sonnet 5.5 and Claude Haiku 5.5, lower the effort level. Asking Claude Sonnet 5.5 in the system prompt to think less doesn’t reliably reduce its thinking, and in Anthropic’s testing, telling Claude Haiku 5.5 in the prompt to answer directly didn’t stop it from thinking. See [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort) and [Prompting Claude Haiku 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking). + + +For broader prompting guidance with thinking, see [leverage thinking and interleaved thinking capabilities](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities). + +### Effort levels + +Effort is the primary steering lever for thinking. Each level sets a different default for how often Claude thinks and how deeply: + +| Effort level | Thinking behavior | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `max` | Claude thinks the most readily and at the greatest depth, with no constraint on thinking length. | +| `xhigh` | Claude thinks more readily and at greater depth than at `high`, suited to extended exploration. | +| `high` (default on most models) | Claude thinks on most requests that benefit from it. Provides deep reasoning on complex tasks. | +| `medium` (default on Claude Opus 5.5 and Claude Haiku 5.5) | Claude uses moderate thinking. Might skip thinking for simple queries. | +| `low` | Claude minimizes thinking. Skips thinking for simple tasks where speed matters most. | + +At every level, Claude determines for each request whether to think. In a tool-use loop, the first request after new user input typically carries most of the reasoning, and follow-up requests that only process tool results can skip thinking, including at `xhigh` and `max`. Thinking per request also tends to decrease as a conversation grows longer. No level guarantees a thinking block on every request. + +This table describes how each level changes thinking behavior. For guidance on which level to choose for a given workload, including per-model recommendations, see [When to adjust the effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort#when-to-adjust-the-effort-parameter) on the effort page. + +Effort is set at `output_config.effort`, not inside the `thinking` object; for full per-language examples, see [Set the effort level](https://platform.claude.com/docs/en/build-with-claude/effort#basic-usage). + +```json +{ + "model": "claude-opus-5-5", + "max_tokens": 4096, + "output_config": { "effort": "medium" }, + "messages": [{ "role": "user", "content": "..." }] +} +``` + +Level availability varies by model; the [effort availability table](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels) on the effort page is the authority for which levels each model supports. + +### System prompt guidance + +System prompt guidance shifts Claude’s thinking threshold for every request in the conversation. If Claude is thinking more often than your workload needs, add guidance such as the following to your system prompt: + +```text wrap +Extended thinking adds latency and should only be used when it +will meaningfully improve answer quality, typically for problems +that require multistep reasoning. When in doubt, respond directly. +``` + +To encourage thinking instead, use a phrase such as: + +```text wrap +This task involves multistep reasoning. Think carefully before responding. +``` + +Steering effectiveness can be sensitive to exact wording. If one phrasing doesn’t produce the behavior you want, try a more direct variant. + +### Per-message steering + +You can also steer thinking on a per-message basis from the user turn, independently of the system prompt. Appending `"Please think hard before responding."` to a user message encourages Claude to think on that turn; `"Answer directly without deliberating."` discourages it. + +Per-message steering is useful when only some requests in a conversation warrant extended reasoning. An agent harness, for example, can append the encouraging phrase on planning steps and the discouraging phrase on routine confirmations, without touching the system prompt or changing any request parameters between turns. + +On Claude Haiku 5.5, the discouraging phrase doesn’t reliably reduce thinking. Where your platform supports it, run routine turns on that model with less thinking by using a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) instead, which also keeps the prompt cache. + +### Verify steering on your workload + +Prompt-based steering changes model behavior, so treat it like any other prompt change: measure before you ship. Run a representative sample of your traffic with and without the guidance, and compare how often thinking triggers (the presence of thinking blocks in responses), output token usage, latency, and answer quality on the cases that matter to you. + + + Steering Claude to think less often might reduce quality on tasks that benefit from reasoning. Lowering the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level is usually the better first lever, because it is a calibrated control rather than a wording-sensitive instruction. Measure the impact on your specific workloads before deploying prompt-based tuning to production. + + +## Mechanics + +Three mechanics follow from Claude managing its own thinking: turn validation, prompt caching, and how you bound cost. + +### Turn validation + +Assistant turns don’t need to start with a thinking block. (Models using a legacy manual thinking budget enforce that the final assistant turn of a thinking-enabled request starts with one; see [Turn structure in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#turn-structure-in-manual-mode).) + +For multi-turn applications, this means you can pass back conversation history in whatever shape you have it: + +* Assistant turns that Claude produced without thinking are valid history as-is. +* You can resume a conversation that started without thinking, or that used a different thinking configuration, without rewriting its history. +* History assembled from mixed sources doesn’t need thinking blocks reinserted at the start of each assistant turn to pass validation. + +The relaxation is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude’s tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules. + +### Prompt caching + +Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching) for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints, just as changing the legacy [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) parameter does on models that use it. Setting `effort` explicitly to the model’s default is equivalent to omitting it and does not break the cache. + +The practical consequence: pick a thinking configuration and a top-level effort level for each conversation and keep them. If some turns need more or less thinking, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) (beta) on models that support it, or steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). Both leave earlier cache breakpoints intact, where a change to the thinking configuration or the top-level effort level does not. + +The following example demonstrates the invalidation with a multi-turn script you can run yourself: + + + + + This workflow needs more logic than a single shell command. Use the Claude SDK to run it; per-turn HTTP requests follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page. + + + + This workflow needs more logic than a single shell command. Use the Claude SDK to run it; per-turn CLI commands follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page. + + + ```python Python + import requests + + client = Anthropic() + + + def fetch_article_content(url): + text = requests.get(url).text + lines = (line.strip() for line in text.splitlines()) + return "\n".join(line for line in lines if line) + + + # Fetch the content of the article + book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt" + book_content = fetch_article_content(book_url) + # Use just enough text for caching (first few chapters) + LARGE_TEXT = book_content[:10000] + + # No system prompt: caching in messages instead + MESSAGES = [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": LARGE_TEXT, + "cache_control": {"type": "ephemeral"}, + }, + {"type": "text", "text": "Analyze the tone of this passage."}, + ], + } + ] + + # First request: establish cache + print("First request - establishing cache") + response1 = client.messages.create( + model="claude-opus-5-5", + max_tokens=16000, + thinking={"type": "adaptive"}, + messages=MESSAGES, + ) + + print(f"First response usage: {response1.usage}") + + MESSAGES.append({"role": "assistant", "content": response1.content}) + MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."}) + + # Second request: same configuration (cache hit expected) + print("\nSecond request - same configuration (cache hit expected)") + response2 = client.messages.create( + model="claude-opus-5-5", + max_tokens=16000, + thinking={"type": "adaptive"}, + messages=MESSAGES, + ) + + print(f"Second response usage: {response2.usage}") + + MESSAGES.append({"role": "assistant", "content": response2.content}) + MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."}) + + # Third request: different effort level (cache miss expected) + print("\nThird request - different effort level (cache miss expected)") + response3 = client.messages.create( + model="claude-opus-5-5", + max_tokens=16000, + thinking={"type": "adaptive"}, + output_config={"effort": "low"}, + messages=MESSAGES, + ) + + print(f"Third response usage: {response3.usage}") + ``` + + ```typescript TypeScript + + const client = new Anthropic(); + + async function fetchArticleContent(url: string): Promise { + const response = await fetch(url); + const text = await response.text(); + const lines = text.split("\n").map((line) => line.trim()); + return lines.filter((line) => line).join("\n"); + } + + const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"; + const bookContent = await fetchArticleContent(bookUrl); + const LARGE_TEXT = bookContent.substring(0, 10000); + + // No system prompt: caching in messages instead + const messages: Anthropic.MessageParam[] = [ + { + role: "user", + content: [ + { + type: "text", + text: LARGE_TEXT, + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "Analyze the tone of this passage." + } + ] + } + ]; + + // First request: establish cache + console.log("First request - establishing cache"); + const response1 = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { type: "adaptive" }, + messages + }); + + console.log("First response usage: ", response1.usage); + + messages.push( + { role: "assistant", content: response1.content }, + { role: "user", content: "Analyze the characters in this passage." } + ); + + // Second request: same configuration (cache hit expected) + console.log("\nSecond request - same configuration (cache hit expected)"); + const response2 = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { type: "adaptive" }, + messages + }); + + console.log("Second response usage: ", response2.usage); + + messages.push( + { role: "assistant", content: response2.content }, + { role: "user", content: "Analyze the setting in this passage." } + ); + + // Third request: different effort level (cache miss expected) + console.log("\nThird request - different effort level (cache miss expected)"); + const response3 = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { type: "adaptive" }, + output_config: { effort: "low" }, + messages + }); + + console.log("Third response usage: ", response3.usage); + ``` + + ```csharp C# + AnthropicClient client = new(); + + string bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"; + string bookContent = await FetchArticleContent(bookUrl); + string largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length)); + + Console.WriteLine("First request - establishing cache"); + var parameters1 = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 16000, + Thinking = new ThinkingConfigAdaptive(), + Messages = + [ + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam() + { + Text = largeText, + CacheControl = new CacheControlEphemeral(), + }), + new ContentBlockParam(new TextBlockParam() + { + Text = "Analyze the tone of this passage." + }), + } + } + ] + }; + + var response1 = await client.Messages.Create(parameters1); + Console.WriteLine($"First response usage: {response1.Usage}"); + + Console.WriteLine("\nSecond request - same configuration (cache hit expected)"); + var parameters2 = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 16000, + Thinking = new ThinkingConfigAdaptive(), + Messages = + [ + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam() + { + Text = largeText, + CacheControl = new CacheControlEphemeral(), + }), + new ContentBlockParam(new TextBlockParam() + { + Text = "Analyze the tone of this passage." + }), + } + }, + new AssistantMessageParam + { + Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList() + }, + new UserMessageParam { Content = "Analyze the characters in this passage." } + ] + }; + + var response2 = await client.Messages.Create(parameters2); + Console.WriteLine($"Second response usage: {response2.Usage}"); + + Console.WriteLine("\nThird request - different effort level (cache miss expected)"); + var parameters3 = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 16000, + Thinking = new ThinkingConfigAdaptive(), + OutputConfig = new OutputConfig + { + Effort = Effort.Low + }, + Messages = + [ + new UserMessageParam + { + Content = new List + { + new ContentBlockParam(new TextBlockParam() + { + Text = largeText, + CacheControl = new CacheControlEphemeral(), + }), + new ContentBlockParam(new TextBlockParam() + { + Text = "Analyze the tone of this passage." + }), + } + }, + new AssistantMessageParam + { + Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList() + }, + new UserMessageParam { Content = "Analyze the characters in this passage." }, + new AssistantMessageParam + { + Content = response2.Content.Select(block => new ContentBlockParam(block.Json)).ToList() + }, + new UserMessageParam { Content = "Analyze the setting in this passage." } + ] + }; + + var response3 = await client.Messages.Create(parameters3); + Console.WriteLine($"Third response usage: {response3.Usage}"); + + static async Task FetchArticleContent(string url) + { + using HttpClient httpClient = new(); + string content = await httpClient.GetStringAsync(url); + return content; + } + ``` + + ```go Go + client := anthropic.NewClient() + + bookURL := "https://www.gutenberg.org/cache/epub/1342/pg1342.txt" + bookContent, err := fetchArticleContent(bookURL) + if err != nil { + log.Fatal(err) + } + + largeText := bookContent + if len(largeText) > 10000 { + largeText = largeText[:10000] + } + + // No system prompt: caching in messages instead + messages := []anthropic.MessageParam{ + anthropic.NewUserMessage( + anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{ + Text: largeText, + CacheControl: anthropic.NewCacheControlEphemeralParam(), + }}, + anthropic.NewTextBlock("Analyze the tone of this passage."), + ), + } + + // First request: establish cache + fmt.Println("First request - establishing cache") + response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}, + }, + Messages: messages, + }) + if err != nil { + log.Fatal(err) + } + fmt.Printf("First response usage: %s\n", response1.Usage.RawJSON()) + + messages = append(messages, response1.ToParam()) + messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage."))) + + // Second request: same configuration (cache hit expected) + fmt.Println("\nSecond request - same configuration (cache hit expected)") + response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}, + }, + Messages: messages, + }) + if err != nil { + log.Fatal(err) + } + fmt.Printf("Second response usage: %s\n", response2.Usage.RawJSON()) + + messages = append(messages, response2.ToParam()) + messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the setting in this passage."))) + + // Third request: different effort level (cache miss expected) + fmt.Println("\nThird request - different effort level (cache miss expected)") + response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}, + }, + OutputConfig: anthropic.OutputConfigParam{ + Effort: anthropic.OutputConfigEffortLow, + }, + Messages: messages, + }) + if err != nil { + log.Fatal(err) + } + fmt.Printf("Third response usage: %s\n", response3.Usage.RawJSON()) + ``` + + ```java Java + import com.anthropic.models.messages.CacheControlEphemeral; + // ... + void main() throws Exception { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + String bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"; + String bookContent = fetchArticleContent(bookUrl); + String largeText = bookContent.substring(0, Math.min(10000, bookContent.length())); + + // First request: establish cache + IO.println("First request - establishing cache"); + MessageCreateParams params1 = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .addUserMessageOfContentBlockParams(List.of( + ContentBlockParam.ofText(TextBlockParam.builder() + .text(largeText) + .cacheControl(CacheControlEphemeral.builder().build()) + .build()), + ContentBlockParam.ofText(TextBlockParam.builder() + .text("Analyze the tone of this passage.") + .build()) + )) + .build(); + + Message response1 = client.messages().create(params1); + IO.println("First response usage: " + response1.usage()); + + // Second request: same configuration (cache hit expected) + IO.println("\nSecond request - same configuration (cache hit expected)"); + MessageCreateParams params2 = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .addUserMessageOfContentBlockParams(List.of( + ContentBlockParam.ofText(TextBlockParam.builder() + .text(largeText) + .cacheControl(CacheControlEphemeral.builder().build()) + .build()), + ContentBlockParam.ofText(TextBlockParam.builder() + .text("Analyze the tone of this passage.") + .build()) + )) + .addAssistantMessageOfContentBlockParams(response1.content().stream() + .map(block -> block.toParam()) + .collect(Collectors.toList())) + .addUserMessage("Analyze the characters in this passage.") + .build(); + + Message response2 = client.messages().create(params2); + IO.println("Second response usage: " + response2.usage()); + + // Third request: different effort level (cache miss expected) + IO.println("\nThird request - different effort level (cache miss expected)"); + MessageCreateParams params3 = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .outputConfig(OutputConfig.builder() + .effort(OutputConfig.Effort.LOW) + .build()) + .addUserMessageOfContentBlockParams(List.of( + ContentBlockParam.ofText(TextBlockParam.builder() + .text(largeText) + .cacheControl(CacheControlEphemeral.builder().build()) + .build()), + ContentBlockParam.ofText(TextBlockParam.builder() + .text("Analyze the tone of this passage.") + .build()) + )) + .addAssistantMessageOfContentBlockParams(response1.content().stream() + .map(block -> block.toParam()) + .collect(Collectors.toList())) + .addUserMessage("Analyze the characters in this passage.") + .addAssistantMessageOfContentBlockParams(response2.content().stream() + .map(block -> block.toParam()) + .collect(Collectors.toList())) + .addUserMessage("Analyze the setting in this passage.") + .build(); + + Message response3 = client.messages().create(params3); + IO.println("Third response usage: " + response3.usage()); + } + + String fetchArticleContent(String url) throws Exception { + HttpClient client = HttpClient.newHttpClient(); + HttpRequest request = HttpRequest.newBuilder() + .uri(URI.create(url)) + .build(); + HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); + return response.body(); + } + ``` + + ```php PHP + function fetchArticleContent($url) + { + $content = file_get_contents($url); + $lines = explode("\n", $content); + $cleanedLines = array_filter(array_map('trim', $lines)); + return implode("\n", $cleanedLines); + } + + $client = new Client(); + + $bookUrl = 'https://www.gutenberg.org/cache/epub/1342/pg1342.txt'; + $bookContent = fetchArticleContent($bookUrl); + $largeText = substr($bookContent, 0, 10000); + + echo "First request - establishing cache\n"; + $response1 = $client->messages->create( + maxTokens: 16000, + messages: [[ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'text', + 'text' => $largeText, + 'cache_control' => ['type' => 'ephemeral'] + ], + [ + 'type' => 'text', + 'text' => 'Analyze the tone of this passage.' + ] + ] + ]], + model: 'claude-opus-5-5', + thinking: ['type' => 'adaptive'], + ); + + echo 'First response usage: ' . json_encode($response1->usage) . "\n"; + + echo "\nSecond request - same configuration (cache hit expected)\n"; + $response2 = $client->messages->create( + maxTokens: 16000, + messages: [ + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'text', + 'text' => $largeText, + 'cache_control' => ['type' => 'ephemeral'] + ], + [ + 'type' => 'text', + 'text' => 'Analyze the tone of this passage.' + ] + ] + ], + [ + 'role' => 'assistant', + 'content' => $response1->content + ], + [ + 'role' => 'user', + 'content' => 'Analyze the characters in this passage.' + ] + ], + model: 'claude-opus-5-5', + thinking: ['type' => 'adaptive'], + ); + + echo 'Second response usage: ' . json_encode($response2->usage) . "\n"; + + echo "\nThird request - different effort level (cache miss expected)\n"; + $response3 = $client->messages->create( + maxTokens: 16000, + messages: [ + [ + 'role' => 'user', + 'content' => [ + [ + 'type' => 'text', + 'text' => $largeText, + 'cache_control' => ['type' => 'ephemeral'] + ], + [ + 'type' => 'text', + 'text' => 'Analyze the tone of this passage.' + ] + ] + ], + [ + 'role' => 'assistant', + 'content' => $response1->content + ], + [ + 'role' => 'user', + 'content' => 'Analyze the characters in this passage.' + ], + [ + 'role' => 'assistant', + 'content' => $response2->content + ], + [ + 'role' => 'user', + 'content' => 'Analyze the setting in this passage.' + ] + ], + model: 'claude-opus-5-5', + thinking: ['type' => 'adaptive'], + outputConfig: ['effort' => 'low'], + ); + + echo 'Third response usage: ' . json_encode($response3->usage) . "\n"; + ``` + + ```ruby Ruby + require "net/http" + require "uri" + + def fetch_article_content(url) + uri = URI.parse(url) + response = Net::HTTP.get_response(uri) + text = response.body + + lines = text.split("\n").map(&:strip) + lines.reject(&:empty?).join("\n") + end + + client = Anthropic::Client.new + + book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt" + book_content = fetch_article_content(book_url) + large_text = book_content[0...10000] + + puts "First request - establishing cache" + response1 = client.messages.create( + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { + type: "adaptive" + }, + messages: [{ + role: "user", + content: [ + { + type: "text", + text: large_text, + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "Analyze the tone of this passage." + } + ] + }] + ) + + puts "First response usage: #{response1.usage}" + + puts "\nSecond request - same configuration (cache hit expected)" + response2 = client.messages.create( + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { + type: "adaptive" + }, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: large_text, + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "Analyze the tone of this passage." + } + ] + }, + { + role: "assistant", + content: response1.content + }, + { + role: "user", + content: "Analyze the characters in this passage." + } + ] + ) + + puts "Second response usage: #{response2.usage}" + + puts "\nThird request - different effort level (cache miss expected)" + response3 = client.messages.create( + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { + type: "adaptive" + }, + output_config: { + effort: "low" + }, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: large_text, + cache_control: { type: "ephemeral" } + }, + { + type: "text", + text: "Analyze the tone of this passage." + } + ] + }, + { + role: "assistant", + content: response1.content + }, + { + role: "user", + content: "Analyze the characters in this passage." + }, + { + role: "assistant", + content: response2.content + }, + { + role: "user", + content: "Analyze the setting in this passage." + } + ] + ) + + puts "Third response usage: #{response3.usage}" + ``` + + + Here is the output of the script (you might see slightly different numbers): + + ```text Output wrap + First request - establishing cache + First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 } + + Second request - same configuration (cache hit expected) + Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 } + + Third request - different effort level (cache miss expected) + Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 } + ``` + + With the cache breakpoint in the messages array, changing effort from `medium`, the default on Claude Opus 5.5, to `low` invalidates it: the third request shows `cache_creation_input_tokens=3546` and `cache_read_input_tokens=0` where the second showed a full cache read. + + +### Cost control + +You don’t set a thinking token budget. Two controls bound cost: + +* `max_tokens` is a hard cap on total output for the request, thinking and response text combined. Claude never generates past it. In a tool-use loop, each request in the turn has its own `max_tokens`, so it doesn’t bound the whole turn’s spend. +* `effort` is soft guidance on how much of that output Claude allocates to thinking. It shapes behavior but doesn’t guarantee a token count. + +Because thinking counts toward `max_tokens`, set it high enough to leave room for both the reasoning and the answer. A `max_tokens` sized for a response with no thinking is often too small once Claude starts thinking on hard requests. + +At `high` effort and above, Claude might think extensively and is more likely to exhaust the budget. If you see [`stop_reason: "max_tokens"`](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#stopped-at-max-tokens) in responses, you have two remedies: + +* Raise `max_tokens` to give the model more room for thinking plus the answer. +* Lower the effort level so Claude thinks less and leaves more of the budget for response text. + +Which one is right depends on whether the truncated responses needed the reasoning. If quality on those requests matters, raise the cap; if they were over-thought, lower the effort. + +## Pricing + +Thinking incurs charges for: + +* Tokens Claude uses while thinking (billed as output tokens) +* Thinking blocks from prior assistant turns that remain in context, according to the [preservation default](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model): all turns by default on keep-all models, only the last turn elsewhere (billed as input tokens) +* Standard text output tokens + + + When thinking is active, a specialized system prompt is automatically included to support this feature. + + +What you’re billed for is the same regardless of the `display` setting; only what you see changes: + +| | `display: "summarized"` | `display: "omitted"` | +| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------- | +| **Input tokens** | Tokens in your original request | Same as summarized | +| **Output tokens (billed)** | The full thinking tokens Claude generated internally | Same as summarized | +| **Output tokens (visible)** | The summarized thinking text | Zero thinking tokens (the `thinking` field is empty) | +| **Summary generation** | No charge | Not applicable | + + + The billed output token count does **not** match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response. + + +To see how many billed output tokens were spent on internal reasoning, read `usage.output_tokens_details.thinking_tokens` in the response. This value reflects the raw reasoning the model generated (not the summarized text returned in the body) and is always less than or equal to `output_tokens`. Subtract it from `output_tokens` to approximate the non-reasoning portion of the output. When streaming, this breakdown appears only on the final `message_delta` event. + +```json +{ + "usage": { + "input_tokens": 25, + "output_tokens": 348, + "output_tokens_details": { + "thinking_tokens": 312 + } + } +} +``` + +`output_tokens` remains the inclusive, authoritative total used for billing. `output_tokens_details` is a read-only breakdown for observability. For complete pricing information including base rates, cache writes, cache hits, and output tokens, see [Pricing](https://platform.claude.com/docs/en/about-claude/pricing). + +## Next steps + + + + Turn thinking on, read thinking output, and check per-model support. + + + + Preserve thinking blocks across tool calls and manage thinking in multi-turn conversations. + + + + Control how much thinking and output Claude allocates for each request. + + + + diff --git a/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking.md b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking.md new file mode 100644 index 00000000..e5a8c400 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/claude-build-with-claude-thinking.md @@ -0,0 +1,1319 @@ +--- +title: Thinking +url: https://platform.claude.com/docs/en/build-with-claude/thinking +description: "Understand how Claude's thinking works: turn it on, read thinking output, steer thinking depth with effort, and use thinking with tools, caching, and streaming." +featureMetadata: + status: stable + zdr: + eligibility: eligible + note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). + supportedModels: + - claude-fable-5-1 + - claude-mythos-5-1 + - claude-fable-5 + - claude-mythos-5 + - claude-mythos-preview + - claude-opus-5-5 + - claude-opus-5 + - claude-sonnet-5-5 + - claude-sonnet-5 + - claude-haiku-5-5 + - claude-haiku-4-5-20251001 + - claude-opus-4-8 + - claude-opus-4-7 + - claude-opus-4-6 + - claude-sonnet-4-6 + - claude-opus-4-5-20251101 + - claude-sonnet-4-5-20250929 + supportedPlatforms: + Claude API: stable + Claude Platform on AWS: stable + Claude Models on Google Cloud (Anthropic managed): stable + Amazon Bedrock: stable + Amazon Bedrock (InvokeModel): stable + Claude Models on Google Cloud (Google managed): stable + Microsoft Foundry: stable +--- + +**API support**: Usage differs by product. + +* **Messages API**: On by default. `thinking: {"type": "disabled"}` turns it off on models that accept that value. Where it is off by default, set `thinking` to turn it on. +* **Managed Agents**: Always on. Managed Agents sets the thinking configuration; the agent definition has no `thinking` field. + +A model that answers in a single pass has to get everything right on the first try: no scratch work, no checking, no changing approach halfway through. For a proof, a tricky bug, or a long agentic task, the first approach is often not the best one. + +Thinking removes that constraint. When thinking is active, Claude works through the problem in its own words before answering: it restates what is being asked, tries approaches, checks intermediate results, and abandons paths that do not hold up. That up-front thinking arrives in `thinking` content blocks ahead of the response, and Claude draws on it to produce the final answer. This is why thinking improves performance on complex tasks such as math, coding, analysis, and long-running agentic work, where the quality of the answer depends on intermediate work that would otherwise be compressed into the response itself or skipped. + +Thinking has a cost: the tokens Claude spends reasoning are billed as output tokens, even when the thinking text isn’t returned to you, and they count toward `max_tokens` alongside the response text. This page covers how thinking behaves across the API surface: turning it on, reading its output, and managing its interactions with tools, streaming, caching, and the context window. + +## How thinking works + + + ![Diagram: Claude determines whether to think up front, might think between tool calls, and returns thinking blocks before text](https://platform.claude.com/docs/images/how-thinking-works.svg) + + +Whether Claude thinks on a given request, and how deeply, depends on your thinking configuration and the complexity of the request. + +Here is what up-front thinking looks like in a response: one or more `thinking` content blocks arrive before the `text` blocks. The thinking block is still generated content, like the `text` block that follows it, but it is separated from the canonical response. Each thinking block also carries a `signature` field, an encrypted copy of the full reasoning that you pass back unchanged in multi-turn and tool-use conversations (see [Thinking encryption](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-encryption)): + +```json +{ + "content": [ + { + "type": "thinking", + "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...", + "signature": "WaUjzkypQ2mUEVM36O2Txu...." + }, + { + "type": "text", + "text": "Based on my analysis..." + } + ] +} +``` + +You don’t always see this text, and what you see is never the raw chain of thought: the text in a thinking block is a [summary of Claude’s reasoning](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking). The `display` field on the thinking configuration controls whether that summary is returned at all: `"summarized"` returns it, whereas `"omitted"`, the default on many models, returns thinking blocks with an empty `thinking` field. Either way the block is billed the same and passed back the same in multi-turn conversations. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) for per-model defaults and details. + +If Claude uses tools, thinking can also appear between tool calls. See [Thinking with tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). For the full response format, see the [Messages API reference](https://platform.claude.com/docs/en/api/messages/create). + +## Configuring thinking + +On most models, thinking is on by default or needs only one parameter. The following table shows what each model does with each `thinking` value a request can send. A 400 error means the API rejects the request, and [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting) has each error and its fix. + +| Model | No `thinking` field | `"adaptive"` | `"enabled"` with `budget_tokens` | `"between_tools"` | `"disabled"` | +| --------------------- | ------------------- | ----------------- | -------------------------------- | ----------------------------------------------- | -------------------------------------- | +| Claude Opus 5.5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | 400 error | +| Claude Sonnet 5.5 | Adaptive thinking | Adaptive thinking | 400 error | Up-front thinking off at `high` effort or below | 400 error | +| Claude Haiku 5.5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | Thinking off at `high` effort or below | +| Claude Fable 5.1 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | 400 error | +| Claude Mythos 5.1 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | 400 error | +| Claude Fable 5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | 400 error | +| Claude Mythos 5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | 400 error | +| Claude Opus 5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | Thinking off at `high` effort or below | +| Claude Sonnet 5 | Adaptive thinking | Adaptive thinking | 400 error | 400 error | Thinking off | +| Claude Opus 4.8 | Thinking off | Adaptive thinking | 400 error | 400 error | Thinking off | +| Claude Opus 4.7 | Thinking off | Adaptive thinking | 400 error | 400 error | Thinking off | +| Claude Mythos Preview | Adaptive thinking | Adaptive thinking | Extended thinking | 400 error | 400 error | +| Claude Opus 4.6 | Thinking off | Adaptive thinking | Extended thinking (deprecated) | 400 error | Thinking off | +| Claude Sonnet 4.6 | Thinking off | Adaptive thinking | Extended thinking (deprecated) | 400 error | Thinking off | +| Claude Opus 4.5 | Thinking off | 400 error | Extended thinking | 400 error | Thinking off | +| Claude Sonnet 4.5 | Thinking off | 400 error | Extended thinking | 400 error | Thinking off | +| Claude Haiku 4.5 | Thinking off | 400 error | Extended thinking | 400 error | Thinking off | + +In the table, “at `high` effort or below” means the request works at `low`, `medium`, and `high` effort and returns a 400 error at `xhigh` or `max`. + +On Claude 5 and later models and Claude Mythos Preview, thinking is already on and needs no configuration. `display` defaults to `"omitted"` on these models, so the thinking text is hidden until you opt in. Opt in with `thinking: {"type": "adaptive", "display": "summarized"}`, as the following examples do. + +On Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6, thinking is off until you set `thinking: {type: "adaptive"}`, which lets Claude determine when and how deeply to think based on the request. The same request, with the [model string](https://platform.claude.com/docs/en/models/overview) swapped, turns it on there. The following examples set `display: "summarized"` so the thinking text is visible, and use a large `max_tokens`: + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 16000, + "thinking": { + "type": "adaptive", + "display": "summarized" + }, + "messages": [ + { + "role": "user", + "content": "What is the greatest common divisor of 1071 and 462?" + } + ] + }' + ``` + + ```bash CLI + ant messages create \ + --model claude-opus-5-5 \ + --max-tokens 16000 \ + --thinking '{type: adaptive, display: summarized}' \ + --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=16000, + thinking={"type": "adaptive", "display": "summarized"}, + messages=[ + { + "role": "user", + "content": "What is the greatest common divisor of 1071 and 462?", + } + ], + ) + + for block in response.content: + match block.type: + case "thinking": + print(f"\nThinking: {block.thinking}") + case "text": + print(f"\nResponse: {block.text}") + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { + type: "adaptive", + display: "summarized" + }, + messages: [ + { + role: "user", + content: "What is the greatest common divisor of 1071 and 462?" + } + ] + }); + + for (const block of response.content) { + switch (block.type) { + case "thinking": + console.log(`\nThinking: ${block.thinking}`); + break; + case "text": + console.log(`\nResponse: ${block.text}`); + break; + } + } + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 16000, + Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, + Messages = [ + new UserMessageParam { Content = "What is the greatest common divisor of 1071 and 462?" } + ] + }; + + var message = await client.Messages.Create(parameters); + + foreach (var block in message.Content) + { + if (block.TryPickThinking(out ThinkingBlock? thinking)) + { + Console.WriteLine($"\nThinking: {thinking.Thinking}"); + } + else if (block.TryPickText(out TextBlock? text)) + { + Console.WriteLine($"\nResponse: {text.Text}"); + } + } + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ + Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), + }, + }) + if err != nil { + log.Fatal(err) + } + + for _, block := range response.Content { + switch v := block.AsAny().(type) { + case anthropic.ThinkingBlock: + fmt.Printf("\nThinking: %s", v.Thinking) + case anthropic.TextBlock: + fmt.Printf("\nResponse: %s", v.Text) + } + } + ``` + + ```java Java + import com.anthropic.models.messages.ThinkingConfigAdaptive; + + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder() + .display(ThinkingConfigAdaptive.Display.SUMMARIZED) + .build()) + .addUserMessage("What is the greatest common divisor of 1071 and 462?") + .build(); + + Message response = client.messages().create(params); + + response.content().forEach(block -> { + block.thinking().ifPresent(thinkingBlock -> + IO.println("\nThinking: " + thinkingBlock.thinking()) + ); + block.text().ifPresent(textBlock -> + IO.println("\nResponse: " + textBlock.text()) + ); + }); + } + ``` + + ```php PHP + use Anthropic\Messages\Model; + use Anthropic\Messages\TextBlock; + use Anthropic\Messages\ThinkingBlock; + + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 16000, + messages: [ + [ + 'role' => 'user', + 'content' => 'What is the greatest common divisor of 1071 and 462?' + ] + ], + model: Model::CLAUDE_OPUS_5_5, + thinking: ['type' => 'adaptive', 'display' => 'summarized'], + ); + + foreach ($message->content as $block) { + switch (true) { + case $block instanceof ThinkingBlock: + echo "\nThinking: " . $block->thinking; + break; + case $block instanceof TextBlock: + echo "\nResponse: " . $block->text; + break; + } + } + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 16000, + thinking: { + type: "adaptive", + # A plain hash like this one takes display:. The typed ThinkingConfigAdaptive class + # spells it display_ (trailing underscore) to avoid shadowing Ruby's Kernel#display. + # The request still sends display. + display: "summarized" + }, + messages: [ + { + role: "user", + content: "What is the greatest common divisor of 1071 and 462?" + } + ] + ) + + message.content.each do |block| + case block + when Anthropic::Models::ThinkingBlock + puts "\nThinking: #{block.thinking}" + when Anthropic::Models::TextBlock + puts "\nResponse: #{block.text}" + end + end + ``` + + +The response carries the summarized thinking, then the answer: + +```text Output wrap +Thinking: Use Euclidean algorithm. +1071 = 2*462 + 147 +462 = 3*147 + 21 +147 = 7*21 + 0 +GCD = 21 + +Response: ## Finding GCD of 1071 and 462 + +I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders... +``` + +Thinking tokens count toward `max_tokens`, so set it high enough to leave room for both the thinking and the response text. See [Cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#cost-control) on the steering page and [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window). + +### Turning thinking off + +On Claude Sonnet 5, where thinking is on by default, you can turn it off: + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-sonnet-5", + "max_tokens": 4096, + "thinking": {"type": "disabled"}, + "messages": [ + { + "role": "user", + "content": "Summarize this article in one sentence." + } + ] + }' + ``` + + ```bash CLI + ant messages create \ + --model claude-sonnet-5 \ + --max-tokens 4096 \ + --thinking '{type: disabled}' \ + --message '{role: user, content: "Summarize this article in one sentence."}' + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-sonnet-5", + max_tokens=4096, + thinking={"type": "disabled"}, + messages=[{"role": "user", "content": "Summarize this article in one sentence."}], + ) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-sonnet-5", + max_tokens: 4096, + thinking: { type: "disabled" }, + messages: [{ role: "user", content: "Summarize this article in one sentence." }] + }); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeSonnet5, + MaxTokens = 4096, + Thinking = new ThinkingConfigDisabled(), + Messages = [new UserMessageParam { Content = "Summarize this article in one sentence." }] + }; + + var message = await client.Messages.Create(parameters); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet5, + MaxTokens: 4096, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfDisabled: &anthropic.ThinkingConfigDisabledParam{}, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Summarize this article in one sentence.")), + }, + }) + if err != nil { + log.Fatal(err) + } + ``` + + ```java Java + import com.anthropic.models.messages.ThinkingConfigDisabled; + + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_5) + .maxTokens(4096L) + .thinking(ThinkingConfigDisabled.builder().build()) + .addUserMessage("Summarize this article in one sentence.") + .build(); + + Message response = client.messages().create(params); + } + ``` + + ```php PHP + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 4096, + messages: [ + [ + 'role' => 'user', + 'content' => 'Summarize this article in one sentence.' + ] + ], + model: Model::CLAUDE_SONNET_5, + thinking: ['type' => 'disabled'], + ); + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_SONNET_5, + max_tokens: 4096, + thinking: { type: "disabled" }, + messages: [ + { + role: "user", + content: "Summarize this article in one sentence." + } + ] + ) + ``` + + +Claude Opus 5 also has thinking on by default and accepts `thinking: {type: "disabled"}` at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max` effort, thinking cannot be turned off: requests that combine `thinking: {type: "disabled"}` with those effort levels return a 400 error. This restriction is enforced on each request. With thinking disabled, Claude Opus 5 can occasionally emit tool calls as plain text or include internal XML tags in its visible output. See [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for prompting mitigations. + +Claude Sonnet 5.5 also has thinking on by default, and it rejects `thinking: {type: "disabled"}` with a 400 error. To turn off up-front thinking, send `thinking: {type: "between_tools"}` instead. It’s the lowest thinking setting on Claude Sonnet 5.5, and it’s accepted at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. The model still returns its [progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates). Without tools, the response contains only text, as with `disabled` on Claude Sonnet 5. See [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) for prompting guidance. + +Claude Haiku 5.5 also has thinking on by default and accepts `thinking: {type: "disabled"}` at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max` effort, that combination returns a 400 error. To get less thinking, lower the effort level first. With thinking off, the model can skip a tool call it needs when you also request JSON output. A [per-message `output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) that differs from the level in effect also returns a 400 error while thinking is off. See [Use effort to control thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) and [Use adaptive thinking with JSON output and your own tools](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools). + +Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, and Claude Mythos Preview reject `thinking: {type: "disabled"}`. Thinking can’t be turned off on these models. + +To check whether a model accepts `"disabled"` or `"between_tools"` before you send a request, read its `capabilities.thinking.types.disabled.supported` or `capabilities.thinking.types.between_tools.supported` value from the Models API. [Using the Models API](https://platform.claude.com/docs/en/models/overview#using-the-models-api) describes both fields. + +If your model supports only extended thinking (see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models)), configure it with `type: "enabled"` and a `budget_tokens` value instead. The [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) page covers that configuration. And if any thinking configuration comes back with a 400 error, [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting) matches each error message to its fix. + +## Reading thinking output + +### Controlling thinking display + +The `display` field on the thinking configuration controls how thinking content is returned in API responses. `display` works in both modes: set it alongside `type: "adaptive"` or `type: "enabled"`. It accepts these values: + +* `"summarized"`: thinking blocks contain [summarized thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking) text, a readable summary of Claude’s reasoning. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier models. +* `"omitted"`: thinking blocks are returned with an empty `thinking` field. The `signature` field still carries the encrypted full thinking for multi-turn continuity (see [Thinking encryption](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-encryption)). This is the default on Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, [Claude Mythos Preview](https://anthropic.com/glasswing), and Claude Haiku 5.5. +* `"updates"` (beta): reasoning blocks are returned with an empty `thinking` field, as with `"omitted"`, and the short [progress updates](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) some models write between tool calls come back as readable text. Requires the beta header `thinking-display-updates-2026-08-18`. + +Set `display: "omitted"` when your application doesn’t surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: the server skips streaming thinking tokens entirely and delivers only the signature, so the final text response starts streaming sooner. + +With `display: "omitted"`, the response contains `thinking` blocks with an empty `thinking` field: + +```json Output +{ + "content": [ + { + "type": "thinking", + "thinking": "", + "signature": "EosnCkYICxIMMb3LzNrMu..." + }, + { + "type": "text", + "text": "The answer is 12,231." + } + ] +} +``` + +Keep the following in mind when working with omitted thinking: + +* You’re still charged for the full thinking tokens. Omitting reduces latency, not cost. +* If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the `signature` to reconstruct the original thinking for prompt construction (see [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks)). Any text you place in the `thinking` field of a round-tripped omitted block is ignored. +* `display` is invalid with `thinking.type: "disabled"` (there is nothing to display) and with `thinking.type: "between_tools"` (Claude Sonnet 5.5 only), which accepts no other field. With `between_tools`, progress updates still come back with summary text, as they do under `display: "updates"` (see [Progress updates](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates)). +* When you use `thinking.type: "adaptive"` and the model skips thinking for a simple request, no thinking block is produced regardless of `display`. +* When streaming with `display: "omitted"`, no thinking text is streamed. Each thinking block streams a `thinking_delta` with an empty `thinking` string, then its `signature_delta`. With `display: "updates"`, only [progress-update blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) stream `thinking_delta` events that carry text. See [Streaming thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking) for the event sequence. + + + The `signature` field is identical whichever `display` value you set. Switching `display` values between turns in a conversation is supported. + + +### Summarized thinking + +When `display` is `"summarized"`, the thinking text you receive is a summary of Claude’s full thinking process rather than the raw chain of thought. Summarized thinking provides the full intelligence benefits of thinking while preventing misuse. No `display` setting returns the raw chain of thought. + +Keep the following in mind when working with summarized thinking: + +* You’re charged for the full thinking tokens generated by the original request, not the summary tokens. The billed output token count does not match the count of tokens you see in the response. +* On Claude Opus 4.6, Claude Sonnet 4.6, and earlier models, the first few lines of thinking output are more verbose, providing detailed reasoning that’s particularly helpful for prompt engineering purposes. [Claude Mythos Preview](https://anthropic.com/glasswing) summarizes from the first token, so its thinking blocks do not show this verbose preamble. +* Summarization preserves the key ideas of Claude’s thinking process with minimal added latency, so summaries can stream as they arrive. +* Summarization is processed by a different model from the one you target in your requests. The thinking model does not receive the summarized output. + + + In rare cases where you need access to full thinking output, [contact Anthropic sales](mailto:sales@anthropic.com). + + +To see the model’s reasoning, read the `thinking` blocks rather than prompting for reasoning in the response text. On Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Fable 5, a request that attempts to elicit the model’s internal reasoning as part of the response text might be refused with `stop_details.category: "reasoning_extraction"`. See [What a refusal looks like](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the field reference and [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks) for what to ask for instead. + +### Streaming thinking + +Thinking works with [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming). Thinking blocks stream as `thinking_delta` events inside `content_block_delta` events, followed by a single `signature_delta` event just before the block’s `content_block_stop`. Text blocks stream afterward as usual. + + + ![Thinking stream: the block opens, deltas carry text only if display returns text, one signature delta closes it, then text](https://platform.claude.com/docs/images/how-thinking-streams.svg) + + +The following examples stream a response with adaptive thinking, printing thinking and text deltas as they arrive: + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 16000, + "stream": true, + "thinking": { + "type": "adaptive", + "display": "summarized" + }, + "messages": [ + { + "role": "user", + "content": "What is the greatest common divisor of 1071 and 462?" + } + ] + }' + ``` + + ```bash CLI + ant messages create \ + --model claude-opus-5-5 \ + --max-tokens 16000 \ + --thinking '{type: adaptive, display: summarized}' \ + --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ + --stream \ + --format jsonl + ``` + + ```python Python + client = anthropic.Anthropic() + + with client.messages.stream( + model="claude-opus-5-5", + max_tokens=16000, + thinking={"type": "adaptive", "display": "summarized"}, + messages=[ + { + "role": "user", + "content": "What is the greatest common divisor of 1071 and 462?", + } + ], + ) as stream: + for event in stream: + match event.type: + case "content_block_start": + print(f"\nStarting {event.content_block.type} block...") + case "content_block_delta": + delta = event.delta + match delta.type: + case "thinking_delta": + print(delta.thinking, end="", flush=True) + case "text_delta": + print(delta.text, end="", flush=True) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const stream = client.messages.stream({ + model: "claude-opus-5-5", + max_tokens: 16000, + thinking: { type: "adaptive", display: "summarized" }, + messages: [{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }] + }); + + for await (const event of stream) { + switch (event.type) { + case "content_block_start": + console.log(`\nStarting ${event.content_block.type} block...`); + break; + case "content_block_delta": + switch (event.delta.type) { + case "thinking_delta": + process.stdout.write(event.delta.thinking); + break; + case "text_delta": + process.stdout.write(event.delta.text); + break; + } + break; + } + } + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 16000, + Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, + Messages = [new UserMessageParam { Content = "What is the greatest common divisor of 1071 and 462?" }] + }; + + await foreach (var rawEvent in client.Messages.CreateStreaming(parameters)) + { + if (rawEvent.TryPickContentBlockStart(out var start)) + { + Console.WriteLine($"\nStarting {start.ContentBlock.Type.Raw()} block..."); + } + else if (rawEvent.TryPickContentBlockDelta(out var delta)) + { + if (delta.Delta.TryPickThinking(out var thinkingDelta)) + { + Console.Write(thinkingDelta.Thinking); + } + else if (delta.Delta.TryPickText(out var textDelta)) + { + Console.Write(textDelta.Text); + } + } + } + ``` + + ```go Go + client := anthropic.NewClient() + + stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{ + OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ + Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, + }, + }, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), + }, + }) + + for stream.Next() { + event := stream.Current() + switch eventVariant := event.AsAny().(type) { + case anthropic.ContentBlockStartEvent: + fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type) + case anthropic.ContentBlockDeltaEvent: + switch deltaVariant := eventVariant.Delta.AsAny().(type) { + case anthropic.ThinkingDelta: + fmt.Print(deltaVariant.Thinking) + case anthropic.TextDelta: + fmt.Print(deltaVariant.Text) + } + } + } + if err := stream.Err(); err != nil { + log.Fatal(err) + } + ``` + + ```java Java + import com.anthropic.models.messages.ThinkingConfigAdaptive; + + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder() + .display(ThinkingConfigAdaptive.Display.SUMMARIZED) + .build()) + .addUserMessage("What is the greatest common divisor of 1071 and 462?") + .build(); + + try (var streamResponse = client.messages().createStreaming(params)) { + streamResponse.stream().forEach(event -> { + switch (event.type().value()) { + case CONTENT_BLOCK_START -> { + var startEvent = event.asContentBlockStart(); + var block = startEvent.contentBlock(); + switch (block.type().value()) { + case THINKING -> IO.println("\nStarting thinking block..."); + case TEXT -> IO.println("\nStarting text block..."); + } + } + case CONTENT_BLOCK_DELTA -> { + var deltaEvent = event.asContentBlockDelta(); + deltaEvent.delta().thinking().ifPresent(thinkingDelta -> + IO.print(thinkingDelta.thinking()) + ); + deltaEvent.delta().text().ifPresent(textDelta -> + IO.print(textDelta.text()) + ); + } + } + }); + } + } + ``` + + ```php PHP + use Anthropic\Messages\Model; + use Anthropic\Messages\RawContentBlockDeltaEvent; + use Anthropic\Messages\RawContentBlockStartEvent; + use Anthropic\Messages\TextDelta; + use Anthropic\Messages\ThinkingDelta; + + $client = new Client(); + + $stream = $client->messages->createStream( + maxTokens: 16000, + messages: [ + ['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?'] + ], + model: Model::CLAUDE_OPUS_5_5, + thinking: ['type' => 'adaptive', 'display' => 'summarized'], + ); + + foreach ($stream as $event) { + switch (true) { + case $event instanceof RawContentBlockStartEvent: + echo "\nStarting {$event->contentBlock->type} block...\n"; + break; + case $event instanceof RawContentBlockDeltaEvent: + switch (true) { + case $event->delta instanceof ThinkingDelta: + echo $event->delta->thinking; + break; + case $event->delta instanceof TextDelta: + echo $event->delta->text; + break; + } + break; + } + } + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + stream = client.messages.stream( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 16000, + # A plain hash like this one takes display:. The typed ThinkingConfigAdaptive class + # spells it display_ (trailing underscore) to avoid shadowing Ruby's Kernel#display. + # The request still sends display. + thinking: { type: "adaptive", display: "summarized" }, + messages: [ + { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } + ] + ) + + stream.each do |event| + case event + when Anthropic::Streaming::ThinkingEvent + print event.thinking + when Anthropic::Streaming::TextEvent + print event.text + end + end + ``` + + +To reassemble complete thinking blocks with their signatures after streaming, use your SDK’s message-accumulation helper, `stream.get_final_message()` (typescript: `stream.finalMessage()`; ruby: `stream.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`), instead of concatenating deltas yourself. + + + ```sse Output + event: message_start + data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null}} + + event: content_block_start + data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}} + + event: content_block_delta + data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}} + + event: content_block_delta + data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}} + + // Additional thinking deltas... + + event: content_block_delta + data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}} + + event: content_block_stop + data: {"type": "content_block_stop", "index": 0} + + event: content_block_start + data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}} + + event: content_block_delta + data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}} + + // Additional text deltas... + + event: content_block_stop + data: {"type": "content_block_stop", "index": 1} + + event: message_delta + data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}} + + event: message_stop + data: {"type": "message_stop"} + ``` + + +When `display: "omitted"` is set, the thinking block opens, a `thinking_delta` with an empty `thinking` string arrives, a single `signature_delta` follows, and the block closes. Text streaming starts immediately after: + +```sse Output +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: content_block_start +data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}} +``` + +With `display: "updates"` (beta), reasoning blocks stream as they do under `"omitted"`. Each [progress-update block](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) streams its text as `thinking_delta` events before the `tool_use` block it introduces. A pause of several seconds before the progress-update block opens is normal: + +```sse Output +event: content_block_start +data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}} + +event: content_block_delta +data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}} + +event: content_block_stop +data: {"type":"content_block_stop","index":1} + +event: content_block_start +data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}} +``` + +Under `"updates"`, treat a block as a progress update as soon as one of its `thinking_delta` events carries non-empty text. + + + When using streaming with thinking enabled, you might notice that text sometimes arrives in larger chunks alternating with smaller, token-by-token delivery. This is expected behavior, especially for thinking content. + + The streaming system processes content in batches, which can delay and group streaming events into this “chunky” delivery pattern. + + +For general streaming mechanics, see [Streaming messages](https://platform.claude.com/docs/en/build-with-claude/streaming). + +## Thinking and effort + +The `thinking` parameter controls whether Claude thinks in [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking) before answering; the `effort` parameter controls how much work Claude puts into the whole response, which in adaptive mode includes how often and how deeply it thinks. Don’t pass `adaptive` as an `effort` value: `adaptive` is a thinking mode, not an effort level. + +To learn what each effort level does to thinking behavior, see the [per-level thinking behavior table](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#effort-levels) on the [Steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost) page. The [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) page documents the parameter itself, including which levels each model supports. On Claude Opus 4.5, the only extended-thinking-only model that supports effort, effort composes with `budget_tokens`. See [Budget rules and tuning](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#budget-rules-and-tuning). + +With the two controls separated this way, pick the one that matches your goal: + +* **Lower cost or latency on a thinking-enabled workload:** lower `effort` first. It scales the whole response down, thinking included. +* **Claude is thinking too rarely or too shallowly:** raise `effort`, or see [Steering how often Claude thinks](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior) on the steering page. +* **You need thinking fully off:** use `thinking: {type: "disabled"}` on models that allow it (see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models)). Claude Sonnet 5.5 rejects `"disabled"`. Its lowest setting is `thinking: {type: "between_tools"}`, which turns off up-front thinking. +* **You need a hard ceiling on spend:** use `max_tokens`. Effort is soft guidance. `max_tokens` is a strict limit. + +## Thinking with tool use + +Thinking works alongside [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), letting Claude reason through tool selection and process tool results. Two constraints apply: + +1. **Tool choice limitation (manual mode):** tool use with manual extended thinking (`thinking: {type: "enabled"}`) only supports `tool_choice: {"type": "auto"}` (the default) or `tool_choice: {"type": "none"}`. Using `tool_choice: {"type": "any"}` or `tool_choice: {"type": "tool", "name": "..."}` results in an error because these options force tool use, which is incompatible with manual extended thinking. Adaptive thinking, including on models where thinking is on by default, supports forced tool use, except on Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 (see [Response prefill and forced tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#limits-and-feature-compatibility)). Where forced tool use is accepted, the response starts with the tool call and has no `thinking` block. +2. **Preserving thinking blocks:** when you return tool results, you must pass the thinking blocks from the assistant message back to the API, complete and unmodified. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). + +**A tool-use loop is one assistant turn.** From the model’s perspective, an assistant turn ends only when Claude completes its full response, which might include multiple tool calls and results. This whole sequence is a single assistant turn: + +```text wrap +User: "What's the weather in Paris?" +Assistant: [thinking] + [tool_use: get_weather] +User: [tool_result: "20°C, sunny"] +Assistant: [text: "The weather in Paris is 20°C and sunny"] +``` + +The entire turn runs in a single thinking mode: you can’t toggle thinking in the middle of a turn, including during the tool-use loop. In extended (manual) mode, the API additionally enforces that the final assistant turn of a thinking-enabled request starts with a thinking block. Adaptive mode relaxes this: no assistant turn needs to start with one. + +**Mid-turn conflicts degrade gracefully.** If you toggle thinking mid-turn (for example, between sending a tool call and returning its result), the API doesn’t error. Instead, it silently disables thinking for that request. To preserve model quality, the API might strip thinking blocks that would create an invalid turn structure, or disable thinking when the conversation history is incompatible with thinking being enabled. To confirm whether thinking was active, check for the presence of `thinking` blocks in the response. + +**Toggle between turns, not within them.** Plan your thinking strategy at the start of each turn. Complete the assistant turn, then change the thinking configuration for the next one: + +```text wrap +User: "What's the weather?" +Assistant: [tool_use] (thinking disabled) +User: [tool_result] +Assistant: [text: "It's sunny"] +User: "What about tomorrow?" +Assistant: [thinking] + [text: "..."] (thinking enabled - new turn) +``` + +Toggling thinking modes also invalidates prompt caching. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). + +### Preserving thinking blocks + +When Claude calls a tool, it pauses construction of its response to await external information. When you return the tool result, Claude continues building that same response, so its earlier reasoning must still be present. Pass every `thinking` block back to the API complete and unmodified, alongside the `tool_use` block it accompanied. This matters for two reasons: + +1. **Reasoning continuity:** the thinking blocks capture the step-by-step reasoning that led to the tool requests. Including them lets Claude continue reasoning from where it left off. +2. **Context maintenance:** tool results appear as user messages in the API structure, but they’re part of one continuous reasoning flow. Preserving thinking blocks maintains that flow across API calls. + +In short: + +* **Required:** within a tool-use turn, pass thinking blocks back. +* **Recommended:** across turns, pass everything back. +* **Allowed:** outside tool use, omit prior turns’ thinking. + +You don’t need to prune old thinking yourself. Pass all thinking blocks back in multi-turn conversations, and the API automatically filters them, keeps the blocks needed to preserve the model’s reasoning, and bills input tokens only for the blocks actually shown to Claude. Which prior-turn blocks are kept is per-model. See [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model). To override the default, use the [`clear_thinking_20251015` context-editing strategy](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing). + +Within the latest assistant message, the sequence of consecutive `thinking` blocks must match what the model generated in the original request: you can’t rearrange, edit, or partially drop them. This includes [`redacted_thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#redacted-thinking-blocks). + + + Modified thinking blocks are rejected with a 400 error. See [A 400 error says thinking blocks cannot be modified](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) for the exact message, the common causes, and the fix. The one exception: text placed in the empty `thinking` field of an [omitted](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) block is ignored rather than rejected. + + +For a worked example with code in every SDK, see [Walk through a two-turn tool-use round trip](https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip). It defines a tool, receives a thinking-plus-tool-use response, and echoes the assistant turn back with the tool result. + +### Interleaved thinking + +Interleaved thinking lets Claude think between tool calls, reasoning about each tool result before acting on it. With interleaved thinking, Claude can: + +* Reason about the results of a tool call before determining what to do next +* Chain multiple tool calls with reasoning steps in between +* Make more nuanced decisions based on intermediate results + + + Consecutive tool calls do not require interleaved thinking. Claude can chain tool calls with or without interleaved thinking. Interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain. + + +With adaptive thinking, interleaved thinking is automatic on every model that supports adaptive thinking. No beta header is needed. On Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8, and Claude Opus 4.7, reasoning between tool calls always appears in thinking blocks. Claude Haiku 4.5 does not support interleaved thinking. On models using manual extended thinking, interleaving requires a beta header and changes how the thinking budget is counted. [Interleaved thinking in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) covers the per-model rules and platform-specific header behavior. + +With interleaved thinking, the thinking allocation can span the entire assistant turn rather than a single response. Interleaved thinking is only supported for [tools used through the Messages API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview). + +For a worked comparison showing what interleaved thinking changes in a two-tool workflow, see [How interleaved thinking changes the flow](https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows#how-interleaved-thinking-changes-the-flow). + +### Progress updates between tool calls + +On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Fable 5, the model can write a progress update between tool calls. A progress update is a note on what the model just found and what it’s about to do next, written for the person watching the agent rather than as reasoning. Each one comes back as its own `thinking` block with its own `signature`, separate from any reasoning block at the same point. It sits immediately before the `tool_use` or `server_tool_use` block it introduces. At most one progress update precedes each tool call, and the model can skip any of them. Progress updates aren’t [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking): they appear whether or not reasoning blocks appear between tool calls, and a response can contain both. + +What a progress-update block contains depends on [`display`](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display): + +| `display` | Reasoning blocks | Progress-update blocks | +| ----------------------------------------- | ---------------------- | -------------------------------------------------------- | +| `"omitted"` (the default on these models) | Empty `thinking` field | Empty `thinking` field | +| `"updates"` (beta) | Empty `thinking` field | Summary text | +| `"summarized"` | Summary text | Summary text, not distinguishable from a reasoning block | + +On Claude Sonnet 5.5, the lowest thinking setting is `thinking: {type: "between_tools"}`. It turns off up-front thinking, and each progress update comes back with its summary text, as it would under `display: "updates"`. `between_tools` is accepted only at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. At `xhigh` or `max`, a request with it returns a 400 error. `between_tools` takes no other field: `display`, `budget_tokens`, or `block_binding` sent with it returns a 400 error. The setting needs no beta header and works on every platform that offers Claude Sonnet 5.5. Pass the blocks back unchanged: a progress-update block you send back gives the model the full note it wrote, not the summary. + +Use `display: "updates"` for an agent interface that keeps reasoning hidden and shows the user a status line at each step. Under it, any `thinking` block with non-empty text is a progress update, so render those and nothing else. It’s in beta and requires the beta header `thinking-display-updates-2026-08-18` (to send it on Amazon Bedrock, Claude Models on Google Cloud (Google managed), or Microsoft Foundry, see [Beta features on other platforms](https://platform.claude.com/docs/en/api/beta-headers#beta-features-on-other-platforms)). Without it, the value is rejected with the same 400 `invalid_request_error` as an unknown `display` value. + +```json +{ + "model": "claude-fable-5-1", + "max_tokens": 16000, + "thinking": { "type": "adaptive", "display": "updates" }, + "tools": [ + { + "name": "edit_file", + "description": "Replace the contents of a file in the repository.", + "input_schema": { + "type": "object", + "properties": { + "path": { "type": "string" }, + "content": { "type": "string" } + }, + "required": ["path", "content"] + } + } + ], + "messages": [ + { + "role": "user", + "content": "The login test fails after an hour of uptime. Find out why and fix it." + } + ] +} +``` + +Under `"updates"`, the start of the response that follows a `tool_result` looks like this. The first block is reasoning and stays empty, as it would under `"omitted"`. The second carries text, so it’s a progress update. Under `"summarized"` both blocks carry text, and under `"omitted"` both are empty. + +```json Output +{ + "content": [ + { + "type": "thinking", + "thinking": "", + "signature": "EqMBCkYICxIM..." + }, + { + "type": "thinking", + "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.", + "signature": "Es8CCkYICxIM..." + }, + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "edit_file", + "input": { "path": "auth.py", "content": "..." } + } + ] +} +``` + +Keep the following in mind when working with progress updates: + +* Pass progress-update blocks back unchanged with the rest of the assistant turn, like any other `thinking` block. +* The text you receive is a summary of the progress update, normally a sentence or two. Don’t rely on its length. The progress update counts toward `usage.output_tokens` at its full length, not the summary’s. +* A progress-update block can come back with an empty `thinking` field under any `display` value. Render nothing for an empty block. Under `"updates"` it looks the same as an empty reasoning block and needs no separate handling. +* When a response stops on `max_tokens`, `model_context_window_exceeded`, or `stop_sequence` soon after a tool call or tool result, its last block can be a progress-update block standing in for the work the model hadn’t completed. Under `"updates"` and `"summarized"` its text is exactly `This part of the response was interrupted before it finished.` and you can show it like any other update. Under `"omitted"` it’s empty. To continue, pass the assistant turn back unchanged and append a new `user` message (with a `tool_result` for each `tool_use` block in that turn). +* When [streaming](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking), expect a pause of several seconds before a progress-update block opens. See the `"updates"` trace in [Streaming thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking). +* These models write fewer progress updates at higher [effort](https://platform.claude.com/docs/en/build-with-claude/effort) and in long tool chains. If your interface depends on them, see [Ask for user-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates). For Claude Opus 5.5 and Claude Sonnet 5.5, see User-facing progress updates in [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates) or [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates). + +### Thinking block preservation by model + +Whether thinking blocks from previous assistant turns stay in context by default depends on the model: + +* **Keep all prior turns:** Claude Opus 4.5 and later Opus models, Claude Sonnet 4.6 and later Sonnet models, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, and Claude Mythos Preview. +* **Keep only the turn in progress (last-turn-only models):** earlier Opus and Sonnet models, and all Haiku models through Claude Haiku 4.5. When you pass older thinking blocks back, the API strips them automatically. You don’t need to remove them yourself. + +Preservation brings two benefits: + +* **Cache optimization:** preserved thinking blocks allow cache hits during tool use, as they are passed back with tool results and cached incrementally across the assistant turn, resulting in token savings in multistep workflows. +* **No intelligence impact:** preserving thinking blocks has no negative effect on model performance. + +The tradeoff is context usage: long conversations consume more context space on keep-all models, because retained thinking blocks count as input like any other conversation history (see [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window)). The behavior is automatic in both regimes. No code changes or beta headers are required, and you should keep passing complete, unmodified thinking blocks back as described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). To override the default in either direction, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing). + +**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models, and the API ignores or drops the blocks the target model can’t read. On Claude Fable 5.1 and Claude Mythos 5.1 the direction matters: they read earlier models’ thinking blocks, and only the two of them read each other’s, so switching to them keeps the conversation’s reasoning and switching from them to any other model drops it (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 reads Claude Opus 5’s thinking blocks and those of earlier Opus, Sonnet, and Haiku models, and, on the Claude API and Claude Models on Google Cloud (Google managed), of Claude Sonnet 5.5 and Claude Haiku 5.5, but not those of the Claude Fable and Claude Mythos models; on the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning; a switch from Claude Fable 5.1 to Claude Opus 5.5 drops it. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Claude Models on Google Cloud (Google managed), from Claude Haiku 5.5, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks and no other model does: a switch from Claude Sonnet 5.5 up to Claude Opus 5.5 there keeps the earlier turns’ reasoning, and any other switch away from Claude Sonnet 5.5 drops it. Claude Haiku 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, but not from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5’s blocks and no other model does. Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them, and never when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged. + +## Preserved thinking + +[Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) determines whether the model can use a thinking block that you send back from an earlier turn. Starting with Claude Fable 5.1, the API checks the `signature` of every `thinking` or `redacted_thinking` block in a request for two things: + +* **The model that produced it.** Each model reads its own thinking blocks and those of a fixed set of other models. Claude Fable 5.1 reads blocks from Claude Opus 5 and, on the Claude API, from Claude Opus 5.5; neither Claude Opus 5 nor Claude Opus 5.5 reads blocks from Claude Fable 5.1. The API drops a block the current model can’t read, without an error and without billing it. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). +* **Everything sent before it.** A block stays valid only while the top-level `system` prompt, the `tools`, and the messages before it are unchanged. If any of them changes, that block and every later thinking block fail the prefix check. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). + +Thinking blocks from Claude Sonnet 5.5 and Claude Haiku 5.5 are also tied to the account that produced them. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) for where this applies. + +The prefix check runs on Claude 5.1 and later models. Make your integration append-only so that the thinking blocks you send back pass it. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) covers what happens when one fails. + +To keep thinking valid, send every assistant turn back exactly as you received it and add new messages only at the end of `messages`. If your code builds the `messages` array itself, the Preserved thinking page covers: + +* [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit), and [how to check whether your code makes an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). +* The [API feature that replaces each common edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits): mid-conversation system messages for new instructions and per-turn reminders, `tool_addition` and `tool_removal` blocks for tool changes, per-message `output_config` for effort changes, and server-side compaction and context editing for trimming. +* [Client-side compaction](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client): which patterns keep thinking valid and which don’t. +* The [`thinking-binding-controls-2026-08-01` beta header](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#preserved-thinking-controls). It adds a `block_binding.prefix_mismatch_behavior` field (`"error"` or `"drop_block"`) to the thinking configuration and an `input_transformations` array to every response. The array lists each thinking block that the API dropped or that failed the prefix check and reached the model. + +## Thinking and prompt caching + +[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) interacts with thinking in a few specific ways. The following rules apply in both thinking modes. + +**Configuration changes invalidate caching.** The thinking configuration and the resolved [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) level are rendered into the prompt itself, so changing any of them starts a new cache prefix. Switching between `adaptive`, `enabled`, and `disabled`, changing `budget_tokens`, and changing the effort value all invalidate cache breakpoints: message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Treat any thinking or top-level effort change as starting the cache over. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it. A thinking block the API drops under any [preserved-thinking condition](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) changes the cached prefix from that block’s position onward. Blocks passed back unchanged keep the cache intact. A worked demonstration with usage output is on the [Steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#prompt-caching) page. + +**Thinking blocks are cached with tool results.** During a tool-use loop, caching occurs when you make a follow-up request that includes tool results. At that point the previous conversation history, including its thinking blocks, can be cached, and those cached thinking blocks count as input tokens in your usage metrics when read from the cache. This occurs automatically, even without explicit `cache_control` markers, and behaves the same for regular and interleaved thinking. The tradeoff: thinking blocks you never see again in responses still contribute to input token usage when read from cache. + +**Whether prior blocks are in context at all is per-model.** The [preservation default](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model) governs this. On keep-all models, previous turns’ thinking blocks stay cached and in context. On last-turn-only models, once you send a user message that isn’t a tool result, all previous thinking blocks are stripped from context. On those models, a conversation like this: + +```text wrap +User: ["What's the weather in Paris?"], +Assistant: [thinking_block_1] + [tool_use block 1], +User: [tool_result_1, cache=True], +Assistant: [thinking_block_2] + [text block 2], +User: [Text response, cache=True] +``` + +is processed as if the thinking blocks were never there: + +```text wrap +User: ["What's the weather in Paris?"], +Assistant: [tool_use block 1], +User: [tool_result_1, cache=True], +Assistant: [text block 2], +User: [Text response, cache=True] +``` + +On keep-all models, the same request keeps `thinking_block_1` and `thinking_block_2` in context and in the cache. + +**Degradation strips thinking from the cacheable history.** If thinking becomes disabled mid-turn and you pass thinking content in the current tool-use turn, the thinking content is stripped and thinking remains disabled for that request (see [graceful degradation](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use)). [Interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking) amplifies cache invalidation effects, because thinking blocks can occur between multiple tool calls. + + + Thinking-heavy tasks often take longer than the default 5-minute cache lifetime to complete. Consider the [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) to maintain cache hits across longer thinking sessions and multistep workflows. + + +## Thinking and the context window + +`max_tokens`, which includes all thinking Claude generates in the current turn, is enforced as a strict limit. On Claude 4.5 models and newer, if input tokens plus `max_tokens` exceeds the context window size, the API accepts the request. If generation then reaches the context window limit, it stops with `stop_reason: "model_context_window_exceeded"` instead of returning an error. On earlier models, the API returns a validation error instead. See [Handling stop reasons](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons). + +How thinking counts against the window depends on when it was generated: + +* **Current-turn thinking** always counts toward `max_tokens`, is billed as output tokens, and occupies context window space for the turn that generated it. +* **Prior-turn thinking** depends on the [preservation default](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model). On [models that keep all prior turns](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model), previous thinking blocks remain in context, count toward the window, and are billed as input tokens like the rest of the conversation history. On models that keep only the last turn, the API strips older thinking blocks automatically when you pass them back, so they don’t consume window space or input tokens. + +In practice: + +* On keep-all models, budget your context window as if thinking were ordinary conversation history, because it is. Long agentic sessions accumulate thinking in context. Use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing) if you need to reclaim space. +* On last-turn-only models, thinking is a per-turn cost only: each turn’s thinking counts against that turn’s `max_tokens` and then drops out of the window. + +The following diagrams illustrate the last-turn-only (stripping) regime. The first shows a multi-turn conversation: each turn’s thinking block is generated in the output but not carried into later turns’ input. + + + ![Thinking on a model that strips previous thinking: each turn's thinking is generated but not carried into later turns' input](https://platform.claude.com/docs/images/context-window-thinking.svg) + + +The second shows the same regime with tool use: thinking stays in context alongside its tool result for the duration of the assistant turn, then drops out on the next user turn. + + + ![Thinking with tools on a model that strips previous thinking: thinking stays with its tool result until the next user turn](https://platform.claude.com/docs/images/context-window-thinking-tools.svg) + + +Use the [token counting API](https://platform.claude.com/docs/en/build-with-claude/token-counting) to get accurate counts for your specific use case, especially for multi-turn conversations that include thinking. + +## Thinking encryption + +Full thinking content is encrypted and returned in the `signature` field on each thinking block. The API uses the signature to verify that thinking blocks were generated by Claude when you pass them back. + +Keep the following in mind when working with signatures: + +* It is only strictly necessary to send back thinking blocks when [using tools with thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). Otherwise you can omit thinking blocks from previous turns. If you do pass them back, whether the API keeps or strips them depends on the model (see [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model)). Use [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) to configure this. +* When sending back thinking blocks, pass everything back exactly as you received it, for consistency and to avoid potential issues. +* When [streaming responses](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking), the signature arrives as a `signature_delta` inside a `content_block_delta` event just before the `content_block_stop` event. +* `signature` values are significantly longer in Claude 4 and later models than in previous models. +* The `signature` field is opaque: don’t interpret or parse it. +* `signature` values are compatible across platforms, including the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). Values generated on one platform work on another, except that thinking blocks from Claude Sonnet 5.5 and Claude Haiku 5.5 work only in the account that produced them or in an account linked to it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking). + +## Redacted thinking blocks + +In addition to regular `thinking` blocks, the API might return `redacted_thinking` blocks when portions of Claude’s reasoning are safety-redacted. A `redacted_thinking` block contains encrypted thinking content in a `data` field, with no readable text: + +```json +{ + "type": "redacted_thinking", + "data": "..." +} +``` + +The `data` field is opaque and encrypted. As with the `signature` field on regular thinking blocks, pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation with [tools](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). + + + If your code filters content blocks by type (for example, `block.type == "thinking"`) when round-tripping responses with tool use, also include `redacted_thinking` blocks. Filtering on `block.type == "thinking"` alone silently drops `redacted_thinking` blocks and breaks the multi-turn protocol described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). + + + + `redacted_thinking` blocks are a distinct content block type returned when thinking is safety-redacted. This is separate from the [`display: "omitted"`](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) option, which returns regular `thinking` blocks with an empty `thinking` field. + + +## Limits and feature compatibility + +### Sampling parameters + +On Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, and Claude Haiku 5.5, non-default `temperature`, `top_p`, or `top_k` values return a 400 error on every request, regardless of whether thinking is used. On these models, the `top_p` default is `0.99`, so a `top_p` of `1` returns a 400 error, and so does a request that includes both `temperature` and `top_p`, even at their defaults. See [Remove sampling parameters](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#remove-sampling-parameters). Starting with [API version `2026-10-21`](https://platform.claude.com/docs/en/api/migration-2026-10-21#sampling-parameters), a request that includes `temperature`, `top_p`, or `top_k` at any value returns a 400 error on every model. On older models in API versions before `2026-10-21`, the restriction applies only while thinking is on: `temperature` and `top_k` are incompatible with thinking, and `top_p` is allowed at values between 0.95 and 1. + +### Response prefill and forced tool use + +Claude 4.6 and later models and Claude Mythos Preview reject a prefilled final assistant turn with a 400 error, whether or not thinking is on (see [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported)). On earlier models, you can’t prefill the assistant response while thinking is on. Forced tool use (`tool_choice: {"type": "any"}` or `{"type": "tool", ...}`) is incompatible with manual extended thinking but works with adaptive thinking. The exceptions are Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1, which reject forced tool use on every request with a 400 error. On those models, use `tool_choice: {"type": "auto"}` with [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) or [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) instead. Where forced tool use is accepted, the response starts with the tool call and has no `thinking` block. To let the model think before it calls a tool, use `tool_choice: {"type": "auto"}` and say in the prompt when to use the tool. See [Thinking with tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). + +### Output limits + +Each model accepts `max_tokens` up to the ceiling listed here. On the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing#extended-output-beta), the `output-300k-2026-03-24` [beta header](https://platform.claude.com/docs/en/api/beta-headers) raises that ceiling for the models with a batches ceiling listed. + +| Model | Max output tokens | Batches beta ceiling | +| :-------------------- | :---------------- | :------------------- | +| Claude Fable 5.1 | 128K | — | +| Claude Mythos 5.1 | 128K | — | +| Claude Fable 5 | 128K | — | +| Claude Mythos 5 | 128K | — | +| Claude Mythos Preview | 128K | Not available | +| Claude Opus 5.5 | 128K | 300K | +| Claude Opus 5 | 128K | 300K | +| Claude Opus 4.8 | 128K | 300K | +| Claude Opus 4.7 | 128K | 300K | +| Claude Opus 4.6 | 128K | 300K | +| Claude Opus 4.5 | 64K | Not available | +| Claude Sonnet 5.5 | 128K | 300K | +| Claude Sonnet 5 | 128K | 300K | +| Claude Sonnet 4.6 | 128K | 300K | +| Claude Sonnet 4.5 | 64K | Not available | +| Claude Haiku 5.5 | 128K | 300K | +| Claude Haiku 4.5 | 64K | Not available | + +To read a model’s limits programmatically, see [Using the Models API](https://platform.claude.com/docs/en/models/overview#using-the-models-api). + +### Long requests + +The SDK requires streaming when `max_tokens` is greater than 21,333, to avoid HTTP timeouts on long-running requests. This is a client-side validation, not an API restriction. If you don’t need to process events incrementally, use `.stream()` (java: `.createStreaming()`; csharp: `.CreateStreaming()`; go: `.NewStreaming()`; php: `->createStream()`) with `.get_final_message()` (typescript: `.finalMessage()`; ruby: `.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`) to get the complete `Message` object without assembling it from individual events yourself. See [Get the final message without handling events](https://platform.claude.com/docs/en/build-with-claude/streaming#get-the-final-message-without-handling-events). Expect longer response times when thinking is active, because generating thinking blocks adds processing time. For workloads that push thinking above roughly 32k tokens per request, use [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) to avoid networking issues: such requests can run long enough to hit system timeouts and open connection limits. + +## Next steps + + + + Steer how often and how deeply Claude thinks with effort levels, system prompt guidance, and per-message steering, and understand thinking’s cost and pricing. + + + + Walk through a complete two-turn tool-use round trip that preserves thinking blocks correctly, and see how interleaved thinking changes the flow. + + + + Find out whether your Messages API integration edits conversation history, and replace each edit with the API feature that keeps earlier thinking blocks valid. + + + + Diagnose and fix the most common thinking failures: configuration 400 errors, empty or missing thinking blocks, `max_tokens` stops, and cache misses. + + + + Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency. + + + +## Availability + +Thinking is available on every model and eligible for zero data retention and HIPAA readiness. + +### API support + +#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) + +* Availability: On by default +* Usage: `thinking: {"type": "disabled"}` turns it off on models that accept that value. Where it is off by default, set `thinking` to turn it on. + +| Status | Cloud platforms | +| --------- | ----------------------- | +| Available | All supported platforms | + +#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) + +* Availability: Always on +* Usage: Managed Agents sets the thinking configuration; the agent definition has no `thinking` field. + +| Status | Cloud platforms | +| --------- | ----------------------- | +| Available | All supported platforms | + +### Data handling + +[Data handling overview](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility) + +| Item | Zero data retention | HIPAA | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| Status | Eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Eligible | + +Applicable endpoints: + +* `/v1/messages` with `thinking` + + diff --git a/tests/fixtures/official-model-registry/sources/claude-effort.md b/tests/fixtures/official-model-registry/sources/claude-effort.md new file mode 100644 index 00000000..777c1c63 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/claude-effort.md @@ -0,0 +1,743 @@ +--- +title: Effort +url: https://platform.claude.com/docs/en/build-with-claude/effort +description: Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency. +featureMetadata: + status: stable + zdr: + eligibility: eligible + note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). + supportedModels: + - claude-fable-5-1 + - claude-mythos-5-1 + - claude-fable-5 + - claude-mythos-5 + - claude-mythos-preview + - claude-opus-5-5 + - claude-opus-5 + - claude-sonnet-5-5 + - claude-sonnet-5 + - claude-haiku-5-5 + - claude-opus-4-8 + - claude-opus-4-7 + - claude-opus-4-6 + - claude-sonnet-4-6 + - claude-opus-4-5-20251101 + supportedPlatforms: + Claude API: stable + Claude Platform on AWS: stable + Claude Models on Google Cloud (Anthropic managed): stable + Amazon Bedrock: stable + Amazon Bedrock (InvokeModel): stable + Claude Models on Google Cloud (Google managed): stable + Microsoft Foundry: stable +--- + +**API support**: Usage differs by product. + +* **Messages API**: Set `output_config.effort` on the request. With no value, the model’s default level applies. +* **Managed Agents**: Set `effort` on the agent’s model object, or in a session’s model override. With no value, Managed Agents fills in the model’s default. + +The effort parameter lets you control how many tokens Claude spends when responding to requests. You can trade off between response thoroughness and token efficiency with a single model. The top-level effort parameter is available on all supported models with no beta header required. [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) is in beta. + + + To learn how effort interacts with thinking and which control to reach for, see [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort). Where adaptive thinking is available, effort is the recommended way to control thinking depth. + + +## Set the effort level + +Set `output_config.effort` on the request. The following example runs one request at `medium` effort. + + + ```bash cURL + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-opus-5-5", + "max_tokens": 4096, + "messages": [{ + "role": "user", + "content": "Analyze the trade-offs between microservices and monolithic architectures" + }], + "output_config": { + "effort": "medium" + } + }' + ``` + + ```bash CLI + ant messages create \ + --model claude-opus-5-5 \ + --max-tokens 4096 \ + --output-config '{effort: medium}' \ + --message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}' + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.messages.create( + model="claude-opus-5-5", + max_tokens=4096, + messages=[ + { + "role": "user", + "content": "Analyze the trade-offs between microservices and monolithic architectures", + } + ], + output_config={"effort": "medium"}, + ) + + for block in response.content: + if block.type == "text": + print(block.text) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.messages.create({ + model: "claude-opus-5-5", + max_tokens: 4096, + messages: [ + { + role: "user", + content: "Analyze the trade-offs between microservices and monolithic architectures" + } + ], + output_config: { + effort: "medium" + } + }); + + const textBlock = response.content.find((block) => block.type === "text"); + console.log(textBlock?.text); + ``` + + ```csharp C# + AnthropicClient client = new(); + + var parameters = new MessageCreateParams + { + Model = Model.ClaudeOpus5_5, + MaxTokens = 4096, + Messages = [ + new UserMessageParam + { + Content = "Analyze the trade-offs between microservices and monolithic architectures" + } + ], + OutputConfig = new OutputConfig + { + Effort = Effort.Medium + } + }; + + var message = await client.Messages.Create(parameters); + Console.WriteLine(message); + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus5_5, + MaxTokens: 4096, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")), + }, + OutputConfig: anthropic.OutputConfigParam{ + Effort: anthropic.OutputConfigEffortMedium, + }, + }) + if err != nil { + log.Fatal(err) + } + for _, block := range response.Content { + if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { + fmt.Println(textBlock.Text) + } + } + ``` + + ```java Java + import com.anthropic.models.messages.OutputConfig; + + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_5_5) + .maxTokens(4096L) + .addUserMessage("Analyze the trade-offs between microservices and monolithic architectures") + .outputConfig(OutputConfig.builder() + .effort(OutputConfig.Effort.MEDIUM) + .build()) + .build(); + + Message response = client.messages().create(params); + response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> IO.println(textBlock.text())); + } + ``` + + ```php PHP + $client = new Client(); + + $message = $client->messages->create( + maxTokens: 4096, + messages: [ + ['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures'] + ], + model: 'claude-opus-5-5', + outputConfig: ['effort' => 'medium'], + ); + + foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text, PHP_EOL; + } + } + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + message = client.messages.create( + model: Anthropic::Model::CLAUDE_OPUS_5_5, + max_tokens: 4096, + messages: [ + { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" } + ], + output_config: { + effort: "medium" + } + ) + + message.content.each do |block| + puts block.text if block.type == :text + end + ``` + + +## How effort works + +Most Claude models default to high effort, spending as many tokens as needed for excellent results; Claude Opus 5.5 and Claude Haiku 5.5 default to medium. You can raise the effort level to `max` for the absolute highest capability, or lower it to be more conservative with token usage, optimizing for speed and cost while accepting some reduction in capability. + + + Setting `effort` to the model’s default (`"medium"` on Claude Opus 5.5 and Claude Haiku 5.5, `"high"` on other models) produces exactly the same behavior as omitting the `effort` parameter entirely. + + +The effort parameter affects **all tokens** in the response, including: + +* Text responses and explanations +* Tool calls and function arguments +* Thinking (when active) + +Because effort applies to every output token, it works with or without thinking. Lower effort also means fewer and terser tool calls. + +### Effort levels + +| Level | Description | Typical use case | +| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `max` | Absolute maximum capability with no constraints on token spending. Available on Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, and Claude Haiku 5.5. | Tasks requiring the deepest possible reasoning and most thorough analysis | +| `xhigh` | Extended capability for long-horizon work. Available on Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, and Claude Haiku 5.5. | Long-running agentic and coding tasks (over 30 minutes) with token budgets in the millions | +| `high` | Spends as many tokens as the task needs for excellent results. The default on every model that supports effort except Claude Opus 5.5 and Claude Haiku 5.5. | Complex reasoning, difficult coding problems, agentic tasks | +| `medium` | Balanced approach with moderate token savings. The default on Claude Opus 5.5 and Claude Haiku 5.5. | Agentic tasks that require a balance of speed, cost, and performance | +| `low` | Most efficient. Significant token savings with some capability reduction. | Simpler tasks that need the best speed and lowest costs, such as subagents | + +Not every model that supports `max` supports `xhigh`. + + + Effort is a behavioral signal, not a strict token budget. At lower effort levels, Claude still thinks on sufficiently difficult problems, but thinks less than it would at higher effort levels for the same problem. + + +The per-model recommendations that follow override this table where they differ. + +## Recommended effort levels + +**[Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview) & [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview)** — *For demanding reasoning and long-horizon agentic work* + +Claude Fable 5.1 supports all five effort levels. **Start with `high`, the default.** Step up to `xhigh` or `max` for the most capability-sensitive agentic and coding work, and step down to `medium` or `low` for routine or latency-sensitive work once your evals show quality holds. At `high` and above, set a large `max_tokens`. It’s a hard limit on total output (thinking plus response text). + +Claude Fable 5.1 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. + +See also: [Prompting Claude Fable 5.1](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#consider-all-effort-levels) + +**[Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview)** — *For long-running agentic coding and knowledge work* + +Claude Opus 5.5 supports all five effort levels, and `medium` is the default (Claude Opus 5 and earlier Opus models default to `high`, so a request that omits `effort` runs one level lower than it did on Claude Opus 5). Adaptive thinking is always on and can’t be turned off, so effort is the primary control for how much the model reasons and what a request costs. Run an effort sweep on your own evals rather than carrying settings over from an earlier model, and set a large `max_tokens` at the higher levels: it’s a hard limit on total output (thinking plus response text). Requests that set `thinking: {"type": "disabled"}` return a 400 error at every effort level. Claude Opus 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. + +See also: [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) + +**[Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)** — *The best combination of speed and intelligence* + +Claude Sonnet 5.5 supports all five effort levels, and `high` is the default on the Claude API. Its levels are recalibrated, so a level doesn’t produce the same amount of thinking as the same level on Claude Sonnet 5. Run a fresh effort sweep on your evals rather than carrying over the setting you used on Claude Sonnet 5. Start with `high` unless your workload is agentic or latency-sensitive. For agentic coding and multistep tool use, start with `medium` for well-specified tasks and move to `high` for harder or longer ones. For chat and other latency-sensitive work, start with `medium` or `low`. Use `xhigh` or `max` only where your evals show a quality gain. Set `max_tokens` with room for thinking and the reply. Thinking counts toward `max_tokens` even when the thinking content isn’t returned. For agentic coding, set `max_tokens` to 128,000, the model’s maximum, and [stream](https://platform.claude.com/docs/en/build-with-claude/streaming) the response. + +To turn off up-front thinking, send `thinking: {"type": "between_tools"}` instead of `"disabled"`. It’s the lowest thinking setting on Claude Sonnet 5.5, and it works at `low`, `medium`, and `high` effort. At `xhigh` or `max`, a request with it returns a 400 error, so use adaptive thinking at those levels: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. See [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking). + +Claude Sonnet 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. With `between_tools`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking. + +See also: [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort) + +**[Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview)** — *For high-volume, latency-sensitive tasks such as classification, extraction, and routing* + +Claude Haiku 5.5 supports all five effort levels, and `medium` is the default. Effort is the main control for how much the model thinks, and with it quality, latency, and cost. **Start with `medium`** for most work, including agentic coding. Use `low`, the cheapest and fastest level, for chat, short tool tasks, and simple, high-volume requests. In long agent prompts, the model is more likely to skip a search, stop early, or skip a check at `low`. Use `high` for knowledge work, longer agent tasks, and strict instruction following. Use `xhigh` or `max` only where your evals show a quality gain, and compare them with Claude Sonnet 5.5 on performance, cost, and speed. Thinking is on by default and counts toward `max_tokens`, so leave room for it. + +To get less thinking, lower the effort level. You can also send `thinking: {"type": "disabled"}` at `high` effort or below. At `xhigh` or `max`, it returns a 400 error, so use adaptive thinking there: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. + +Where your platform supports it, Claude Haiku 5.5 also lets you [change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. With `thinking: {"type": "disabled"}`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking. + +See also: [Prompting Claude Haiku 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) + +**[Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview) & [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview)** + +Effort is the primary control for trading off intelligence, latency, and cost on Claude Fable 5. **Start with `high`, the default, for most tasks**, use `xhigh` for the most capability-sensitive workloads, and step down to `medium` or `low` for routine work. Lower effort settings on Claude Fable 5 still perform well and often exceed `xhigh` performance on prior models. At `high` and `xhigh`, set a large `max_tokens`. It’s a hard limit on total output (thinking plus response text). See [Cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#cost-control). + +Reduce effort if a task completes but takes longer than necessary, or if you want a faster, more interactive working style. + +See also: [Prompting Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5) + +**[Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview)** + +Claude Opus 5 supports all five effort levels. **Start with `high`, the default**, and adjust based on your evals: step up to `xhigh` for demanding coding and agentic work, or to `max` when a task justifies unconstrained token spending. Use `low` and `medium` liberally as your primary control for token cost and response time wherever your evals show quality holds. If you carried effort settings over from an earlier model, run a fresh effort sweep on your evals rather than reusing them. + +Effort controls thinking volume, not visible response length: on Claude Opus 5, changing effort does not reliably shorten responses, so [prompt for length](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity) instead. + +The API default is `high`. Set `effort` explicitly to use a different level. The value you pass overrides the default. + +On Claude Opus 5, thinking cannot be disabled at `xhigh` or `max` effort: requests that set `thinking: {"type": "disabled"}` at those levels return a 400 error. See [Effort with thinking](https://platform.claude.com/docs/en/build-with-claude/effort#effort-with-thinking). + +When running Claude Opus 5 at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default. + +Claude Opus 5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. Per-message effort isn’t available for Claude Opus 5 on Amazon Bedrock. + +See also: [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5) + +**[Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview)** + +The guidance for Claude Opus 4.7 also applies to Claude Opus 4.8. **Start with `xhigh` for coding and agentic use cases**, use `high` for most other intelligence-sensitive workloads, and step down to `medium` or `low` only when you’ve measured that the lower level holds quality on your evals. + +The API default is `high`. Set `effort` explicitly to use a different level. The value you pass overrides the default. + +When running Claude Opus 4.8 at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default. + +See also: [Prompting Claude Opus 4.8](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8) + +**[Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview)** + +**Start with `xhigh` for coding and agentic use cases**, and use `high` as the minimum for most intelligence-sensitive workloads. Step down to `medium` for cost-sensitive workloads, or up to `max` only when your evals show measurable headroom at `xhigh`. + +The API default is `high`. To use `xhigh`, set `effort` explicitly. The value you pass overrides the default. + +* **Low effort:** Efficient, but best for short, scoped tasks. Pair `low` with explicit checklists if your task has multiple sections. +* **Medium effort:** The setting for the average workflow where you want good results while reducing costs. +* **High effort:** Advanced use cases that still need a balance of intelligence and token consumption. This is often the best balance of quality and token efficiency. +* **Xhigh effort:** The recommended starting point for coding and agentic work, and for exploratory tasks such as repeated tool calling, detailed web search, and knowledge-base search. Expect meaningfully higher token usage than `high`. +* **Max effort:** Reserve for frontier problems. On most workloads `max` adds significant cost for relatively small quality gains, and on some structured-output or less intelligence-sensitive tasks it can lead to overthinking. + +Claude Opus 4.7 also respects effort levels more strictly than Claude Opus 4.6, especially at `low` and `medium`. At lower effort levels, the model scopes its work to what was asked rather than doing more than requested. If you observe shallow reasoning on complex problems with Claude Opus 4.7, raise effort rather than prompting around it. If you must keep effort low for latency, add targeted guidance such as “This task involves multistep reasoning. Think carefully before responding.” + +When running Claude Opus 4.7 at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default. + +See also: [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) + +**[Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview)** + +Claude Sonnet 5 defaults to `high` effort on the Claude API and Claude Code. + +* **High effort (default):** Suitable for complex reasoning, coding, and agentic tasks where quality matters more than speed or cost. +* **Xhigh effort:** For the hardest coding and agentic tasks. +* **Medium effort:** Cost-saving step-down from the default. Comparable to Claude Sonnet 4.6 at high effort. +* **Low effort:** For high-volume or latency-sensitive workloads. Suitable for chat and non-coding use cases where faster turnaround is prioritized. +* **Max effort:** For tasks requiring the absolute highest capability with no constraints on token spending. + +See also: [Prompting Claude Sonnet 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5#calibrating-effort-and-thinking-depth) + +**[Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview)** + +Sonnet 4.6 defaults to `high` effort. Explicitly set effort when using Sonnet 4.6 to avoid unexpected latency: + +* **Medium effort (recommended default):** Best balance of speed, cost, and performance for most applications. Suitable for agentic coding, tool-heavy workflows, and code generation. +* **Low effort:** For high-volume or latency-sensitive workloads. Suitable for chat and non-coding use cases where faster turnaround is prioritized. +* **High effort:** For complex reasoning and tasks where quality matters more than speed or cost. +* **Max effort:** For tasks requiring the absolute highest capability with no constraints on token spending. + +See also: [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) + +## Effort with tool use + +When using tools, the effort parameter affects both the explanations around tool calls and the tool calls themselves. Lower effort levels tend to: + +* Combine multiple operations into fewer tool calls +* Make fewer tool calls +* Proceed directly to action without preamble +* Use terse confirmation messages after completion + +Higher effort levels might: + +* Make more tool calls +* Explain the plan before taking action +* Provide detailed summaries of changes +* Include more comprehensive code comments + +## Effort with thinking + +The `thinking` parameter controls whether Claude thinks in [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking) before answering; the `effort` parameter controls how much work Claude puts into the whole response, which in adaptive mode includes how often and how deeply it thinks. Don’t pass `adaptive` as an `effort` value: `adaptive` is a thinking mode, not an effort level. + +At higher effort levels, Claude thinks more readily and at greater length. In a tool-use loop, follow-up requests that only process tool results can still skip thinking at any level. At lower levels, Claude can skip thinking entirely for simpler problems. See [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort) for full guidance on how the two controls work together. + +On Claude Opus 4.5, the only extended-thinking-only model that supports effort, it works alongside [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking): set the effort level for your task, then set the thinking token budget based on how much reasoning depth the task needs. + +For per-model thinking availability, see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models). Effort works with or without thinking. See [How effort works](https://platform.claude.com/docs/en/build-with-claude/effort#how-effort-works). + +## Change effort mid-conversation + +You can run later turns of a conversation at a different effort level in two ways. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5, use a per-message effort change, which keeps the prompt cache. On other models, set a new top-level value on the next request, which starts the cache over. + +### Per-message effort (beta) + +Per-message effort is in beta. On the Claude API and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), it’s available on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. On [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) and [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), it’s available on Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. On [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), it’s available on Claude Fable 5.1, Claude Mythos 5.1, and Claude Opus 5.5. It requires the [beta header](https://platform.claude.com/docs/en/api/beta-headers) `mid-conversation-output-config-2026-07-01`. With the Amazon Bedrock [InvokeModel API](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), it’s available on Claude Fable 5.1 and Claude Opus 5.5, and you send that value in the `anthropic_beta` array of the request body instead. + +Without the beta value, a per-message `output_config` returns a 400 error: `messages.N.output_config: Extra inputs are not permitted`, where `N` is the index of the `system` message in `messages`. With the beta value, models without per-message effort, including Claude Fable 5, return a 400 error: `output_config.effort requires a model that supports per-turn effort; this model does not`. On Amazon Bedrock, those models and Claude Opus 5 return the `Extra inputs are not permitted` error instead. On Claude Sonnet 5.5 with `thinking: {"type": "between_tools"}` and on Claude Haiku 5.5 with `thinking: {"type": "disabled"}`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking. + +Add a `role: "system"` message with empty `content` and the new level in `output_config.effort`. Placed directly after a `user` turn with new input, it sets the level for Claude’s reply to that turn. Placed anywhere else, such as between an `assistant` turn and the next `user` turn as in the following example, it takes effect from the next `user` turn with new input. A `user` turn that holds only `tool_result` blocks doesn’t count as new input, so a change placed after one in a tool-use loop waits for the next `user` turn with new input. The new level then holds until a later message changes it. Everything before that message is unchanged, so the cached prefix still matches. + +The following example starts at `high`, then drops to `low` for a routine follow-up: + + + ```bash cURL + # Effort-only system message: the new level takes effect from the next user turn. + curl https://api.anthropic.com/v1/messages \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2026-10-21" \ + -H "anthropic-beta: mid-conversation-output-config-2026-07-01" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-fable-5-1", + "max_tokens": 4096, + "output_config": {"effort": "high"}, + "messages": [ + {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."}, + {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."}, + {"role": "system", "content": [], "output_config": {"effort": "low"}}, + {"role": "user", "content": "Summarize the plan in one sentence."} + ] + }' + ``` + + ```bash CLI + ant beta:messages create \ + --beta mid-conversation-output-config-2026-07-01 <<'YAML' + model: claude-fable-5-1 + max_tokens: 4096 + output_config: + effort: high + messages: + - role: user + content: Plan a migration from SQLite to PostgreSQL in three short steps. + - role: assistant + content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." + # Effort-only system message: the new level takes effect from the next user turn. + - role: system + content: [] + output_config: + effort: low + - role: user + content: Summarize the plan in one sentence. + YAML + ``` + + ```python Python + client = anthropic.Anthropic() + + response = client.beta.messages.create( + model="claude-fable-5-1", + max_tokens=4096, + output_config={"effort": "high"}, + messages=[ + { + "role": "user", + "content": "Plan a migration from SQLite to PostgreSQL in three short steps.", + }, + { + "role": "assistant", + "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.", + }, + # Effort-only system message: the new level takes effect from the next user turn. + {"role": "system", "content": [], "output_config": {"effort": "low"}}, + {"role": "user", "content": "Summarize the plan in one sentence."}, + ], + betas=["mid-conversation-output-config-2026-07-01"], + ) + + for block in response.content: + if block.type == "text": + print(block.text) + ``` + + ```typescript TypeScript + const client = new Anthropic(); + + const response = await client.beta.messages.create({ + model: "claude-fable-5-1", + max_tokens: 4096, + output_config: { effort: "high" }, + messages: [ + { + role: "user", + content: "Plan a migration from SQLite to PostgreSQL in three short steps." + }, + { + role: "assistant", + content: + "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." + }, + // Effort-only system message: the new level takes effect from the next user turn. + { role: "system", content: [], output_config: { effort: "low" } }, + { role: "user", content: "Summarize the plan in one sentence." } + ], + betas: ["mid-conversation-output-config-2026-07-01"] + }); + + for (const block of response.content) { + if (block.type === "text") { + console.log(block.text); + } + } + ``` + + ```csharp C# + using Anthropic.Models.Beta; + using Anthropic.Models.Beta.Messages; + using Model = Anthropic.Models.Messages.Model; + + AnthropicClient client = new(); + + var response = await client.Beta.Messages.Create(new MessageCreateParams + { + Model = Model.ClaudeFable5_1, + MaxTokens = 4096, + OutputConfig = new() { Effort = Effort.High }, + Messages = + [ + new BetaUserMessageParam { Content = "Plan a migration from SQLite to PostgreSQL in three short steps." }, + new BetaAssistantMessageParam { Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." }, + // Effort-only system message: the new level takes effect from the next user turn. + new BetaSystemMessageParam + { + Content = new([]), + OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low }, + }, + new BetaUserMessageParam { Content = "Summarize the plan in one sentence." }, + ], + Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01], + }); + + foreach (var block in response.Content) + { + if (block.TryPickText(out var textBlock)) + { + Console.WriteLine(textBlock.Text); + } + } + ``` + + ```go Go + client := anthropic.NewClient() + + response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeFable5_1, + MaxTokens: 4096, + OutputConfig: anthropic.BetaOutputConfigParam{ + Effort: anthropic.BetaOutputConfigEffortHigh, + }, + Messages: []anthropic.BetaMessageParam{ + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")), + {OfAssistant: &anthropic.BetaAssistantMessageParam{ + Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")}, + }}, + // Effort-only system message: the new level takes effect from the next user turn. + anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{ + Effort: anthropic.BetaSystemMessageOutputConfigEffortLow, + }), + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")), + }, + Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01}, + }) + if err != nil { + log.Fatal(err) + } + + for _, block := range response.Content { + if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok { + fmt.Println(textBlock.Text) + } + } + ``` + + ```java Java + import com.anthropic.models.beta.AnthropicBeta; + import com.anthropic.models.beta.messages.BetaMessage; + import com.anthropic.models.beta.messages.BetaOutputConfig; + import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig; + import com.anthropic.models.beta.messages.BetaSystemMessageParam; + import com.anthropic.models.beta.messages.MessageCreateParams; + import com.anthropic.models.messages.Model; + + void main() { + AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + + MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_FABLE_5_1) + .maxTokens(4096L) + .addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01) + .outputConfig(BetaOutputConfig.builder() + .effort(BetaOutputConfig.Effort.HIGH) + .build()) + .addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.") + .addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.") + // Effort-only system message: the new level takes effect from the next user turn. + .addMessage(BetaSystemMessageParam.builder() + .contentOfBlocks(List.of()) + .outputConfig(BetaSystemMessageOutputConfig.builder() + .effort(BetaSystemMessageOutputConfig.Effort.LOW) + .build()) + .build()) + .addUserMessage("Summarize the plan in one sentence.") + .build(); + + BetaMessage response = client.beta().messages().create(params); + response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> IO.println(textBlock.text())); + } + ``` + + ```php PHP + use Anthropic\Beta\AnthropicBeta; + use Anthropic\Beta\Messages\BetaMessageParam; + use Anthropic\Beta\Messages\BetaOutputConfig; + use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig; + use Anthropic\Client; + + $client = new Client(); + + $response = $client->beta->messages->create( + model: 'claude-fable-5-1', + maxTokens: 4096, + outputConfig: BetaOutputConfig::with(effort: 'high'), + messages: [ + BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'), + BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'), + // Effort-only system message: the new level takes effect from the next user turn. + BetaMessageParam::with( + role: 'system', + content: [], + outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'), + ), + BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'), + ], + betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01], + ); + + foreach ($response->content as $block) { + if ($block->type === 'text') { + echo $block->text, PHP_EOL; + } + } + ``` + + ```ruby Ruby + client = Anthropic::Client.new + + response = client.beta.messages.create( + model: Anthropic::Model::CLAUDE_FABLE_5_1, + max_tokens: 4096, + output_config: {effort: :high}, + messages: [ + {role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps."}, + {role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."}, + # Effort-only system message: the new level takes effect from the next user turn. + {role: "system", content: [], output_config: {effort: :low}}, + {role: "user", content: "Summarize the plan in one sentence."} + ], + betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01] + ) + + response.content.each do |block| + puts block.text if block.type == :text + end + ``` + + +An effort-only system message carries no text, so the [placement rules for mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations) don’t apply. It can appear anywhere in `messages`, including as the first entry or between an `assistant` turn and the next `user` turn. Values are the level names (`low`, `medium`, `high`, `xhigh`, and `max`). + +Prefer this form over changing the top-level value between requests. A top-level change restarts the cache and, on Claude Fable 5.1, also steers the model less reliably: its earlier replies were written at the previous level, and it tends to stay consistent with them. + +### Top-level effort on the next request + +The top-level `output_config.effort` applies to the whole request. To run a later part of a conversation at a different level, set the new value on the next request. Because top-level effort shapes the rendered prompt, changing it between requests doesn’t preserve cached prefixes from earlier turns. If you rely on [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) across a long session and your model doesn’t support per-message effort, pick an effort level at the start and keep it constant. + +## Best practices + +1. **Set effort explicitly:** The API defaults to `high` (`medium` on Claude Opus 5.5 and Claude Haiku 5.5), but the right starting point depends on your model and workload. +2. **Use low for speed-sensitive or simple tasks:** When latency matters or tasks are straightforward, low effort can significantly reduce response times and costs. +3. **Test your use case:** The impact of effort levels varies by task type. Evaluate performance on your specific use cases before deploying. +4. **Consider dynamic effort:** Adjust effort based on task complexity. Simple queries might warrant low effort, whereas agentic coding and complex reasoning benefit from high effort. See the next item before varying it within one conversation. +5. **Hold top-level effort constant within cached conversations:** Changing the top-level effort value between requests invalidates [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), so vary it across workloads rather than within a conversation that relies on cache hits. On models that support it, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) instead, which preserves the cache. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). + +## Next steps + + + + Give Claude an advisory token budget for the full agentic loop to help the model self-regulate on long agentic tasks. + + + + Understand adaptive thinking, where Claude determines when and how much to think, and steer it with effort and prompting. + + + + Understand how thinking works, when Claude thinks by default, and how thinking interacts with effort. + + + +## Availability + +Effort is available on select models and eligible for zero data retention and HIPAA readiness. + +### API support + +#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) + +* Availability: Always on +* Usage: Set `output_config.effort` on the request. With no value, the model’s default level applies. + +| Status | Cloud platforms | Models | +| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Available | All supported platforms | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/en/models/opus-4-5/overview) | + +#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) + +* Availability: Always on +* Usage: Set `effort` on the agent’s model object, or in a session’s model override. With no value, Managed Agents fills in the model’s default. + +| Status | Cloud platforms | Models | +| --------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/en/models/opus-4-5/overview) | + +### Data handling + +[Data handling overview](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility) + +| Item | Zero data retention | HIPAA | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| Status | Eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Eligible | + +Applicable endpoints: + +* `/v1/messages` with `effort` diff --git a/tests/fixtures/official-model-registry/sources/claude-models-overview.md b/tests/fixtures/official-model-registry/sources/claude-models-overview.md new file mode 100644 index 00000000..406f57ea --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/claude-models-overview.md @@ -0,0 +1,127 @@ +--- +title: Models overview +url: https://platform.claude.com/docs/en/models/overview +description: Claude is a family of state-of-the-art large language models developed by Anthropic. This guide introduces the available models and compares their performance. +--- + +# Models overview + +Claude is a family of state-of-the-art large language models developed by Anthropic. Compare the current lineup, find the model ID for every platform, and open each model's page for its full specs and resources. + + + Choosing a model + + + + Pricing + + + + Migration guide + + +## Compare models + +If you’re unsure which model to use, start with [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) for most workloads. Use [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview) for demanding reasoning and long-horizon agentic work, or when your evals on Claude Opus 5.5 at higher effort still fall short. All current models support text and image input, text output, multilingual capabilities, vision, and tool use. Each model’s page lists the platforms it’s available on. + +| Feature | Claude Fable 5.1 | Claude Opus 5.5 | Claude Sonnet 5.5 | Claude Haiku 5.5 | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| Description | For demanding reasoning and long-horizon agentic work | For long-running agentic coding and knowledge work | The best combination of speed and intelligence | For high-volume, latency-sensitive tasks such as classification, extraction, and routing | +| Model page | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview) | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) | [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) | [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview) | +| Comparative latency | Slower | Moderate | Fast | Fastest | +| [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) | $10 / input MTok, $50 / output MTok | $4 / input MTok, $20 / output MTok | $2 / input MTok, $10 / output MTok | From $0.10 / input MTok, From $0.50 / output MTok | +| Claude API ID | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | +| [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) | Adaptive (always on) | Adaptive (always on) | Adaptive | Adaptive | +| [Default effort](https://platform.claude.com/docs/en/build-with-claude/effort) | `high` | `medium` | `high` | `medium` | +| [Context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) | 1M tokens | 1M tokens | 1M tokens | 1M tokens | +| Max output | 128K tokens | 128K tokens | 128K tokens | 128K tokens | +| Reliable knowledge cutoff | Jun 2026 | Jun 2026 | Jun 2026 | Jun 2026 | +| Training data cutoff | Jun 2026 | Jun 2026 | Jun 2026 | Jun 2026 | +| [Retirement](https://platform.claude.com/docs/en/about-claude/model-deprecations) | Not sooner than September 1, 2027 | Not sooner than September 22, 2027 | Not sooner than September 28, 2027 | Not sooner than October 7, 2027 | +| Claude API alias | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | +| [Amazon Bedrock ID](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | `anthropic.claude-fable-5-1` | `anthropic.claude-opus-5-5` | `anthropic.claude-sonnet-5-5` | `anthropic.claude-haiku-5-5` | +| [Claude Models on Google Cloud (Google managed) ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | +| [Microsoft Foundry ID](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | +| [Claude Platform on AWS ID](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | +| [Claude Models on Google Cloud (Anthropic managed) ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) | `claude-fable-5-1` | `claude-opus-5-5` | `claude-sonnet-5-5` | `claude-haiku-5-5` | + +* **Comparative latency:** Relative to the current lineup. Actual latency depends on prompt length, output length, and thinking effort. +* **Pricing:** Base price per million tokens. Batch API requests are 50% off; prompt cache reads cost 10% of the base input price (2.5% on Claude Fable 5.1 and Claude Mythos 5.1, 5% on Claude Opus 5.5 and Claude Sonnet 5.5). See Pricing for cache writes, long-context, and per-platform pricing. +* **Claude API ID:** Every Claude model ID is a pinned snapshot, including the dateless IDs used from the 4.6 generation on. +* **Thinking:** Adaptive thinking lets the model decide how much to think, steered by effort. Extended thinking is the manual thinking.type “enabled” + budget\_tokens mode on earlier models; it is deprecated on Claude Opus 4.6 and Claude Sonnet 4.6 and not accepted on later models. +* **Default effort:** The effort parameter’s default on the Claude API. Set effort explicitly to use a different level. +* **Context window:** 1M tokens is roughly 555k words or 2.5M Unicode characters on the current tokenizer (introduced with Claude Opus 4.7); models before it fit about 750k words in 1M tokens. 200k tokens is roughly 150k words. +* **Max output:** Synchronous Messages API limit. On the Message Batches API, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6 support up to 300k output tokens with the output-300k-2026-03-24 beta header. +* **Reliable knowledge cutoff:** The date through which the model’s knowledge is most extensive and reliable. Training data cutoff (under Additional details) is the broader range of data used. See Anthropic’s Transparency Hub for details. +* **Retirement:** Anthropic’s commitment for the platforms that Anthropic operates. Partner-operated platforms set their own dates. +* **Claude API alias:** For models before the 4.6 generation, the alias is a convenience pointer that resolves to the dated ID. Dateless IDs are their own pinned snapshot; the alias row repeats them. +* **Amazon Bedrock ID:** The ID on Bedrock’s Messages-API endpoint (Claude Opus 4.7 and later, plus Claude Haiku 4.5); a model offered only through Bedrock’s InvokeModel integration shows that ID instead. Bedrock offers global endpoints (dynamic routing) and regional endpoints (guaranteed data routing) for Claude Sonnet 4.5 and later, and sets its own lifecycle dates. +* **Claude Models on Google Cloud (Google managed) ID:** Claude Models on Google Cloud (Google managed) offers global, multi-region, and regional endpoints, and sets its own lifecycle dates. +* **Microsoft Foundry ID:** Foundry deployments default to the Claude API model ID (the alias, where one exists); the deployment name is what you send. Foundry follows the Claude API lifecycle schedule. +* **Claude Platform on AWS ID:** Claude Platform on AWS uses the Claude API model IDs (the dateless form where the Claude API has an alias), not Bedrock-style IDs, and follows Anthropic’s first-party model lifecycle. + +See [Model IDs and versioning](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions) and [Pricing](https://platform.claude.com/docs/en/about-claude/pricing). + +Legacy models (still available): [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/en/models/opus-4-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview), [Claude Haiku 4.5](https://platform.claude.com/docs/en/models/haiku-4-5/overview). + +Once you’ve picked a model, [learn how to make your first API call](https://platform.claude.com/docs/en/get-started). To understand how model IDs, aliases, and snapshots work, see [Model IDs and versioning](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions); for the reliable-knowledge and training-data cutoffs behind each model, see Anthropic’s [Transparency Hub](https://www.anthropic.com/transparency). + +## Using the Models API + +You can query model capabilities and token limits programmatically with the [Models API](https://platform.claude.com/docs/en/api/models/list). The response includes [`max_input_tokens`](https://platform.claude.com/docs/en/api/models#model_info.max_input_tokens), [`max_tokens`](https://platform.claude.com/docs/en/api/models#model_info.max_tokens), and a [`capabilities`](https://platform.claude.com/docs/en/api/models#model_info.capabilities) object for every available model. + +Each model in the response also has a [`line`](https://platform.claude.com/docs/en/api/models#model_info.line) field, which names the model line it belongs to. Claude Opus 4.5 and Claude Opus 4.6 both report `opus`. Use `line` to group models, for example, in a model picker. `line` is `null` when a model belongs to no line. Read `line` instead of inferring it from the model’s `id`. Anthropic might add more lines, so don’t treat the set of values as fixed. + +Each model’s `capabilities` object includes [`thinking.types.disabled`](https://platform.claude.com/docs/en/api/models#thinking_types.disabled), which reports whether the model accepts `thinking: {type: "disabled"}`, the setting that [turns thinking off](https://platform.claude.com/docs/en/build-with-claude/thinking#turning-thinking-off). `supported` is `false` when the model rejects `"disabled"` with a 400 error, and `true` on a model that doesn’t support thinking. Even when `supported` is `true`, the API can still reject a `"disabled"` request for another reason. One such reason is an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level that the model doesn’t allow with thinking off. + +Each model’s `capabilities` object also includes [`thinking.types.between_tools`](https://platform.claude.com/docs/en/api/models#thinking_types.between_tools), which reports whether the model accepts `thinking: {type: "between_tools"}`, the setting that [turns off up-front thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#turning-thinking-off). `supported` is `false` when the model rejects `"between_tools"` with a 400 error. Even when `supported` is `true`, the API can still reject a `"between_tools"` request for another reason, such as an [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level that the model doesn’t allow with `"between_tools"`. For Claude Sonnet 5.5, for example, the Models API reports `thinking.types.between_tools.supported` as `true` and `thinking.types.disabled.supported` as `false`. + +Each model’s `capabilities` object also includes [`server_tools`](https://platform.claude.com/docs/en/api/models#model_capabilities.server_tools), which reports whether the model accepts the [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) and [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) tools. It doesn’t cover other server tools, such as web fetch. `server_tools.web_search.supported` and `server_tools.code_execution.supported` are `true` when the model accepts at least one version of that tool, not necessarily every version. `server_tools.supported` is `true` when the model accepts at least one of the two tools. Even when a tool is supported, your organization’s settings can still cause a request that uses it to fail. For example, an administrator can [disable web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool#how-to-use-web-search). + +The top-level [`code_execution`](https://platform.claude.com/docs/en/api/models#model_capabilities.code_execution) capability is a different check. It reports whether code that Claude runs in the code execution tool can call the request’s other tools, as in [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling). For Claude Haiku 4.5, for example, the Models API reports `server_tools.code_execution.supported` as `true` and `code_execution.supported` as `false`. + +The API reference lists the List Models endpoint’s parameters and full response. + +(See the `models/list` method in [the API reference](https://platform.claude.com/docs/en/api/models/list).) + +## Prompt and output performance + +Current Claude models excel in: + +* **Performance:** Top-tier results in reasoning, coding, multilingual tasks, long-context handling, honesty, and image processing. See [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) for general and model-specific prompting guidance. +* **Engaging responses:** Claude models are ideal for applications that require rich, human-like interactions. If you prefer more concise responses, adjust your prompts to guide the model toward the output length you want. Refer to the [prompt engineering guides](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering) for details. +* **Output quality:** When migrating from a previous model generation, you might notice larger improvements in overall performance. If you’re on Claude Opus 5 or earlier, see the [Claude Opus 5.5 migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide). + +## Get started with Claude + +Whether you’re a developer looking to integrate Claude into your applications or a user wanting to experience the power of AI firsthand, the following resources can help. + + + + Explore Claude’s capabilities and development flow. + + + + Learn how to make your first API call in minutes. + + + + Establish criteria and pick the right model for your use case. + + + + Complete pricing, including batch discounts and prompt caching rates. + + + + Lifecycle status and retirement commitments for every model. + + + + Craft and test prompts directly in your browser. + + + +Looking to chat with Claude? Visit [claude.ai](https://claude.ai). If you have questions, contact the [support team](https://support.claude.com/) or the [Discord community](https://www.anthropic.com/discord). + + diff --git a/tests/fixtures/official-model-registry/sources/deepseek-cache.body b/tests/fixtures/official-model-registry/sources/deepseek-cache.body new file mode 100644 index 00000000..af3e5874 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-cache.body @@ -0,0 +1,70 @@ + + + + + +Context Caching | DeepSeek API Docs + + + + +
Skip to main content

Context Caching

+

The DeepSeek API Context Caching on Disk Technology is enabled by default for all users, allowing them to benefit without needing to modify their code.

+

Each user request will trigger the construction of a hard disk cache. If subsequent requests have overlapping prefixes with previous requests, the overlapping part will only be fetched from the cache, which counts as a "cache hit."

+

Cache Persistence and Hit Rules​

+

A cache hit requires that the corresponding prefix has already been "persisted" (written to the disk cache). Due to the Sliding Window Attention mechanism, the storage and matching of cached prefixes differs from before. Each cached prefix is an independent, complete unit. A subsequent request can only hit the cache if it fully matches a cache prefix unit.

+

When cache prefixes are persisted:​

+
    +
  1. +

    Persistence at request boundaries: Each request will produce two cache prefix units at the end position of the user input and the end position of the model output. A subsequent request can hit the cache if it fully matches them.

    +
  2. +
  3. +

    Common prefix detection persistence: When the system detects a common prefix across multiple requests, it will persist that common prefix as an independent cache prefix unit. A subsequent request can hit the cache if it fully reuses that cache prefix unit.

    +
  4. +
  5. +

    Persistence at fixed token intervals: For long inputs or long outputs, the system will carve out cache prefix units at fixed token intervals, to avoid long prefixes from being completely uncacheable due to never reaching an end position.

    +
  6. +
+

Example 1: A user's first-round request is A + B, and the second-round request is A + B + C. The second request can fully match the cache prefix unit A + B, hitting the cache for A + B. See Example 1 below.

+

Example 2: A user's first-round request is A + B, and the second-round request is A + C. The second request cannot hit the cache, because A + C does not fully match the first round's cache prefix unit (A + B). However, at this point the system will detect that the two requests share a common prefix A, and persist A as a cache prefix unit. When a third-round request A + D arrives, it can fully match the cache prefix unit A, hitting the cache for A. See Example 2 below.

+
+

Example 1: Multi-round Conversation​

+

First Request

+
messages: [
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the capital of China?"}
]
+

Second Request

+
messages: [
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the capital of China?"},
{"role": "assistant", "content": "The capital of China is Beijing."},
{"role": "user", "content": "What is the capital of the United States?"}
]
+

In this example, the second request can fully reuse the cache prefix unit from the first request, which will count as a "cache hit."

+

Example 2: Long Text Q&A​

+

First Request

+
messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."},
{"role": "user", "content": "<financial report content>\n\nPlease summarize the key information of this financial report."}
]
+

Second Request

+
messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."},
{"role": "user", "content": "<financial report content>\n\nPlease analyze the profitability of this financial report."}
]
+

Third Request

+
messages: [
{"role": "system", "content": "You are an experienced financial report analyst..."},
{"role": "user", "content": "<financial report content>\n\nPlease analyze the ratio of the company's revenue to expenses."}
]
+

In the above example, the first two requests will not hit the cache. After the first two requests are completed, the system will identify the system message + <financial report content> in the user message as a cache prefix unit and persist it. In the third request, since it fully matches the previously persisted cache prefix unit, it can hit the cache.

+
+

Checking Cache Hit Status​

+

In the response from the DeepSeek API, we have added two fields in the usage section to reflect the cache hit status of the request:

+
    +
  1. +

    prompt_cache_hit_tokens: The number of tokens in the input of this request that resulted in a cache hit.

    +
  2. +
  3. +

    prompt_cache_miss_tokens: The number of tokens in the input of this request that did not result in a cache hit.

    +
  4. +
+

Hard Disk Cache and Output Randomness​

+

The hard disk cache only matches the prefix part of the user's input. The output is still generated through computation and inference, and it is influenced by parameters such as temperature, introducing randomness.

+

Additional Notes​

+
    +
  1. +

    The cache system works on a "best-effort" basis and does not guarantee a 100% cache hit rate.

    +
  2. +
  3. +

    Cache construction takes seconds. Once the cache is no longer in use, it will be automatically cleared, usually within a few hours to a few days.

    +
  4. +
+ + \ No newline at end of file diff --git a/tests/fixtures/official-model-registry/sources/deepseek-create.body b/tests/fixtures/official-model-registry/sources/deepseek-create.body new file mode 100644 index 00000000..d1b26b97 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-create.body @@ -0,0 +1,53 @@ + + + + + +Chat Completions API | DeepSeek API Docs + + + + +
Skip to main content

Chat Completions API

+
POST 

/chat/completions

+

Creates a model response for the given chat conversation.

+

Request​

+

Body

required

    messages

    object[]

    required

    Minimum items: 1

    A list of messages comprising the conversation so far.

  • Array [

  • oneOf

    content stringrequired

    The contents of the system message.

    role stringrequired

    Possible values: system

    The role of the messages author, in this case system.

    name string

    An optional name for the participant. Provides the model information to differentiate between participants of the same role.

  • ]

  • model stringrequired

    Possible values: deepseek-flash, deepseek-v4-pro

    ID of the model to use. Use deepseek-flash or deepseek-v4-pro.

    thinking

    object

    nullable

    Controls the switch between thinking and non-thinking mode. When thinking is omitted or null, the mode follows reasoning_effort; if reasoning_effort is also omitted, thinking is enabled. When this object is provided, type is required and takes precedence over reasoning_effort for selecting the mode.

    type stringrequired

    Possible values: enabled, disabled

    If set to enabled, then use thinking mode. If set to disabled, then use non-thinking model.

    reasoning_effort string

    Possible values: none, low, high, max

    Controls the thinking mode toggle and the thinking effort. none disables thinking mode; low / high / max enable thinking mode. The default effort is high. For compatibility with existing software, minimal is accepted and mapped to low, and medium / xhigh are accepted and mapped to high.

    max_tokens integernullable

    The maximum number of tokens that can be generated in the chat completion.

    +

    The total length of input tokens and generated tokens is limited by the model's context length.

    +

    The value must be between 1 and 384K (393216). When not set, the default is 8K in non-thinking mode, 64K in thinking mode (128K with reasoning_effort set to max). Please refer to the Models & Pricing page for details.

    response_format

    object

    nullable

    An object specifying the format that the model must output. If omitted or null, plain text is used. When this object is provided, type is required. +Setting to { "type": "json_object" } enables JSON Output, which guarantees the message the model generates is valid JSON.

    Important: When using JSON Output, you must also instruct the model to produce JSON yourself via a system or user message. If the model's output cannot be recognized as JSON, the API replaces the non-JSON content with spaces (U+0020). As a result, the message content may contain only spaces (appearing empty), even when finish_reason is stop. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

    type stringrequired

    Possible values: text, json_object

    Must be one of text or json_object.

    stop string | string[]

    nullable

    Default value: null

    Up to 16 sequences where the API will stop generating further tokens.

    oneOf

    string

    stream booleannullable

    Default value: false

    +

    If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events (SSE) as they become available, with the stream terminated by a data: [DONE] message.

    stream_options

    object

    nullable

    Default value: null

    Options for streaming response. Must be set together with stream: true; if stream is not set to true, the API returns a 400 error.

    include_usage boolean

    If set to true, all chunks in the stream will include a usage field, whose value is null on every chunk except the last one. If omitted or set to false, the usage field is absent from all chunks except the last one.

    +

    Either way, the last chunk before the data: [DONE] message carries the token usage statistics for the entire request in its usage field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose choices array always contains exactly one element that carries no new content and a non-null finish_reason.

    temperature numbernullable

    Possible values: >= 0 and <= 2

    Default value: 1

    +

    What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

    +

    We generally recommend altering this or top_p but not both. Has no effect in thinking mode.

    top_p numbernullable

    Possible values: > 0 and <= 1

    An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

    +

    The value must be greater than 0 and at most 1. We generally recommend altering this or temperature but not both. The effective value depends on the model and mode:

    +
      +
    • deepseek-flash: In thinking mode, the default is 1.0 and values below 0.95 are treated as 0.95. In non-thinking mode, it is fixed at 1.0 and the value you pass is ignored.
    • +
    • deepseek-v4-pro: In thinking mode, it is fixed at 0.95 when tool calling is enabled, or 1.0 otherwise; the value you pass is ignored. Setting tool_choice to none disables tool calling even when tools is provided. In non-thinking mode, the value you pass is used, with a default of 1.0.
    • +

    tools

    object[]

    nullable

    A list of tools the model may call. Currently, only functions are supported as a tool. +Use this to provide a list of functions the model may generate JSON inputs for. Tool names must be unique.

  • Array [

  • type stringrequired

    Possible values: function

    The type of the tool. Currently, only function is supported.

    function

    object

    required

    description string

    A description of what the function does, used by the model to choose when and how to call the function.

    name stringrequired

    The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 128.

    parameters

    object

    The parameters the functions accepts, described as a JSON Schema object. See the Tool Calls Guide for examples, and the JSON Schema reference for documentation about the format.

    Omitting parameters defines a function with an empty parameter list.

    property name* anynullable
    strict boolean

    Default value: false

    +

    If set to true, the API will use strict-mode for the tool calls to ensure the output always complies with the function's JSON schema. This is a Beta feature, for more details please refer to Tool Calls Guide

  • ]

  • tool_choice string | object

    nullable

    Controls which (if any) tool is called by the model.

    none means the model will not call any tool and instead generates a message.

    auto means the model can pick between generating a message or calling one or more tools.

    required means the model must call one or more tools.

    Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.

    none is the default when no tools are present. auto is the default if tools are present.

    required and named tool choices are not supported in thinking mode; the API returns a 400 error. Disable thinking mode first to use them.

    oneOf

    string

    Possible values: none, auto, required

    logprobs booleannullable

    Default value: false

    +

    Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.

    top_logprobs integernullable

    Possible values: >= 0 and <= 20

    Default value: null

    +

    An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.

    user_id nullable

    A custom user_id. We recommend using only ASCII letters, digits, underscores (_), and hyphens (-). The UTF-8 encoded value must not exceed 512 bytes. Do not include user privacy information in the user_id.

    +
      +
    • user_id can be used to distinguish user identities on your side to help us with content safety review.
    • +
    • user_id can be used for KVCache isolation for privacy management.
    • +
    • user_id can be used for scheduling isolation of users on your business side.
    • +
    • For more details on the user_id parameter, please refer to Rate Limit & Isolation
    • +
    frequency_penalty nullabledeprecated

    This parameter is no longer supported. It will not take effect if you pass it to the API.

    presence_penalty nullabledeprecated

    This parameter is no longer supported. It will not take effect if you pass it to the API.

+

Responses​

OK, returns a chat completion object

Schema

    id stringrequired

    A unique identifier for the chat completion.

    choices

    object[]

    required

    A list of chat completion choices.

  • Array [

  • finish_reason stringrequired

    Possible values: stop, length, content_filter, tool_calls, insufficient_system_resource, aborted

    The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, +length if the maximum number of tokens specified in the request was reached, +content_filter if content was omitted due to a flag from our content filters, +tool_calls if the model called a tool, +insufficient_system_resource if the request is interrupted due to insufficient resource of the inference system, +or aborted if the generation was interrupted.

    index integerrequired

    The index of the choice in the list of choices.

    message

    object

    required

    A chat completion message generated by the model.

    content stringnullablerequired

    The contents of the message.

    reasoning_content stringnullable

    For thinking mode only. The reasoning contents of the assistant message, before the final answer.

    tool_calls

    object[]

    The tool calls generated by the model.

  • Array [

  • id stringrequired

    The ID of the tool call.

    type stringrequired

    Possible values: function

    The type of the tool. Currently, only function is supported.

    function

    object

    required

    The function that the model called.

    name stringrequired

    The name of the function to call.

    arguments stringrequired

    The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

  • ]

  • role stringrequired

    Possible values: assistant

    The role of the author of this message.

    logprobs

    object

    nullable

    required

    Log probability information for the choice.

    content

    object[]

    nullable

    required

    A list of message content tokens with log probability information.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

    top_logprobs

    object[]

    required

    List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

  • ]

  • ]

  • reasoning_content

    object[]

    nullable

    A list of message content tokens with log probability information.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

    top_logprobs

    object[]

    required

    List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.

  • Array [

  • token stringrequired

    The token.

    logprob numberrequired

    The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

    bytes integer[]nullablerequired

    A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

  • ]

  • ]

  • ]

  • created integerrequired

    The Unix timestamp (in seconds) of when the chat completion was created.

    model stringrequired

    The model used for the chat completion.

    system_fingerprint stringrequired

    This fingerprint represents the backend configuration that the model runs with.

    object stringrequired

    Possible values: chat.completion

    The object type, which is always chat.completion.

    usage

    object

    Usage statistics for the completion request.

    completion_tokens integerrequired

    Number of tokens in the generated completion.

    prompt_tokens integerrequired

    Number of tokens in the prompt. It equals prompt_cache_hit_tokens + prompt_cache_miss_tokens.

    prompt_tokens_details

    object

    required

    Breakdown of tokens used in the prompt.

    cached_tokens integer

    Number of tokens in the prompt that hit the context cache. Same as prompt_cache_hit_tokens.

    prompt_cache_hit_tokens integerrequired

    Number of tokens in the prompt that hits the context cache.

    prompt_cache_miss_tokens integerrequired

    Number of tokens in the prompt that misses the context cache.

    total_tokens integerrequired

    Total number of tokens used in the request (prompt + completion).

    completion_tokens_details

    object

    Breakdown of tokens used in a completion.

    reasoning_tokens integer

    Tokens generated by the model for reasoning.

Loading...
+ + \ No newline at end of file diff --git a/tests/fixtures/official-model-registry/sources/deepseek-message.md b/tests/fixtures/official-model-registry/sources/deepseek-message.md new file mode 100644 index 00000000..ccf257e9 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-message.md @@ -0,0 +1,2045 @@ +# Messages API + +Creates a model response in the Anthropic Messages API format. + +Send the conversation history in `messages` on each request. Use `https://api.deepseek.com/anthropic` as the Anthropic SDK's `base_url`; the SDK appends `/v1/messages`. Direct HTTP requests can also use the compatible path `/anthropic/messages`. + +Authenticate with either `x-api-key` or `Authorization: Bearer`. If both are supplied, `Authorization` takes precedence. See the [Anthropic API Guide](https://api-docs.deepseek.com/guides/anthropic_api.md) for model mappings, tool-result replay, and compatibility details. + +Compatibility fields `container`, `mcp_servers`, `service_tier`, and `top_k` are ignored. + +## Endpoint + +```http +POST /anthropic/v1/messages +``` + +operationId: `createMessage` + +### Servers + +- `https://api.deepseek.com` + +## Authentication + +### Alternative 1 + +**anthropicApiKey** + +`x-api-key` (header) + +```yaml +type: apiKey +in: header +name: x-api-key +``` + +### Alternative 2 + +**bearerAuth** + +`Authorization: Bearer ` + +```yaml +type: http +scheme: bearer +``` + +## Parameters + +**`anthropic-version`** (header) — optional + +The Anthropic SDK sends this header automatically; the service currently ignores it. + +- `type`: `string` + +**Example** + +```json +"2023-06-01" +``` + +**`anthropic-beta`** (header) — optional + +Include `files-api-2025-04-14` when referencing an uploaded image with `source.type` of `file`. Otherwise not required for this endpoint. See the [Files API Guide](https://api-docs.deepseek.com/guides/files_api.md#anthropic-compatible-files-api). + +- `type`: `string` + +**Example** + +```json +"files-api-2025-04-14" +``` + +## Request body + +**required** + +### application/json + +- Reference: [CreateMessageRequest](#schema-create-message-request) (`#/components/schemas/CreateMessageRequest`) + +## Responses + +### 200 (No streaming) + +OK, returns a `message` object. Its content may include text, thinking, and tool-use blocks. + +#### application/json + +- Reference: [AnthropicMessage](#schema-anthropic-message) (`#/components/schemas/AnthropicMessage`) + +**Example** + +```json +{ + "id": "e6ef6a63-a078-4f53-a73b-38c8d1d46310", + "type": "message", + "role": "assistant", + "model": "deepseek-flash", + "content": [{"type": "text", "text": "Hello!"}], + "stop_reason": "end_turn", + "stop_sequence": null, + "usage": { + "input_tokens": 12, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0, + "output_tokens": 3, + "service_tier": "standard" + } +} +``` + +### 200 (Streaming) + +OK, returns SSE events in the order `message_start` → content block events → `message_delta` → `message_stop`. A `ping` event or keep-alive comment may appear between events. There is no `data: [DONE]` message. Accumulate tool input JSON fragments until the content block ends before parsing them. See [Streaming](https://api-docs.deepseek.com/guides/anthropic_api.md#streaming). + +A connection that closes before `message_stop` is an incomplete response. Errors after streaming has started may terminate the connection without an Anthropic `error` event. + +#### text/event-stream + +- `type`: `array` + +- **Array items** + + - Reference: [AnthropicMessageStreamEvent](#schema-anthropic-message-stream-event) (`#/components/schemas/AnthropicMessageStreamEvent`) + +**Example** + +``` +event: message_start +data: {"type":"message_start","message":{"id":"e6ef6a63-a078-4f53-a73b-38c8d1d46310","type":"message","role":"assistant","model":"deepseek-flash","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0,"service_tier":"standard"}}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: ping +data: {"type":"ping"} + +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","stop_sequence":null},"usage":{"input_tokens":12,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3,"service_tier":"standard"}} + +event: message_stop +data: {"type":"message_stop"} +``` + +### 400 (Bad request) + +Invalid request, for example an empty `messages` array or unpaired tool results. Request errors use the common DeepSeek `{error: {message, type, param, code}}` structure, without the Anthropic top-level `type: "error"` field. See [Error Codes](https://api-docs.deepseek.com/quick_start/error_codes.md) for other HTTP errors. + +#### application/json + +- Reference: [ErrorResponse](#schema-error-response) (`#/components/schemas/ErrorResponse`) + +**Example** + +```json +{ + "error": { + "message": "messages: at least one message is required", + "type": "invalid_request_error", + "param": null, + "code": "invalid_request_error" + } +} +``` + +## Code samples + +### curl + +```bash +# Set DEEPSEEK_API_KEY to your API key before running this example. +curl --silent --show-error --max-time 60 "https://api.deepseek.com/anthropic/v1/messages" \ + --header "x-api-key: ${DEEPSEEK_API_KEY}" \ + --header "anthropic-version: 2023-06-01" \ + --header "Content-Type: application/json" \ + --data '{ + "model": "deepseek-flash", + "messages": [{"role": "user", "content": "Say hello."}], + "max_tokens": 32, + "thinking": {"type": "disabled"}, + "stream": false +}' +``` + +### Python — Anthropic SDK + +```python +# Install the SDK first: pip install anthropic +# Set DEEPSEEK_API_KEY to your API key before running this example. +import os +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ["DEEPSEEK_API_KEY"], + base_url="https://api.deepseek.com/anthropic", + timeout=60.0, +) + +message = client.messages.create( + model="deepseek-flash", + messages=[{"role": "user", "content": "Say hello."}], + max_tokens=32, + thinking={"type": "disabled"}, + stream=False, +) +print(message.model_dump_json(indent=2)) +``` + +## Referenced schemas + +### schema-create-message-request + +**CreateMessageRequest** — `#/components/schemas/CreateMessageRequest` + +Creates the next assistant message using the Anthropic Messages format. Compatibility fields `container`, `mcp_servers`, `service_tier`, and `top_k` are ignored. See the [Anthropic API Guide](https://api-docs.deepseek.com/guides/anthropic_api.md) for compatibility details. + +- `type`: `object` + +- `required`: `["model","messages"]` + +- **Properties** + + - **`model`** (required) + + ID of the model to use. Use `deepseek-flash` or `deepseek-v4-pro`. Claude model-name aliases are also accepted: `claude-opus*` maps to `deepseek-v4-pro`, and other `claude*` names map to `deepseek-flash`. See the [Anthropic API Guide](https://api-docs.deepseek.com/guides/anthropic_api.md). + + - `type`: `string` + + **Example** + + ```json + "deepseek-flash" + ``` + + - **`messages`** (required) + + The conversation history. At least one message is required. This API is stateless: include the messages needed for the current turn in every request. Use the top-level `system` field for the system prompt. When continuing after a tool call, pass back the complete assistant content, including thinking and tool-use blocks, followed by the matching tool results. The service may restore omitted thinking content from tool-call IDs; if recovery is required but fails, the request returns `400`. Preserve the complete content for reliable replay. + + - `type`: `array` + + - `minItems`: `1` + + - **Array items** + + - Reference: [AnthropicMessageParam](#schema-anthropic-message-param) (`#/components/schemas/AnthropicMessageParam`) + + - **`system`** (optional) + + - Reference: [AnthropicSystemContent](#schema-anthropic-system-content) (`#/components/schemas/AnthropicSystemContent`) + + - **`max_tokens`** (optional) + + The requested output token limit, including thinking tokens. This field is optional at the HTTP API level; the Anthropic SDK requires it. The default and effective limit depend on the model, thinking mode, and reasoning effort. Values above the model limit are capped, and the input plus output must fit within the context window. For certain Claude Code or OpenCode main-agent requests in thinking mode, compatibility handling may raise the effective limit above the requested value, within model and context limits. See [Models & Pricing](https://api-docs.deepseek.com/quick_start/pricing.md). + + - `type`: `integer` + + - `minimum`: `1` + + - `nullable`: `true` + + **Example** + + ```json + 4096 + ``` + + - **`stream`** (optional) + + If `true`, return named server-sent events (SSE), ending with `message_stop`. There is no `data: [DONE]` message. Otherwise, return one complete message object. + + - `type`: `boolean` + + - `nullable`: `true` + + - `default`: `false` + + - **`thinking`** (optional) + + - Reference: [AnthropicThinkingConfig](#schema-anthropic-thinking-config) (`#/components/schemas/AnthropicThinkingConfig`) + + - **`output_config`** (optional) + + - Reference: [AnthropicOutputConfig](#schema-anthropic-output-config) (`#/components/schemas/AnthropicOutputConfig`) + + - **`tools`** (optional) + + Tools available to the model. Supports client-defined tools and the web search server tool. Tool names must be unique. An empty list is treated as no tools. `cache_control` is ignored. + + - `type`: `array` + + - `nullable`: `true` + + - **Array items** + + - Reference: [AnthropicTool](#schema-anthropic-tool) (`#/components/schemas/AnthropicTool`) + + - **`tool_choice`** (optional) + + - Reference: [AnthropicToolChoice](#schema-anthropic-tool-choice) (`#/components/schemas/AnthropicToolChoice`) + + - **`stop_sequences`** (optional) + + Up to 16 non-empty strings that stop generation. If a string is matched, `stop_reason` is `stop_sequence` and `stop_sequence` contains the matched string. + + - `type`: `array` + + - `nullable`: `true` + + - `maxItems`: `16` + + - **Array items** + + - `type`: `string` + + - `minLength`: `1` + + - **`temperature`** (optional) + + Sampling temperature, between 0 and 2. Higher values produce more varied output. In thinking mode the value is fixed at 1, and the supplied value has no effect. We generally recommend changing either this or `top_p`, rather than both. + + - `type`: `number` + + - `nullable`: `true` + + - `minimum`: `0` + + - `maximum`: `2` + + - `default`: `1` + + - **`top_p`** (optional) + + Nucleus sampling probability, greater than 0 and at most 1. For `deepseek-flash`, thinking mode defaults to 1 and clamps values below 0.95 to 0.95; non-thinking mode always uses 1. For `deepseek-v4-pro`, thinking mode uses 0.95 when tools are enabled and 1 otherwise, ignoring the supplied value; non-thinking mode uses the supplied value, defaulting to 1. Setting `tool_choice` to `{"type":"none"}` disables tool calling. + + - `type`: `number` + + - `nullable`: `true` + + - `minimum`: `0` + + - `exclusiveMinimum`: `true` + + - `maximum`: `1` + + **Example** + + ```json + 1 + ``` + + - **`metadata`** (optional) + + - Reference: [AnthropicMetadata](#schema-anthropic-metadata) (`#/components/schemas/AnthropicMetadata`) + +### schema-anthropic-message + +**AnthropicMessage** — `#/components/schemas/AnthropicMessage` + +- title: `Message` + +- `type`: `object` + +- `required`: `["id","type","role","model","content","stop_reason","stop_sequence","usage"]` + +- **Properties** + + - **`id`** (required) + + Unique identifier for this message. + + - `type`: `string` + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["message"]` + + - **`role`** (required) + + - `type`: `string` + + - `enum`: `["assistant"]` + + - **`model`** (required) + + The model identifier supplied in the request. When using a Claude-compatible model name, the response retains that name. + + - `type`: `string` + + - **`content`** (required) + + Generated content blocks. Preserve the full content when adding this assistant turn to the next request. + + - `type`: `array` + + - **Array items** + + - Reference: [AnthropicMessageOutputBlock](#schema-anthropic-message-output-block) (`#/components/schemas/AnthropicMessageOutputBlock`) + + - **`stop_reason`** (required) + + Why generation stopped: natural completion, output limit, a stop sequence, a client tool call, or content filtering. Null in message\_start. + + - `type`: `string` + + - `nullable`: `true` + + - `enum`: `["end_turn","max_tokens","stop_sequence","tool_use","refusal",null]` + + - **`stop_sequence`** (required) + + The matched stop sequence, or null when no stop sequence was matched. + + - `type`: `string` + + - `nullable`: `true` + + - **`usage`** (required) + + - Reference: [AnthropicMessageUsage](#schema-anthropic-message-usage) (`#/components/schemas/AnthropicMessageUsage`) + +### schema-anthropic-message-stream-event + +**AnthropicMessageStreamEvent** — `#/components/schemas/AnthropicMessageStreamEvent` + +- title: `Message stream event` + +Normal message events have an event name matching the JSON type. A normal stream ends with message\_stop. Ping events and keep-alive comments may appear between events; no data: \[DONE] is emitted. A timeout may instead return an unnamed data event containing an error object before closing the connection. An interrupted stream without message\_stop is incomplete. + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicMessageStartEvent](#schema-anthropic-message-start-event) (`#/components/schemas/AnthropicMessageStartEvent`) + + - oneOf 2 + + - Reference: [AnthropicContentBlockStartEvent](#schema-anthropic-content-block-start-event) (`#/components/schemas/AnthropicContentBlockStartEvent`) + + - oneOf 3 + + - Reference: [AnthropicContentBlockDeltaEvent](#schema-anthropic-content-block-delta-event) (`#/components/schemas/AnthropicContentBlockDeltaEvent`) + + - oneOf 4 + + - Reference: [AnthropicContentBlockStopEvent](#schema-anthropic-content-block-stop-event) (`#/components/schemas/AnthropicContentBlockStopEvent`) + + - oneOf 5 + + - Reference: [AnthropicMessageDeltaEvent](#schema-anthropic-message-delta-event) (`#/components/schemas/AnthropicMessageDeltaEvent`) + + - oneOf 6 + + - Reference: [AnthropicMessageStopEvent](#schema-anthropic-message-stop-event) (`#/components/schemas/AnthropicMessageStopEvent`) + + - oneOf 7 + + - Reference: [AnthropicPingEvent](#schema-anthropic-ping-event) (`#/components/schemas/AnthropicPingEvent`) + +### schema-error-response + +**ErrorResponse** — `#/components/schemas/ErrorResponse` + +- `type`: `object` + +- `required`: `["error"]` + +- **Properties** + + - **`error`** (required) + + - Reference: [Error](#schema-error) (`#/components/schemas/Error`) + +### schema-anthropic-message-param + +**AnthropicMessageParam** — `#/components/schemas/AnthropicMessageParam` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicUserMessage](#schema-anthropic-user-message) (`#/components/schemas/AnthropicUserMessage`) + + - oneOf 2 + + - Reference: [AnthropicAssistantMessage](#schema-anthropic-assistant-message) (`#/components/schemas/AnthropicAssistantMessage`) + +### schema-anthropic-system-content + +**AnthropicSystemContent** — `#/components/schemas/AnthropicSystemContent` + +The system prompt. Supports only a string, an array of text blocks, or `null`. + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextContent](#schema-anthropic-text-content) (`#/components/schemas/AnthropicTextContent`) + + - oneOf 2 + + - Reference: [AnthropicSystemBlocks](#schema-anthropic-system-blocks) (`#/components/schemas/AnthropicSystemBlocks`) + + - oneOf 3 + + - Reference: [AnthropicNullValue](#schema-anthropic-null-value) (`#/components/schemas/AnthropicNullValue`) + +### schema-anthropic-thinking-config + +**AnthropicThinkingConfig** — `#/components/schemas/AnthropicThinkingConfig` + +- title: `Thinking configuration` + +Controls thinking mode. An explicit `thinking.type` takes precedence over `output_config.effort` when selecting the mode. When omitted, `effort` determines the mode. If neither is set, thinking is enabled by default for `deepseek-flash` and `deepseek-v4-pro`. + +- `type`: `object` + +- `required`: `["type"]` + +- `nullable`: `true` + +- **Properties** + + - **`type`** (required) + + `enabled` turns thinking on; `disabled` turns it off. `adaptive` is treated as `enabled`. + + - `type`: `string` + + - `enum`: `["enabled","disabled","adaptive"]` + + - **`budget_tokens`** (optional) + + Ignored. This parameter does not set a thinking-token budget. + + - `type`: `integer` + + - `minimum`: `0` + + - `nullable`: `true` + +### schema-anthropic-output-config + +**AnthropicOutputConfig** — `#/components/schemas/AnthropicOutputConfig` + +- title: `Output configuration` + +Output configuration. Only `effort` is supported; output-format settings such as `format` are ignored. + +- `type`: `object` + +- `nullable`: `true` + +- **Properties** + + - **`effort`** (optional) + + Controls thinking mode and effort. `none` disables thinking unless `thinking.type` explicitly enables it. `low`, `high`, and `max` enable thinking, with `high` as the default effort. Compatibility aliases: `minimal` maps to `low`, `medium` and `xhigh` both map to `high`, and `ultra` maps to `max`. An explicit `thinking.type` determines whether thinking is enabled. + + - `type`: `string` + + - `enum`: `["none","minimal","low","medium","high","xhigh","ultra","max",null]` + + - `nullable`: `true` + +### schema-anthropic-tool + +**AnthropicTool** — `#/components/schemas/AnthropicTool` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicClientTool](#schema-anthropic-client-tool) (`#/components/schemas/AnthropicClientTool`) + + - oneOf 2 + + - Reference: [AnthropicWebSearchTool](#schema-anthropic-web-search-tool) (`#/components/schemas/AnthropicWebSearchTool`) + +### schema-anthropic-tool-choice + +**AnthropicToolChoice** — `#/components/schemas/AnthropicToolChoice` + +Controls tool selection. Defaults to `auto`. `any` is treated as `auto` and does not force a tool call. Selecting a named client tool requires non-thinking mode. `disable_parallel_tool_use` is ignored. + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicToolChoiceAuto](#schema-anthropic-tool-choice-auto) (`#/components/schemas/AnthropicToolChoiceAuto`) + + - oneOf 2 + + - Reference: [AnthropicToolChoiceAny](#schema-anthropic-tool-choice-any) (`#/components/schemas/AnthropicToolChoiceAny`) + + - oneOf 3 + + - Reference: [AnthropicToolChoiceNamed](#schema-anthropic-tool-choice-named) (`#/components/schemas/AnthropicToolChoiceNamed`) + + - oneOf 4 + + - Reference: [AnthropicToolChoiceNone](#schema-anthropic-tool-choice-none) (`#/components/schemas/AnthropicToolChoiceNone`) + + - oneOf 5 + + - Reference: [AnthropicNullValue](#schema-anthropic-null-value) (`#/components/schemas/AnthropicNullValue`) + +### schema-anthropic-metadata + +**AnthropicMetadata** — `#/components/schemas/AnthropicMetadata` + +- title: `Metadata` + +Request metadata. Only `user_id` is supported; other metadata fields are ignored. + +- `type`: `object` + +- `nullable`: `true` + +- **Properties** + + - **`user_id`** (optional) + + A custom end-user identifier. We recommend using only ASCII letters, digits, underscores (`_`), and hyphens (`-`). The UTF-8 encoded value must not exceed 512 bytes. Do not include personal information. See [Rate Limit & Isolation](https://api-docs.deepseek.com/quick_start/rate_limit.md). + + - `type`: `string` + + - `nullable`: `true` + +### schema-anthropic-message-output-block + +**AnthropicMessageOutputBlock** — `#/components/schemas/AnthropicMessageOutputBlock` + +- title: `Output content block` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextBlock](#schema-anthropic-text-block) (`#/components/schemas/AnthropicTextBlock`) + + - oneOf 2 + + - Reference: [AnthropicOutputThinkingBlock](#schema-anthropic-output-thinking-block) (`#/components/schemas/AnthropicOutputThinkingBlock`) + + - oneOf 3 + + - Reference: [AnthropicToolUseBlock](#schema-anthropic-tool-use-block) (`#/components/schemas/AnthropicToolUseBlock`) + + - oneOf 4 + + - Reference: [AnthropicOutputServerToolUseBlock](#schema-anthropic-output-server-tool-use-block) (`#/components/schemas/AnthropicOutputServerToolUseBlock`) + + - oneOf 5 + + - Reference: [AnthropicWebSearchToolResultBlock](#schema-anthropic-web-search-tool-result-block) (`#/components/schemas/AnthropicWebSearchToolResultBlock`) + +### schema-anthropic-message-usage + +**AnthropicMessageUsage** — `#/components/schemas/AnthropicMessageUsage` + +- title: `Message usage` + +- `type`: `object` + +- `required`: `["input_tokens","cache_creation_input_tokens","cache_read_input_tokens","output_tokens","service_tier"]` + +- **Properties** + + - **`input_tokens`** (required) + + Input tokens not served from the context cache. Total input tokens equal input\_tokens + cache\_read\_input\_tokens + cache\_creation\_input\_tokens. + + - `type`: `integer` + + - `minimum`: `0` + + - **`cache_creation_input_tokens`** (required) + + Always 0. Anthropic-style cache creation is not used; context caching is automatic. + + - `type`: `integer` + + - `enum`: `[0]` + + - **`cache_read_input_tokens`** (required) + + Input tokens served from the context cache. + + - `type`: `integer` + + - `minimum`: `0` + + - **`output_tokens`** (required) + + Generated output tokens, including thinking tokens when thinking is enabled. In message\_delta this is the cumulative count, not an increment. + + - `type`: `integer` + + - `minimum`: `0` + + - **`service_tier`** (required) + + - `type`: `string` + + - `enum`: `["standard"]` + + - **`server_tool_use`** (optional) + + - title: `Server tool usage` + + Server-side web search counts, separate from token usage. Present only when at least one web search was attempted; otherwise omitted. Both fields are present when this object is returned. Read the final message's usage for non-streaming responses or the final message\_delta.usage for streaming responses. These counts are cumulative, not deltas. See [Server tool usage](https://api-docs.deepseek.com/guides/anthropic_api.md#server-tool-usage). + + - `type`: `object` + + - `required`: `["web_search_requests","tool_search"]` + + - **Properties** + + - **`web_search_requests`** (required) + + Number of server-side web search attempts, including failed attempts and attempts exceeding `max_uses`. + + - `type`: `integer` + + - `minimum`: `0` + + - **`tool_search`** (required) + + Number of successful server-side web searches that returned nonempty results. Failed attempts and empty results are not counted. This field can be used as a basis for billing. + + - `type`: `integer` + + - `minimum`: `0` + + **Example** + + ```json + { + "web_search_requests": 1, + "tool_search": 1 + } + ``` + +### schema-anthropic-message-start-event + +**AnthropicMessageStartEvent** — `#/components/schemas/AnthropicMessageStartEvent` + +- title: `message_start` + +- `type`: `object` + +- `required`: `["type","message"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["message_start"]` + + - **`message`** (required) + + - Reference: [AnthropicMessage](#schema-anthropic-message) (`#/components/schemas/AnthropicMessage`) + +### schema-anthropic-content-block-start-event + +**AnthropicContentBlockStartEvent** — `#/components/schemas/AnthropicContentBlockStartEvent` + +- title: `content_block_start` + +- `type`: `object` + +- `required`: `["type","index","content_block"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["content_block_start"]` + + - **`index`** (required) + + Zero-based index of the content block. + + - `type`: `integer` + + - `minimum`: `0` + + - **`content_block`** (required) + + - Reference: [AnthropicMessageOutputBlock](#schema-anthropic-message-output-block) (`#/components/schemas/AnthropicMessageOutputBlock`) + +### schema-anthropic-content-block-delta-event + +**AnthropicContentBlockDeltaEvent** — `#/components/schemas/AnthropicContentBlockDeltaEvent` + +- title: `content_block_delta` + +- `type`: `object` + +- `required`: `["type","index","delta"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["content_block_delta"]` + + - **`index`** (required) + + Zero-based index of the content block. + + - `type`: `integer` + + - `minimum`: `0` + + - **`delta`** (required) + + - Reference: [AnthropicContentBlockDelta](#schema-anthropic-content-block-delta) (`#/components/schemas/AnthropicContentBlockDelta`) + +### schema-anthropic-content-block-stop-event + +**AnthropicContentBlockStopEvent** — `#/components/schemas/AnthropicContentBlockStopEvent` + +- title: `content_block_stop` + +- `type`: `object` + +- `required`: `["type","index"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["content_block_stop"]` + + - **`index`** (required) + + Zero-based index of the content block. + + - `type`: `integer` + + - `minimum`: `0` + +### schema-anthropic-message-delta-event + +**AnthropicMessageDeltaEvent** — `#/components/schemas/AnthropicMessageDeltaEvent` + +- title: `message_delta` + +- `type`: `object` + +- `required`: `["type","delta","usage"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["message_delta"]` + + - **`delta`** (required) + + - title: `Stop information` + + - `type`: `object` + + - `required`: `["stop_reason","stop_sequence"]` + + - **Properties** + + - **`stop_reason`** (required) + + The final reason generation stopped. + + - `type`: `string` + + - `nullable`: `false` + + - `enum`: `["end_turn","max_tokens","stop_sequence","tool_use","refusal"]` + + - **`stop_sequence`** (required) + + The matched stop sequence, or null when no stop sequence was matched. + + - `type`: `string` + + - `nullable`: `true` + + - **`usage`** (required) + + - Reference: [AnthropicMessageUsage](#schema-anthropic-message-usage) (`#/components/schemas/AnthropicMessageUsage`) + +### schema-anthropic-message-stop-event + +**AnthropicMessageStopEvent** — `#/components/schemas/AnthropicMessageStopEvent` + +- title: `message_stop` + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["message_stop"]` + +### schema-anthropic-ping-event + +**AnthropicPingEvent** — `#/components/schemas/AnthropicPingEvent` + +- title: `ping` + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["ping"]` + +### schema-error + +**Error** — `#/components/schemas/Error` + +- `type`: `object` + +- `required`: `["type","message","param","code"]` + +- **Properties** + + - **`code`** (required) + + - `type`: `string` + + - `nullable`: `true` + + - **`message`** (required) + + - `type`: `string` + + - `nullable`: `false` + + - **`param`** (required) + + - `type`: `string` + + - `nullable`: `true` + + - **`type`** (required) + + - `type`: `string` + + - `nullable`: `false` + +### schema-anthropic-user-message + +**AnthropicUserMessage** — `#/components/schemas/AnthropicUserMessage` + +- title: `User message` + +- `type`: `object` + +- `required`: `["role","content"]` + +- **Properties** + + - **`role`** (required) + + - `type`: `string` + + - `enum`: `["user"]` + + - **`content`** (required) + + - Reference: [AnthropicUserContent](#schema-anthropic-user-content) (`#/components/schemas/AnthropicUserContent`) + +### schema-anthropic-assistant-message + +**AnthropicAssistantMessage** — `#/components/schemas/AnthropicAssistantMessage` + +- title: `Assistant message` + +A previous assistant message. Preserve its content blocks when passing it back, including thinking, tool use, and web search results. + +- `type`: `object` + +- `required`: `["role","content"]` + +- **Properties** + + - **`role`** (required) + + - `type`: `string` + + - `enum`: `["assistant"]` + + - **`content`** (required) + + - Reference: [AnthropicAssistantContent](#schema-anthropic-assistant-content) (`#/components/schemas/AnthropicAssistantContent`) + +### schema-anthropic-text-content + +**AnthropicTextContent** — `#/components/schemas/AnthropicTextContent` + +- title: `Text content` + +- `type`: `string` + +### schema-anthropic-system-blocks + +**AnthropicSystemBlocks** — `#/components/schemas/AnthropicSystemBlocks` + +- title: `System text blocks` + +- `type`: `array` + +- **Array items** + + - Reference: [AnthropicTextBlock](#schema-anthropic-text-block) (`#/components/schemas/AnthropicTextBlock`) + +### schema-anthropic-null-value + +**AnthropicNullValue** — `#/components/schemas/AnthropicNullValue` + +- title: `Null value` + +- `type`: `string` + +- `nullable`: `true` + +- `enum`: `[null]` + +### schema-anthropic-client-tool + +**AnthropicClientTool** — `#/components/schemas/AnthropicClientTool` + +- title: `Client tool` + +The application executes this tool after receiving a `tool_use` block and returns a `tool_result` block. Omit `type` for client tools. Providing `type` selects server-tool parsing; unsupported values such as `custom` return `422`. `cache_control` is ignored. + +- `type`: `object` + +- `required`: `["name","input_schema"]` + +- **Properties** + + - **`name`** (required) + + A unique tool name containing letters, digits, underscores, or hyphens, up to 128 characters. + + - `type`: `string` + + - `minLength`: `1` + + - `maxLength`: `128` + + - `pattern`: `^[a-zA-Z0-9_-]+$` + + - **`description`** (optional) + + A description of what the tool does and when to use it. + + - `type`: `string` + + - `nullable`: `true` + + - **`input_schema`** (required) + + A valid JSON Schema describing the tool arguments. Its top-level `type` must be `object`. + + - `type`: `object` + + - **additionalProperties** + + - Schema: `true` + + **Example** + + ```json + { + "type": "object", + "properties": { + "city": { + "type": "string" + } + }, + "required": [ + "city" + ] + } + ``` + +- **not** + + - `required`: `["type"]` + +### schema-anthropic-web-search-tool + +**AnthropicWebSearchTool** — `#/components/schemas/AnthropicWebSearchTool` + +- title: `Web search server tool` + +The service executes web searches and returns `server_tool_use` and `web_search_tool_result` blocks in the assistant message. Both type values select the same tool. + +- `type`: `object` + +- `required`: `["type","name"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["web_search_20250305","web_search_20260209"]` + + - **`name`** (required) + + - `type`: `string` + + - `enum`: `["web_search"]` + + - **`max_uses`** (optional) + + Maximum searches allowed in this request. The default and service-side cap are normally 5; for Claude Code search-subagent compatibility requests, both are 1. Larger values are capped at the applicable limit. A search beyond this limit returns a `max_uses_exceeded` result. + + - `type`: `integer` + + - `minimum`: `0` + + - `nullable`: `true` + +### schema-anthropic-tool-choice-auto + +**AnthropicToolChoiceAuto** — `#/components/schemas/AnthropicToolChoiceAuto` + +- title: `Automatic tool choice` + +The model decides whether to call a tool. This is the default. + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["auto"]` + + - **`disable_parallel_tool_use`** (optional) + + Ignored; it does not disable parallel tool calls. + + - `type`: `boolean` + + - `nullable`: `true` + +### schema-anthropic-tool-choice-any + +**AnthropicToolChoiceAny** — `#/components/schemas/AnthropicToolChoiceAny` + +- title: `Any tool (automatic)` + +Treated as `auto`; the model decides whether to call a tool. + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["any"]` + + - **`disable_parallel_tool_use`** (optional) + + Ignored; it does not disable parallel tool calls. + + - `type`: `boolean` + + - `nullable`: `true` + +### schema-anthropic-tool-choice-named + +**AnthropicToolChoiceNamed** — `#/components/schemas/AnthropicToolChoiceNamed` + +- title: `Named tool choice` + +Selects the named tool. For a client tool, this forces a call in non-thinking mode; selecting it in thinking mode returns a `400` error. Set `thinking.type` to `disabled` when forcing a client-tool call. + +- `type`: `object` + +- `required`: `["type","name"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["tool"]` + + - **`name`** (required) + + The name of a tool present in `tools`. + + - `type`: `string` + + - **`disable_parallel_tool_use`** (optional) + + Ignored; it does not disable parallel tool calls. + + - `type`: `boolean` + + - `nullable`: `true` + +### schema-anthropic-tool-choice-none + +**AnthropicToolChoiceNone** — `#/components/schemas/AnthropicToolChoiceNone` + +- title: `Disable tool calls` + +Disables tool calling, even when `tools` is provided. + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["none"]` + +### schema-anthropic-text-block + +**AnthropicTextBlock** — `#/components/schemas/AnthropicTextBlock` + +- title: `Text block` + +Each text block must have `type: "text"`, with its content in the `text` field. On input, additional `cache_control` and `citations` fields are ignored. + +- `type`: `object` + +- `required`: `["type","text"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["text"]` + + - **`text`** (required) + + The text content. + + - `type`: `string` + +### schema-anthropic-output-thinking-block + +**AnthropicOutputThinkingBlock** — `#/components/schemas/AnthropicOutputThinkingBlock` + +- title: `Thinking output` + +- `type`: `object` + +- `required`: `["type","thinking","signature"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["thinking"]` + + - **`thinking`** (required) + + The generated thinking content. Return this block unchanged when continuing a thinking-mode tool conversation. + + - `type`: `string` + + - **`signature`** (required) + + Opaque signature returned with the thinking block; preserve it when replaying the block. + + - `type`: `string` + +### schema-anthropic-tool-use-block + +**AnthropicToolUseBlock** — `#/components/schemas/AnthropicToolUseBlock` + +- title: `Tool-use block` + +Appears in assistant messages. Each tool-use block must have a matching tool-result block in the immediately following user message. + +- `type`: `object` + +- `required`: `["type","id","name","input"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["tool_use"]` + + - **`id`** (required) + + The tool-call ID. Pass this ID back as `tool_result.tool_use_id`. + + - `type`: `string` + + - **`name`** (required) + + The name of the client tool. + + - `type`: `string` + + - **`input`** (required) + + The JSON arguments supplied to the tool, normally an object matching its `input_schema`. + +### schema-anthropic-output-server-tool-use-block + +**AnthropicOutputServerToolUseBlock** — `#/components/schemas/AnthropicOutputServerToolUseBlock` + +- title: `Server tool use output` + +Describes a tool call executed by the service. Request-level search counts are reported separately in `usage.server_tool_use`; the client does not execute this call. + +- `type`: `object` + +- `required`: `["type","id","name","input","caller"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["server_tool_use"]` + + - **`id`** (required) + + Identifier of the server tool call. + + - `type`: `string` + + - **`name`** (required) + + Name of the server tool. + + - `type`: `string` + + - **`input`** (required) + + Arguments supplied to the server tool as a JSON value, normally an object. + + - **`caller`** (required) + + - title: `Caller` + + - `type`: `object` + + - `required`: `["type"]` + + - **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["direct"]` + +### schema-anthropic-web-search-tool-result-block + +**AnthropicWebSearchToolResultBlock** — `#/components/schemas/AnthropicWebSearchToolResultBlock` + +- title: `Web search result block` + +- `type`: `object` + +- `required`: `["type","tool_use_id","content"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["web_search_tool_result"]` + + - **`tool_use_id`** (required) + + The ID of the associated `server_tool_use` block. + + - `type`: `string` + + - **`content`** (required) + + Search results or search-error items. Pass the entire array back unchanged with the assistant message. + + - `type`: `array` + + - **Array items** + + - Reference: [AnthropicWebSearchResultContent](#schema-anthropic-web-search-result-content) (`#/components/schemas/AnthropicWebSearchResultContent`) + +### schema-anthropic-content-block-delta + +**AnthropicContentBlockDelta** — `#/components/schemas/AnthropicContentBlockDelta` + +- title: `Content delta` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextDelta](#schema-anthropic-text-delta) (`#/components/schemas/AnthropicTextDelta`) + + - oneOf 2 + + - Reference: [AnthropicThinkingDelta](#schema-anthropic-thinking-delta) (`#/components/schemas/AnthropicThinkingDelta`) + + - oneOf 3 + + - Reference: [AnthropicSignatureDelta](#schema-anthropic-signature-delta) (`#/components/schemas/AnthropicSignatureDelta`) + + - oneOf 4 + + - Reference: [AnthropicInputJsonDelta](#schema-anthropic-input-json-delta) (`#/components/schemas/AnthropicInputJsonDelta`) + +### schema-anthropic-user-content + +**AnthropicUserContent** — `#/components/schemas/AnthropicUserContent` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextContent](#schema-anthropic-text-content) (`#/components/schemas/AnthropicTextContent`) + + - oneOf 2 + + - Reference: [AnthropicUserBlocks](#schema-anthropic-user-blocks) (`#/components/schemas/AnthropicUserBlocks`) + +### schema-anthropic-assistant-content + +**AnthropicAssistantContent** — `#/components/schemas/AnthropicAssistantContent` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextContent](#schema-anthropic-text-content) (`#/components/schemas/AnthropicTextContent`) + + - oneOf 2 + + - Reference: [AnthropicAssistantBlocks](#schema-anthropic-assistant-blocks) (`#/components/schemas/AnthropicAssistantBlocks`) + +### schema-anthropic-web-search-result-content + +**AnthropicWebSearchResultContent** — `#/components/schemas/AnthropicWebSearchResultContent` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicWebSearchResult](#schema-anthropic-web-search-result) (`#/components/schemas/AnthropicWebSearchResult`) + + - oneOf 2 + + - Reference: [AnthropicWebSearchToolResultError](#schema-anthropic-web-search-tool-result-error) (`#/components/schemas/AnthropicWebSearchToolResultError`) + +### schema-anthropic-text-delta + +**AnthropicTextDelta** — `#/components/schemas/AnthropicTextDelta` + +- title: `Text delta` + +- `type`: `object` + +- `required`: `["type","text"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["text_delta"]` + + - **`text`** (required) + + Append this text to the current text block. + + - `type`: `string` + +### schema-anthropic-thinking-delta + +**AnthropicThinkingDelta** — `#/components/schemas/AnthropicThinkingDelta` + +- title: `Thinking delta` + +- `type`: `object` + +- `required`: `["type","thinking"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["thinking_delta"]` + + - **`thinking`** (required) + + Append this text to the current thinking block. + + - `type`: `string` + +### schema-anthropic-signature-delta + +**AnthropicSignatureDelta** — `#/components/schemas/AnthropicSignatureDelta` + +- title: `Signature delta` + +- `type`: `object` + +- `required`: `["type","signature"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["signature_delta"]` + + - **`signature`** (required) + + Signature for the completed thinking block. + + - `type`: `string` + +### schema-anthropic-input-json-delta + +**AnthropicInputJsonDelta** — `#/components/schemas/AnthropicInputJsonDelta` + +- title: `Tool input delta` + +- `type`: `object` + +- `required`: `["type","partial_json"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["input_json_delta"]` + + - **`partial_json`** (required) + + A fragment of the tool input JSON. Concatenate all fragments for this block, then parse the JSON after content\_block\_stop. + + - `type`: `string` + +### schema-anthropic-user-blocks + +**AnthropicUserBlocks** — `#/components/schemas/AnthropicUserBlocks` + +- title: `User content blocks` + +Place all `tool_result` blocks before text or image blocks when replying to tool calls. + +- `type`: `array` + +- `minItems`: `1` + +- **Array items** + + - Reference: [AnthropicUserContentBlock](#schema-anthropic-user-content-block) (`#/components/schemas/AnthropicUserContentBlock`) + +### schema-anthropic-assistant-blocks + +**AnthropicAssistantBlocks** — `#/components/schemas/AnthropicAssistantBlocks` + +- title: `Assistant content blocks` + +- `type`: `array` + +- `minItems`: `1` + +- **Array items** + + - Reference: [AnthropicAssistantContentBlock](#schema-anthropic-assistant-content-block) (`#/components/schemas/AnthropicAssistantContentBlock`) + +### schema-anthropic-web-search-result + +**AnthropicWebSearchResult** — `#/components/schemas/AnthropicWebSearchResult` + +- title: `Web search result` + +- `type`: `object` + +- `required`: `["type","title","url","encrypted_content"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["web_search_result"]` + + - **`title`** (required) + + The title of the result page. + + - `type`: `string` + + - **`url`** (required) + + The URL of the result page. + + - `type`: `string` + + - `format`: `uri` + + - **`encrypted_content`** (required) + + Opaque result content. Preserve this value unchanged when passing the result back. + + - `type`: `string` + + - **`page_age`** (optional) + + Page-age metadata, when available; may be `null`. + + - `type`: `string` + + - `nullable`: `true` + +### schema-anthropic-web-search-tool-result-error + +**AnthropicWebSearchToolResultError** — `#/components/schemas/AnthropicWebSearchToolResultError` + +- title: `Web search error` + +- `type`: `object` + +- `required`: `["type","error_code"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["web_search_tool_result_error"]` + + - **`error_code`** (required) + + The reason the server-side search failed. + + - `type`: `string` + + - `enum`: `["invalid_tool_input","unavailable","max_uses_exceeded","too_many_requests","query_too_long","request_too_large"]` + +### schema-anthropic-user-content-block + +**AnthropicUserContentBlock** — `#/components/schemas/AnthropicUserContentBlock` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextBlock](#schema-anthropic-text-block) (`#/components/schemas/AnthropicTextBlock`) + + - oneOf 2 + + - Reference: [AnthropicImageBlock](#schema-anthropic-image-block) (`#/components/schemas/AnthropicImageBlock`) + + - oneOf 3 + + - Reference: [AnthropicToolResultBlock](#schema-anthropic-tool-result-block) (`#/components/schemas/AnthropicToolResultBlock`) + +### schema-anthropic-assistant-content-block + +**AnthropicAssistantContentBlock** — `#/components/schemas/AnthropicAssistantContentBlock` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextBlock](#schema-anthropic-text-block) (`#/components/schemas/AnthropicTextBlock`) + + - oneOf 2 + + - Reference: [AnthropicThinkingBlock](#schema-anthropic-thinking-block) (`#/components/schemas/AnthropicThinkingBlock`) + + - oneOf 3 + + - Reference: [AnthropicToolUseBlock](#schema-anthropic-tool-use-block) (`#/components/schemas/AnthropicToolUseBlock`) + + - oneOf 4 + + - Reference: [AnthropicServerToolUseBlock](#schema-anthropic-server-tool-use-block) (`#/components/schemas/AnthropicServerToolUseBlock`) + + - oneOf 5 + + - Reference: [AnthropicWebSearchToolResultBlock](#schema-anthropic-web-search-tool-result-block) (`#/components/schemas/AnthropicWebSearchToolResultBlock`) + +### schema-anthropic-image-block + +**AnthropicImageBlock** — `#/components/schemas/AnthropicImageBlock` + +- title: `Image block` + +Image input is supported by `deepseek-flash` in user messages and tool results. Images in assistant messages are not supported. `deepseek-v4-pro` does not support image input. See the [Vision Guide](https://api-docs.deepseek.com/guides/vision.md) for image limits. + +- `type`: `object` + +- `required`: `["type","source"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["image"]` + + - **`source`** (required) + + - Reference: [AnthropicImageSource](#schema-anthropic-image-source) (`#/components/schemas/AnthropicImageSource`) + +### schema-anthropic-tool-result-block + +**AnthropicToolResultBlock** — `#/components/schemas/AnthropicToolResultBlock` + +- title: `Tool-result block` + +Only valid in user messages. Return one result for every pending tool-use ID, with no duplicates, before any text or image blocks. + +- `type`: `object` + +- `required`: `["type","tool_use_id"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["tool_result"]` + + - **`tool_use_id`** (required) + + The ID of the corresponding `tool_use` block in the immediately preceding assistant message. + + - `type`: `string` + + - **`content`** (optional) + + - Reference: [AnthropicToolResultContent](#schema-anthropic-tool-result-content) (`#/components/schemas/AnthropicToolResultContent`) + + - **`is_error`** (optional) + + Ignored. Include any error details in `content`. + + - `type`: `boolean` + + - `nullable`: `true` + +### schema-anthropic-thinking-block + +**AnthropicThinkingBlock** — `#/components/schemas/AnthropicThinkingBlock` + +- title: `Thinking block` + +- `type`: `object` + +- `required`: `["type","thinking"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["thinking"]` + + - **`thinking`** (required) + + Thinking content returned by the model. Pass it back unchanged when continuing a tool-call turn in thinking mode. + + - `type`: `string` + + - **`signature`** (optional) + + The signature returned with the thinking block. Preserve it when passing back the block; the input signature is not validated. + + - `type`: `string` + + - `nullable`: `true` + +### schema-anthropic-server-tool-use-block + +**AnthropicServerToolUseBlock** — `#/components/schemas/AnthropicServerToolUseBlock` + +- title: `Server-tool-use block` + +Returned when the service runs web search. Its matching `web_search_tool_result` appears in the same assistant message; the client does not run this tool. + +- `type`: `object` + +- `required`: `["type","id","name","input"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["server_tool_use"]` + + - **`id`** (required) + + The server-tool-call ID. + + - `type`: `string` + + - **`name`** (required) + + - `type`: `string` + + - `enum`: `["web_search"]` + + - **`input`** (required) + + The server-tool arguments as a JSON value, normally an object such as `{"query":"..."}`. Preserve them when passing back the assistant message. + + - **`caller`** (optional) + + Identifies a direct server-tool call. + + - `type`: `object` + + - `required`: `["type"]` + + - **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["direct"]` + +### schema-anthropic-image-source + +**AnthropicImageSource** — `#/components/schemas/AnthropicImageSource` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicBase64ImageSource](#schema-anthropic-base-64-image-source) (`#/components/schemas/AnthropicBase64ImageSource`) + + - oneOf 2 + + - Reference: [AnthropicUrlImageSource](#schema-anthropic-url-image-source) (`#/components/schemas/AnthropicUrlImageSource`) + + - oneOf 3 + + - Reference: [AnthropicFileImageSource](#schema-anthropic-file-image-source) (`#/components/schemas/AnthropicFileImageSource`) + +### schema-anthropic-tool-result-content + +**AnthropicToolResultContent** — `#/components/schemas/AnthropicToolResultContent` + +The tool output as a string or a list of text and image blocks. If omitted or `null`, the result is empty. + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextContent](#schema-anthropic-text-content) (`#/components/schemas/AnthropicTextContent`) + + - oneOf 2 + + - Reference: [AnthropicToolResultBlocks](#schema-anthropic-tool-result-blocks) (`#/components/schemas/AnthropicToolResultBlocks`) + + - oneOf 3 + + - Reference: [AnthropicNullValue](#schema-anthropic-null-value) (`#/components/schemas/AnthropicNullValue`) + +### schema-anthropic-base-64-image-source + +**AnthropicBase64ImageSource** — `#/components/schemas/AnthropicBase64ImageSource` + +- title: `Base64 image` + +- `type`: `object` + +- `required`: `["type","media_type","data"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["base64"]` + + - **`media_type`** (required) + + - `type`: `string` + + - `enum`: `["image/jpeg","image/png","image/gif","image/webp"]` + + - **`data`** (required) + + The base64-encoded image bytes, without a data-URL prefix. + + - `type`: `string` + +### schema-anthropic-url-image-source + +**AnthropicUrlImageSource** — `#/components/schemas/AnthropicUrlImageSource` + +- title: `Image URL` + +- `type`: `object` + +- `required`: `["type","url"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["url"]` + + - **`url`** (required) + + An HTTP or HTTPS URL from which the server can download the image. + + - `type`: `string` + + - `format`: `uri` + +### schema-anthropic-file-image-source + +**AnthropicFileImageSource** — `#/components/schemas/AnthropicFileImageSource` + +- title: `Uploaded image file` + +Requires the request header `anthropic-beta: files-api-2025-04-14`. + +- `type`: `object` + +- `required`: `["type","file_id"]` + +- **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["file"]` + + - **`file_id`** (required) + + The ID of an uploaded image file. See the [Files API Guide](https://api-docs.deepseek.com/guides/files_api.md#anthropic-compatible-files-api). + + - `type`: `string` + +### schema-anthropic-tool-result-blocks + +**AnthropicToolResultBlocks** — `#/components/schemas/AnthropicToolResultBlocks` + +- title: `Tool-result content blocks` + +- `type`: `array` + +- **Array items** + + - Reference: [AnthropicToolResultContentBlock](#schema-anthropic-tool-result-content-block) (`#/components/schemas/AnthropicToolResultContentBlock`) + +### schema-anthropic-tool-result-content-block + +**AnthropicToolResultContentBlock** — `#/components/schemas/AnthropicToolResultContentBlock` + +- **oneOf** + + - oneOf 1 + + - Reference: [AnthropicTextBlock](#schema-anthropic-text-block) (`#/components/schemas/AnthropicTextBlock`) + + - oneOf 2 + + - Reference: [AnthropicImageBlock](#schema-anthropic-image-block) (`#/components/schemas/AnthropicImageBlock`) diff --git a/tests/fixtures/official-model-registry/sources/deepseek-model-list.html b/tests/fixtures/official-model-registry/sources/deepseek-model-list.html new file mode 100644 index 00000000..bd185ec6 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-model-list.html @@ -0,0 +1,22 @@ + + + + + +Lists Models | DeepSeek API Docs + + + + +
Skip to main content

Lists Models

+
GET 

/models

+

Lists the currently available models, and provides metadata about each one, such as its display name, context window, output limit, supported input/output modalities, supported effort levels, and per-protocol API capabilities. Check Models & Pricing for our currently supported models.

+

Responses​

OK, returns A list of models

Schema

    object stringrequired

    Possible values: list

    The object type, which is always list.

    data

    object[]

    required

    The list of model objects.

    Describes a DeepSeek model offering that can be used with the API. Besides the identifier fields, each model carries machine-readable metadata about its capabilities and limits; a metadata field may be omitted when the information is not available for that model.

  • Array [

  • id stringrequired

    The model identifier, which can be referenced in the API endpoints.

    object stringrequired

    Possible values: model

    The object type, which is always "model".

    owned_by stringrequired

    The organization that owns the model.

    name string

    The display name of the model, for use in model pickers and model discovery tools.

    context_window integer

    The total token capacity of the context window, counting both input and output tokens.

    max_output_tokens integer

    The maximum number of output tokens the server allows in a single response, i.e. the maximum accepted value of max_tokens.

    input_modalities string[]

    Possible values: text, image

    The input types the model accepts.

    output_modalities string[]

    Possible values: text

    The media types the model can generate.

    effort

    object

    The effort levels available when thinking mode is enabled.

    supported_levels string[]required

    The effort levels the model supports when thinking mode is enabled, in the recommended display order. These are the values accepted by the reasoning_effort parameter; none, which turns thinking mode off, is not included.

    default_level string

    The effort level the server uses when thinking mode is enabled and the request does not specify one. Always one of supported_levels. Only present when the server defines a default for the model.

    api_capabilities

    object

    Model behavior declared per API protocol.

    anthropic_messages

    object

    Capabilities that apply when the model is used through the Anthropic Messages API.

    system_prompt_update stringrequired

    Possible values: leading-only, in-history

    How the model picks up an updated system prompt during a conversation.

    +
      +
    • leading-only: only the system prompt at the start of the conversation takes effect. To change the system prompt, modify that leading system prompt; system messages appearing later in the history are not treated as system prompt updates.
    • +
    • in-history: a system message may be appended to the conversation history. The latest system message in the history provides the complete effective system prompt and replaces all earlier ones.
    • +
  • ]

Loading...
+ + \ No newline at end of file diff --git a/tests/fixtures/official-model-registry/sources/deepseek-models.html b/tests/fixtures/official-model-registry/sources/deepseek-models.html new file mode 100644 index 00000000..b57168ac --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-models.html @@ -0,0 +1,30 @@ + + + + + +Models & Pricing | DeepSeek API Docs + + + + +
Skip to main content

Models & Pricing

+

Model prices are listed in units of per 1M tokens. A token, the smallest unit of text that the model recognizes, can be a word, a number, or even a punctuation mark. We bill model usage based on the total number of input and output tokens by the model.

+
+

Model Details​

+
MODELdeepseek-flash(1)deepseek-v4-pro
BASE URL (OpenAI Format)https://api.deepseek.com
BASE URL (Anthropic Format)https://api.deepseek.com/anthropic
MODEL VERSIONDeepSeek-V4.1-Flash-1017DeepSeek-V4-Pro-0813
THINKING MODESupports both non-thinking and thinking (default) modes
See Thinking Mode for how to switch
CONTEXT LENGTH1M
MAX OUTPUTMAXIMUM: 384K
FEATURESJson Output✓✓
Tool Calls✓✓
Responses API✓✓
Anthropic API✓✓
Chat Prefix Completion(Beta)✓✓
FIM Completion(Beta)Non-thinking mode onlyNon-thinking mode only
Vision✓Not supported
PRICING(2)1M INPUT TOKENS
(CACHE HIT)
OFF-PEAK$0.003$0.022
PEAK$0.006$0.044
1M INPUT TOKENS
(CACHE MISS)
OFF-PEAK$0.15$0.66
PEAK$0.3$1.32
1M OUTPUT TOKENSOFF-PEAK$0.6$1.98
PEAK$1.2$3.96
Concurrency Limit(3)2500500
+

(1) Use deepseek-flash as the model name. The legacy names deepseek-v4-flash and deepseek-v4-flash-vision-exp are still accepted, but the corresponding models have been retired, their requests are served by the DeepSeek-V4.1-Flash-1017 model and billed at the Flash price.

(2) Off-peak rates are half of the peak rates. Peak hours are 01:00 - 04:00 and 06:00 - 10:00 UTC, Monday through Friday, excluding Chinese public holidays. All other hours are off-peak, including weekends and Chinese public holidays in full.

(3) For more details on concurrency limits, please refer to Rate Limit & Isolation.

+
+

Search & Fetch Pricing​

+

Search and Fetch are standalone APIs billed per request.

+
APIUnitPrice
SearchPer 1,000 successful requests$0.75
FetchPer 1,000 successful requests$0.75
+

See the Search & Fetch guide for API usage and complete billing rules.

+
+

Deduction Rules​

+

For model usage, the expense = number of tokens × price. Search and Fetch are charged per successful request at the rates above. +The corresponding fees will be directly deducted from your topped-up balance or granted balance, with a preference for using the granted balance first when both balances are available.

+

Product prices may vary and DeepSeek reserves the right to adjust them. We recommend topping up based on your actual usage and regularly checking this page for the most recent pricing information.

+ + \ No newline at end of file diff --git a/tests/fixtures/official-model-registry/sources/deepseek-response.md b/tests/fixtures/official-model-registry/sources/deepseek-response.md new file mode 100644 index 00000000..da8b66f2 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-response.md @@ -0,0 +1,1030 @@ +# Responses API + +Creates a model response in the OpenAI Responses API format. + +The API is **stateless**: responses and conversations are not stored on the server. For multi-turn conversations, the client needs to send the full conversation history in `input` on each request. Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md) for details, including the full parameter compatibility tables. + +## Endpoint + +```http +POST /responses +``` + +operationId: `createResponse` + +### Servers + +- `https://api.deepseek.com` + +## Authentication + +### Alternative 1 + +**bearerAuth** + +`Authorization: Bearer ` + +```yaml +type: http +scheme: bearer +``` + +## Request body + +**required** + +### application/json + +- Reference: [CreateResponseRequest](#schema-create-response-request) (`#/components/schemas/CreateResponseRequest`) + +## Responses + +### 200 (No streaming) + +OK, returns a `response` object + +#### application/json + +- Reference: [Response](#schema-response) (`#/components/schemas/Response`) + +**Example** + +```json +{ + "id": "387b53c1-7ad2-4259-9298-61b139f5bd20", + "object": "response", + "created_at": 1793084842, + "status": "completed", + "background": false, + "completed_at": 1793084843, + "content_filters": null, + "error": null, + "frequency_penalty": 0.0, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": 32, + "max_tool_calls": null, + "model": "deepseek-flash", + "moderation": null, + "output": [ + { + "type": "message", + "id": "4e706f35-6ea2-468a-bd19-a9c1adc54726", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Hello! 👋 How can I help you today?" + } + ], + "phase": "final_answer", + "role": "assistant" + } + ], + "parallel_tool_calls": true, + "presence_penalty": 0.0, + "previous_response_id": null, + "prompt_cache_key": null, + "prompt_cache_retention": null, + "reasoning": { + "effort": "none", + "summary": null + }, + "safety_identifier": null, + "service_tier": "default", + "store": false, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + }, + "verbosity": null + }, + "tool_choice": "auto", + "tools": [], + "top_logprobs": 0, + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 7, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 11, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18 + }, + "user": null, + "metadata": {} +} +``` + +### 200 (Streaming) + +OK, returns a streamed sequence of semantic server-sent events. Each event has an `event` field for the event type and an incrementing `sequence_number`. The final event is `response.completed` / `response.incomplete` / `response.failed` (there is no `data: [DONE]` message). Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md#streaming) for the full event list. + +#### text/event-stream + +- `type`: `array` + +- **Array items** + + - `type`: `object` + +**Example** + +``` +event: response.created +data: {"type":"response.created","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"in_progress","background":false,"completed_at":null,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":0} + +event: response.in_progress +data: {"type":"response.in_progress","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"in_progress","background":false,"completed_at":null,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":1} + +event: response.output_item.added +data: {"type":"response.output_item.added","item":{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"in_progress","content":[],"phase":"final_answer","role":"assistant"},"output_index":0,"sequence_number":2} + +event: response.content_part.added +data: {"type":"response.content_part.added","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","output_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":""},"sequence_number":3} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":"Hello","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":4} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":"!","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":5} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" 👋","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":6} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" How","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":7} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" can","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":8} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" I","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":9} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" help","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":10} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" you","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":11} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":" today","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":12} + +event: response.output_text.delta +data: {"type":"response.output_text.delta","content_index":0,"delta":"?","item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":13} + +event: response.output_text.done +data: {"type":"response.output_text.done","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","logprobs":[],"output_index":0,"sequence_number":14,"text":"Hello! 👋 How can I help you today?"} + +event: response.content_part.done +data: {"type":"response.content_part.done","content_index":0,"item_id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","output_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"},"sequence_number":15} + +event: response.output_item.done +data: {"type":"response.output_item.done","item":{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"completed","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"}],"phase":"final_answer","role":"assistant"},"output_index":0,"sequence_number":16} + +event: response.completed +data: {"type":"response.completed","response":{"id":"19460ef2-58da-46c5-9510-9e7b04c47e4a","object":"response","created_at":1793084908,"status":"completed","background":false,"completed_at":1793084909,"content_filters":null,"error":null,"frequency_penalty":0.0,"incomplete_details":null,"instructions":null,"max_output_tokens":32,"max_tool_calls":null,"model":"deepseek-flash","moderation":null,"output":[{"type":"message","id":"7b653eb5-6012-4257-ba1a-4e9dce20bd25","status":"completed","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"Hello! 👋 How can I help you today?"}],"phase":"final_answer","role":"assistant"}],"parallel_tool_calls":true,"presence_penalty":0.0,"previous_response_id":null,"prompt_cache_key":null,"prompt_cache_retention":null,"reasoning":{"effort":"none","summary":null},"safety_identifier":null,"service_tier":"default","store":false,"temperature":1.0,"text":{"format":{"type":"text"},"verbosity":null},"tool_choice":"auto","tools":[],"top_logprobs":0,"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":7,"input_tokens_details":{"cached_tokens":0},"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":18},"user":null,"metadata":{}},"sequence_number":17} +``` + +## Code samples + +### curl + +```bash +# Set DEEPSEEK_API_KEY to your API key before running this example. +curl --silent --show-error --max-time 60 "https://api.deepseek.com/responses" \ + --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \ + --header "Content-Type: application/json" \ + --data '{ + "model": "deepseek-flash", + "input": "Say hello.", + "max_output_tokens": 32, + "reasoning": { + "effort": "none" + }, + "stream": false +}' +``` + +### Python — OpenAI SDK + +```python +# Set DEEPSEEK_API_KEY to your API key before running this example. +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ["DEEPSEEK_API_KEY"], + base_url="https://api.deepseek.com", + timeout=60.0, +) + +response = client.responses.create( + model="deepseek-flash", + input="Say hello.", + max_output_tokens=32, + reasoning={"effort": "none"}, + stream=False, +) +print(response.model_dump_json(indent=2)) +``` + +## Referenced schemas + +### schema-create-response-request + +**CreateResponseRequest** — `#/components/schemas/CreateResponseRequest` + +- `type`: `object` + +- `required`: `["model"]` + +- **Properties** + + - **`model`** (required) + + ID of the model to use. Use `deepseek-flash` or `deepseek-v4-pro`. + + - `type`: `string` + + - `enum`: `["deepseek-flash","deepseek-v4-pro"]` + + **Example** + + ```json + "deepseek-flash" + ``` + + - **`input`** (optional) + + The input to the model. Either a plain string (treated as a single `user` message), or a list of input items. + + Supported input item types are `message` / `function_call` / `function_call_output` / `custom_tool_call` / `custom_tool_call_output` / `reasoning` / `web_search_call`; other types are ignored. Message roles can be `user` / `assistant` / `system` / `developer` (`developer` is treated as `user`). With the `deepseek-flash` model, `input_image` content parts are supported in `user` / `developer` message items and in the `output` of `function_call_output` / `custom_tool_call_output` items; images in `system` or `assistant` messages return a `400` error. File inputs are not supported. + + At least one of `input` and `instructions` is required. + + - `nullable`: `true` + + - **oneOf** + + - oneOf 1 + + - title: `Text input` + + - `type`: `string` + + - oneOf 2 + + - title: `Input item list` + + - `type`: `array` + + - **Array items** + + - Reference: [ResponseInputItem](#schema-response-input-item) (`#/components/schemas/ResponseInputItem`) + + - **`instructions`** (optional) + + A system-level instruction, inserted as the first system message of the model's context. + + - `type`: `string` + + - `nullable`: `true` + + - **`reasoning`** (optional) + + Configuration of the thinking mode. + + - `type`: `object` + + - `nullable`: `true` + + - **Properties** + + - **`effort`** (optional) + + Controls the thinking mode toggle and the thinking effort. `none` disables thinking mode; `low` / `high` / `max` enable thinking mode. If not set, the model's default thinking behavior is used (enabled by default). For compatibility with existing software, `minimal` is accepted and mapped to `low`, and `medium` / `xhigh` are accepted and mapped to `high`. + + - `type`: `string` + + - `enum`: `["none","low","high","max"]` + + - **`max_output_tokens`** (optional) + + An upper bound for the number of tokens that can be generated in the response, including both the visible output tokens and the reasoning tokens. + + - `type`: `integer` + + - `nullable`: `true` + + **Example** + + ```json + 4096 + ``` + + - **`stream`** (optional) + + If set to `true`, the response is streamed as semantic server-sent events. The final event is `response.completed` / `response.incomplete` / `response.failed` (there is no `data: [DONE]` message). Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md#streaming) for the full event list. + + - `type`: `boolean` + + - `nullable`: `true` + + - `default`: `false` + + - **`temperature`** (optional) + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Has no effect in thinking mode. + + - `type`: `number` + + - `minimum`: `0` + + - `maximum`: `2` + + - `default`: `1` + + - `nullable`: `true` + + **Example** + + ```json + 1 + ``` + + - **`top_p`** (optional) + + An alternative to sampling with temperature, called nucleus sampling. The effective value depends on the model and mode: + + - `deepseek-flash`: In thinking mode, the default is 1.0 and values below 0.95 are treated as 0.95. In non-thinking mode, it is fixed at 1.0 and the value you pass is ignored. + + - `deepseek-v4-pro`: In thinking mode, it is fixed at 0.95 when tool calling is enabled, or 1.0 otherwise; the value you pass is ignored. Setting `tool_choice` to `none` disables tool calling even when `tools` is provided. In non-thinking mode, the value you pass is used, with a default of 1.0. + + - `type`: `number` + + - `minimum`: `0` + + - `maximum`: `1` + + - `nullable`: `true` + + **Example** + + ```json + 1 + ``` + + - **`text`** (optional) + + Configuration of the text output. + + - `type`: `object` + + - `nullable`: `true` + + - **Properties** + + - **`format`** (optional) + + The output format. `{"type": "text"}` (default) for plain text; `{"type": "json_object"}` for JSON mode; `{"type": "json_schema", "name": ..., "schema": ...}` for structured output conforming to the given JSON Schema. + + If `text` is omitted or `null`, or `format` is omitted, plain text is used. When a `format` object is provided, `type` is required. + + - `type`: `object` + + - `required`: `["type"]` + + - **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["text","json_object","json_schema"]` + + - **`name`** (optional) + + The name of the schema. Required when `type` is `json_schema`. + + - `type`: `string` + + - **`schema`** (optional) + + The JSON Schema that the output must conform to. Required when `type` is `json_schema`. + + - `type`: `object` + + - **`tools`** (optional) + + A list of tools the model may call. Function names must be non-empty, at most 128 characters, match `^[a-zA-Z0-9_-]+$`, and be unique across all tools. `function` tools are supported; `web_search` is supported with `deepseek-v4-pro`; other built-in tool types are ignored. Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md) for details. + + - `type`: `array` + + - `nullable`: `true` + + - **Array items** + + - Reference: [ResponseTool](#schema-response-tool) (`#/components/schemas/ResponseTool`) + + **Example** + + ```json + null + ``` + + - **`tool_choice`** (optional) + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` (default) means the model can pick between generating a message or calling one or more tools. + + `required` means the model must call one or more tools. + + Specifying a particular tool via `{"type": "function", "name": "my_function"}` forces the model to call that tool. + + - `nullable`: `true` + + - **oneOf** + + - oneOf 1 + + - title: `Tool choice mode` + + - `type`: `string` + + - `enum`: `["none","auto","required"]` + + - oneOf 2 + + - title: `Named tool choice` + + Forces the model to call the specified tool. `name` is required when `type` is `function`. + + - `type`: `object` + + - `required`: `["type"]` + + - **Properties** + + - **`type`** (required) + + - `type`: `string` + + - `enum`: `["function"]` + + - **`name`** (optional) + + The name of the function to call. Required when `type` is `function`. + + - `type`: `string` + + - **`top_logprobs`** (optional) + + An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. + + - `type`: `integer` + + - `minimum`: `0` + + - `maximum`: `20` + + - `nullable`: `true` + + - `default`: `null` + + **Example** + + ```json + null + ``` + + - **`user`** (optional) + + A custom end-user identifier. We recommend using only ASCII letters, digits, underscores (`_`), and hyphens (`-`). The UTF-8 encoded value must not exceed 512 bytes. Do not include user privacy information. + + - It can be used to distinguish user identities on your side to help us with content safety review, for KVCache isolation, and for scheduling isolation. For more details, please refer to [Rate Limit & Isolation](https://api-docs.deepseek.com/quick_start/rate_limit.md) + + * `type`: `string` + + * `nullable`: `true` + +### schema-response + +**Response** — `#/components/schemas/Response` + +A model response in the OpenAI Responses API format. + +- `type`: `object` + +- `required`: `["id","object","created_at","status","model","output"]` + +- **Properties** + + - **`id`** (required) + + A unique identifier for the response. + + - `type`: `string` + + - **`object`** (required) + + The object type, which is always `response`. + + - `type`: `string` + + - `enum`: `["response"]` + + - **`created_at`** (required) + + The Unix timestamp (in seconds) of when the response was created. + + - `type`: `integer` + + - **`status`** (required) + + The status of the response. + + - `type`: `string` + + - `enum`: `["in_progress","completed","incomplete","failed"]` + + - **`error`** (optional) + + The error object when the response failed, with `code` and `message` fields. + + - `type`: `object` + + - `nullable`: `true` + + - **`incomplete_details`** (optional) + + The details about why the response is incomplete. The `reason` field can be `max_output_tokens` or `content_filter`. + + - `type`: `object` + + - `nullable`: `true` + + - **Properties** + + - **`reason`** (optional) + + - `type`: `string` + + - `enum`: `["max_output_tokens","content_filter"]` + + - **`model`** (required) + + The model used for the response. + + - `type`: `string` + + - **`output`** (required) + + The list of output items generated by the model. In thinking mode, the chain-of-thought is returned as a `reasoning` item before the `message` item. Function calls are returned as `function_call` items. + + - `type`: `array` + + - **Array items** + + - Reference: [ResponseOutputItem](#schema-response-output-item) (`#/components/schemas/ResponseOutputItem`) + + - **`usage`** (optional) + + - Reference: [ResponseUsage](#schema-response-usage) (`#/components/schemas/ResponseUsage`) + +### schema-response-input-item + +**ResponseInputItem** — `#/components/schemas/ResponseInputItem` + +An input item. Supported types are `message` / `function_call` / `function_call_output` / `custom_tool_call` / `custom_tool_call_output` / `reasoning` / `web_search_call`; other types are ignored. `reasoning` and `function_call` items are automatically merged into the adjacent assistant message by the server. A `web_search_call` item returned by a previous response can be passed back to restore its search results into the context. Please refer to the [Responses API Guide](https://api-docs.deepseek.com/guides/responses_api.md#multi-turn-conversation) for the pass-back rules in multi-turn conversations. + +- `type`: `object` + +- **Properties** + + - **`type`** (optional) + + The type of the input item. For `message` items, this field can be omitted if `role` is present. `custom_tool_call` / `custom_tool_call_output` items are used together with the `apply_patch` custom tool. `web_search_call` items restore the search results of a previous server-side search. + + - `type`: `string` + + - `enum`: `["message","function_call","function_call_output","custom_tool_call","custom_tool_call_output","reasoning","web_search_call"]` + + - **`role`** (optional) + + For `message` items. The role of the message author. `developer` is treated as `user`. + + - `type`: `string` + + - `enum`: `["user","assistant","system","developer"]` + + - **`content`** (optional) + + For `message` items, the message content, either a plain string or a list of `input_text` / `output_text` / `input_image` content parts. For `reasoning` items, a list of `reasoning_text` content parts. + + - **oneOf** + + - oneOf 1 + + - title: `Text content` + + - `type`: `string` + + - oneOf 2 + + - title: `Array of content parts` + + - `type`: `array` + + - **Array items** + + - Reference: [ResponseInputContentPart](#schema-response-input-content-part) (`#/components/schemas/ResponseInputContentPart`) + + - **`call_id`** (optional) + + For `function_call` / `function_call_output` items. The ID pairing a function call with its output. Must be non-empty and unique, and every `function_call` must have a matching `function_call_output`. + + - `type`: `string` + + - **`name`** (optional) + + For `function_call` items. The name of the function to call. + + - `type`: `string` + + - **`arguments`** (optional) + + For `function_call` items. The arguments to call the function with, in JSON format. + + - `type`: `string` + + - **`output`** (optional) + + For `function_call_output` / `custom_tool_call_output` items. The output of the tool call, either a plain string or a list of `input_text` / `input_image` content parts. + + - **oneOf** + + - oneOf 1 + + - title: `Text output` + + - `type`: `string` + + - oneOf 2 + + - title: `Array of content parts` + + - `type`: `array` + + - **Array items** + + - Reference: [ResponseInputContentPart](#schema-response-input-content-part) (`#/components/schemas/ResponseInputContentPart`) + +### schema-response-tool + +**ResponseTool** — `#/components/schemas/ResponseTool` + +A tool the model may call. `function` defines a function tool — note that in the Responses API format, `name` / `parameters` and other function fields are at the top level of the tool object. `custom` defines a custom tool; only `{"type": "custom", "name": "apply_patch"}` is supported, and other names return a `400` error. `web_search` enables server-side web search and is supported with `deepseek-v4-pro`. + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + The type of the tool: `function`, `custom` (only `apply_patch`), or `web_search` (`deepseek-v4-pro` only). + + - `type`: `string` + + - `enum`: `["function","custom","web_search"]` + + - **`name`** (optional) + + For `function` and `custom` tools. The name of the tool. For function tools, must be non-empty, at most 128 characters, match `^[a-zA-Z0-9_-]+$`, and be unique across all tools. For custom tools, must be `apply_patch`. + + - `type`: `string` + + - **`description`** (optional) + + For `function` tools. A description of what the function does, used by the model to choose when and how to call the function. + + - `type`: `string` + + - **`parameters`** (optional) + + - Reference: [FunctionParameters](#schema-function-parameters) (`#/components/schemas/FunctionParameters`) + +### schema-response-output-item + +**ResponseOutputItem** — `#/components/schemas/ResponseOutputItem` + +An output item generated by the model. `message` items carry the assistant text, `reasoning` items carry the chain-of-thought, `function_call` items represent function calls, `custom_tool_call` items represent custom tool calls (such as `apply_patch`), `web_search_call` items represent server-side web searches (`deepseek-v4-pro` only), and `tool_search_call` items represent tool searches. + +- `type`: `object` + +- **Properties** + + - **`type`** (optional) + + The type of the output item: `message` / `reasoning` / `function_call` / `custom_tool_call` / `web_search_call` / `tool_search_call`. + + - `type`: `string` + + - `enum`: `["message","reasoning","function_call","custom_tool_call","web_search_call","tool_search_call"]` + + - **`id`** (optional) + + The unique ID of the output item. + + - `type`: `string` + + - **`status`** (optional) + + The status of the output item. + + - `type`: `string` + + - `enum`: `["in_progress","completed","incomplete"]` + + - **`role`** (optional) + + For `message` items. Always `assistant`. + + - `type`: `string` + + - `enum`: `["assistant"]` + + - **`content`** (optional) + + For `message` items, a list of `output_text` content parts. For `reasoning` items, a list of `reasoning_text` content parts carrying the chain-of-thought in plain text. + + - `type`: `array` + + - **Array items** + + - `type`: `object` + + - **Properties** + + - **`type`** (optional) + + - `type`: `string` + + - `enum`: `["output_text","reasoning_text"]` + + - **`text`** (optional) + + - `type`: `string` + + - **`call_id`** (optional) + + For `function_call` / `custom_tool_call` / `tool_search_call` items. An identifier used when passing the tool output back to the API. + + - `type`: `string` + + - **`name`** (optional) + + For `function_call` / `custom_tool_call` items. The name of the function or custom tool to call. + + - `type`: `string` + + - **`arguments`** (optional) + + For `function_call` items. The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + + - `type`: `string` + +### schema-response-usage + +**ResponseUsage** — `#/components/schemas/ResponseUsage` + +Token and server-tool usage statistics for the response. Null in initial streaming events; read usage from the final response. + +- `type`: `object` + +- `nullable`: `true` + +- `required`: `["input_tokens","output_tokens","total_tokens"]` + +- **Properties** + + - **`input_tokens`** (required) + + Number of input tokens. + + - `type`: `integer` + + - **`input_tokens_details`** (optional) + + Breakdown of the input tokens. + + - `type`: `object` + + - **Properties** + + - **`cached_tokens`** (optional) + + Number of input tokens that hit the context cache. See [Context Caching](https://api-docs.deepseek.com/guides/kv_cache.md). + + - `type`: `integer` + + - **`output_tokens`** (required) + + Number of output tokens. + + - `type`: `integer` + + - **`output_tokens_details`** (optional) + + Breakdown of the output tokens. + + - `type`: `object` + + - **Properties** + + - **`reasoning_tokens`** (optional) + + Number of reasoning (chain-of-thought) tokens generated by the model. + + - `type`: `integer` + + - **`total_tokens`** (required) + + Total number of tokens used in the request (input + output). + + - `type`: `integer` + + - **`server_tool_use`** (optional) + + - title: `Server tool usage` + + Successful server-side web search and page-fetch counts, separate from token usage. Present only when tool\_search or tool\_fetch is greater than zero; otherwise omitted. Both fields are present when this object is returned. In streaming responses, read response.usage from the terminal response.completed, response.incomplete, or response.failed event. These are cumulative counts, not deltas. See [Server tool usage](https://api-docs.deepseek.com/guides/responses_api.md#server-tool-usage). + + - `type`: `object` + + - `required`: `["tool_search","tool_fetch"]` + + - **Properties** + + - **`tool_search`** (required) + + Number of successful web search queries. A search with multiple queries can add more than one; failed queries and queries with no results are not counted. This field can be used as a basis for billing. + + - `type`: `integer` + + - `minimum`: `0` + + - **`tool_fetch`** (required) + + Number of successful page fetches performed by open\_page or find\_in\_page. Failed attempts are not counted. This field can be used as a basis for billing. + + - `type`: `integer` + + - `minimum`: `0` + + **Example** + + ```json + { + "tool_search": 1, + "tool_fetch": 0 + } + ``` + +### schema-response-input-content-part + +**ResponseInputContentPart** — `#/components/schemas/ResponseInputContentPart` + +- **oneOf** + + - oneOf 1 + + - Reference: [ResponseInputTextContentPart](#schema-response-input-text-content-part) (`#/components/schemas/ResponseInputTextContentPart`) + + - oneOf 2 + + - Reference: [ResponseInputImageContentPart](#schema-response-input-image-content-part) (`#/components/schemas/ResponseInputImageContentPart`) + + - oneOf 3 + + - Reference: [ResponseInputReasoningTextContentPart](#schema-response-input-reasoning-text-content-part) (`#/components/schemas/ResponseInputReasoningTextContentPart`) + +### schema-function-parameters + +**FunctionParameters** — `#/components/schemas/FunctionParameters` + +The parameters the functions accepts, described as a JSON Schema object. See the [Tool Calls Guide](https://api-docs.deepseek.com/guides/tool_calls.md) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + +Omitting `parameters` defines a function with an empty parameter list. + +- `type`: `object` + +- **additionalProperties** + + - Schema: `true` + +### schema-response-input-text-content-part + +**ResponseInputTextContentPart** — `#/components/schemas/ResponseInputTextContentPart` + +- title: `Text content part` + +- `type`: `object` + +- `required`: `["type","text"]` + +- **Properties** + + - **`type`** (required) + + The type of the content part. + + - `type`: `string` + + - `enum`: `["input_text","output_text"]` + + - **`text`** (required) + + The text content. + + - `type`: `string` + +### schema-response-input-image-content-part + +**ResponseInputImageContentPart** — `#/components/schemas/ResponseInputImageContentPart` + +- title: `Image content part` + +An image content part. Processed as a real image. Allowed only in `user` / `developer` message items and in the `output` of `function_call_output` / `custom_tool_call_output` items; images in `system` or `assistant` messages return a `400` error ("Image in system message is unsupported" / "Image in assistant message is unsupported"). + +- `type`: `object` + +- `required`: `["type"]` + +- **Properties** + + - **`type`** (required) + + The type of the content part, in this case `input_image`. + + - `type`: `string` + + - `enum`: `["input_image"]` + + - **`image_url`** (optional) + + The image source, either an `http(s)` URL of the image (max 8192 characters) or a base64-encoded data URL (`data:image/jpeg;base64,...`). Supported formats: JPEG, PNG, GIF, and WebP. Mutually exclusive with `file_id`: passing neither returns a `400` error ("input\_image must have image\_url or file\_id"); passing both returns a `400` error ("input\_image cannot have both image\_url and file\_id"). + + - `type`: `string` + + - **`detail`** (optional) + + Controls how the image is processed. `low` downsamples the image to 512x512 (faster, cheaper). `high`, `original`, and `auto` keep the original image. Ignored when `file_id` is set. + + - `type`: `string` + + - `enum`: `["low","high","original","auto"]` + + - **`file_id`** (optional) + + The ID of an image file uploaded via the [Files API](https://api-docs.deepseek.com/guides/files_api.md), of the form `file-api-...`. Mutually exclusive with `image_url`; `detail` is ignored when `file_id` is set. + + - `type`: `string` + +### schema-response-input-reasoning-text-content-part + +**ResponseInputReasoningTextContentPart** — `#/components/schemas/ResponseInputReasoningTextContentPart` + +- title: `Reasoning text content part` + +- `type`: `object` + +- `required`: `["type","text"]` + +- **Properties** + + - **`type`** (required) + + The type of the content part, in this case `reasoning_text`. + + - `type`: `string` + + - `enum`: `["reasoning_text"]` + + - **`text`** (required) + + The chain-of-thought text content. + + - `type`: `string` diff --git a/tests/fixtures/official-model-registry/sources/deepseek-thinking.body b/tests/fixtures/official-model-registry/sources/deepseek-thinking.body new file mode 100644 index 00000000..87623d47 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/deepseek-thinking.body @@ -0,0 +1,54 @@ + + + + + +Thinking Mode | DeepSeek API Docs + + + + +
Skip to main content

Thinking Mode

+

The DeepSeek model supports the thinking mode: before outputting the final answer, the model will first output a chain-of-thought reasoning to improve the accuracy of the final response.

+

Thinking Mode Toggle and Effort Control​

+
Control Parameter (OpenAI Format)Control Parameter (Anthropic Format)Control Parameter (Responses API Format)
Thinking Mode Toggle(1){"thinking": {"type": "enabled/disabled"}}{"reasoning": {"effort": "none/low/high/max"}}
(none disables thinking mode)
Thinking Effort Control(2){"reasoning_effort": "low/high/max"}{"output_config": {"effort": "low/high/max"}}
+

(1) Thinking mode is enabled by default, with the default effort being high
+(2) The mapping between the effort set by the user and the model's actual reasoning effort is as follows:

Requested effortActual mapped effort
minimallow
lowlow
mediumhigh
highhigh
xhighhigh
maxmax
ultramax
+

When using Chat Completion with the OpenAI SDK to set the thinking parameter, you need to pass the thinking parameter within extra_body:

+
response = client.chat.completions.create(
model="deepseek-flash",
# ...
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
+

Input and Output Parameters​

+

Thinking mode does not support the temperature, presence_penalty, or frequency_penalty parameters. Please note that, for compatibility with existing software, setting these parameters will not trigger an error but will also have no effect.

+

top_p behavior depends on the model:

+
    +
  • deepseek-flash: only takes effect in thinking mode, where the effective range is 0.95–1.0; values below 0.95 are treated as 0.95. In non-thinking mode it is fixed at 1.0 and your value is ignored.
  • +
  • deepseek-v4-pro: in thinking mode your value is ignored (fixed at 0.95 when tool calling is enabled, otherwise 1.0); in non-thinking mode it takes effect. Setting tool_choice to none disables tool calling even when tools is provided.
  • +
+

In thinking mode, the chain-of-thought content is returned via the reasoning_content parameter, at the same level as content. In subsequent requests, whether reasoning_content should be passed back and whether it will be concatenated into the context depends on whether the request carries the tools parameter:

+
    +
  • If the request carries the tools parameter: the reasoning_content of all previous turns should be passed back to the API and will be concatenated into the context. See Tool Calls for details.
  • +
  • If the request does not carry the tools parameter: reasoning_content does not need to be passed back; even if passed to the API, it will be ignored and will not be concatenated into the context. See Multi-turn Conversation for details.
  • +
+

Multi-turn Conversation​

+

In each turn of the conversation, the model outputs the CoT (reasoning_content) and the final answer (content). If the request does not carry the tools parameter, the CoT content from previous turns will not be concatenated into the context in the next turn, as illustrated in the following diagram:

+
+

Sample Code​

+

The following code, using Python as an example, demonstrates how to access the CoT and the final answer, as well as how to concatenate context in multi-turn conversations.

+
from openai import OpenAI
client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://api.deepseek.com")

# Turn 1
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
model="deepseek-flash",
messages=messages,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)

reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content

# Turn 2
# The reasoning_content will be ignored by the API
messages.append(response.choices[0].message)
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
model="deepseek-flash",
messages=messages,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
# ...
+

Tool Calls​

+

The DeepSeek model's thinking mode supports tool calls. Before outputting the final answer, the model can perform multiple turns of reasoning and tool calls to improve the quality of the response. The calling pattern is illustrated below:

+
+

Please note that for requests carrying the tools parameter, the reasoning_content must be fully passed back to the API in all subsequent requests — even for turns where the model did not perform a tool call. If your code does not correctly pass back reasoning_content, the API will return a 400 error. Please refer to the sample code below for the correct approach.

+

Sample Code​

+

Below is a simple sample code for tool calls in thinking mode:

+
import os
import json
from openai import OpenAI
from datetime import datetime

# The definition of the tools
tools = [
{
"type": "function",
"function": {
"name": "get_date",
"description": "Get the current date",
"parameters": { "type": "object", "properties": {} },
},
},
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather of a location, the user should supply the location and date.",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string", "description": "The city name" },
"date": { "type": "string", "description": "The date in format YYYY-mm-dd" },
},
"required": ["location", "date"],
},
},
},
]

# The mocked version of the tool calls
def get_date_mock():
return datetime.now().strftime("%Y-%m-%d")

def get_weather_mock(location, date):
return "Cloudy 7~13°C"

TOOL_CALL_MAP = {
"get_date": get_date_mock,
"get_weather": get_weather_mock,
}

def run_turn(turn, messages):
sub_turn = 1
while True:
response = client.chat.completions.create(
model='deepseek-flash',
messages=messages,
tools=tools,
reasoning_effort="high",
extra_body={ "thinking": { "type": "enabled" } },
)
messages.append(response.choices[0].message)
reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content
tool_calls = response.choices[0].message.tool_calls
print(f"Turn {turn}.{sub_turn}\n{reasoning_content=}\n{content=}\n{tool_calls=}")
# If there is no tool calls, then the model should get a final answer and we need to stop the loop
if tool_calls is None:
break
for tool in tool_calls:
tool_function = TOOL_CALL_MAP[tool.function.name]
tool_result = tool_function(**json.loads(tool.function.arguments))
print(f"tool result for {tool.function.name}: {tool_result}\n")
messages.append({
"role": "tool",
"tool_call_id": tool.id,
"content": tool_result,
})
sub_turn += 1
print()

client = OpenAI(
api_key=os.environ.get('DEEPSEEK_API_KEY'),
base_url=os.environ.get('DEEPSEEK_BASE_URL'),
)

# The user starts a question
turn = 1
messages = [{
"role": "user",
"content": "How's the weather in Hangzhou Tomorrow",
}]
run_turn(turn, messages)

# The user starts a new question
turn = 2
messages.append({
"role": "user",
"content": "How's the weather in Guangzhou Tomorrow",
})
run_turn(turn, messages)
+

In each sub-request of Turn 1, the reasoning_content generated during that turn is sent to the API, allowing the model to continue its previous reasoning. response.choices[0].message contains all necessary fields for the assistant message, including content, reasoning_content, and tool_calls. For simplicity, you can directly append the message to the end of the messages list using the following code:

+
messages.append(response.choices[0].message)
+

This line of code is equivalent to:

+
messages.append({
'role': 'assistant',
'content': response.choices[0].message.content,
'reasoning_content': response.choices[0].message.reasoning_content,
'tool_calls': response.choices[0].message.tool_calls,
})
+

Additionally, in the Turn 2 request, we still pass the reasoning_content generated in Turn 1 to the API.

+

The sample output of this code is as follows:

+
Turn 1.1
reasoning_content="The user is asking about the weather in Hangzhou tomorrow. I need to get tomorrow's date first, then call the weather function."
content="Let me check tomorrow's weather in Hangzhou for you. First, let me get tomorrow's date."
tool_calls=[ChatCompletionMessageFunctionToolCall(id='call_00_kw66qNnNto11bSfJVIdlV5Oo', function=Function(arguments='{}', name='get_date'), type='function', index=0)]
tool result for get_date: 2026-04-19

Turn 1.2
reasoning_content="Today is 2026-04-19, so tomorrow is 2026-04-20. Now I'll call the weather function for Hangzhou."
content=''
tool_calls=[ChatCompletionMessageFunctionToolCall(id='call_00_H2SCW6136vWJGq9SQlBuhVt4', function=Function(arguments='{"location": "Hangzhou", "date": "2026-04-20"}', name='get_weather'), type='function', index=0)]
tool result for get_weather: Cloudy 7~13°C

Turn 1.3
reasoning_content='The weather result is in. Let me share this with the user.'
content="Here's the weather forecast for **Hangzhou tomorrow (April 20, 2026)**:\n\n- 🌤 **Condition:** Cloudy \n- 🌡 **Temperature:** 7°C ~ 13°C (45°F ~ 55°F)\n\nIt'll be on the cooler side, so you might want to bring a light jacket if you're heading out! Let me know if you need anything else."
tool_calls=None

Turn 2.1
reasoning_content='The user is asking about the weather in Guangzhou tomorrow. Today is 2026-04-19, so tomorrow is 2026-04-20. I can directly call the weather function.'
content=''
tool_calls=[ChatCompletionMessageFunctionToolCall(id='call_00_8URkLt5NjmNkVKhDmMcNq9Mo', function=Function(arguments='{"location": "Guangzhou", "date": "2026-04-20"}', name='get_weather'), type='function', index=0)]
tool result for get_weather: Cloudy 7~13°C

Turn 2.2
reasoning_content='The weather result for Guangzhou is the same as Hangzhou. Let me share this with the user.'
content="Here's the weather forecast for **Guangzhou tomorrow (April 20, 2026)**:\n\n- 🌤 **Condition:** Cloudy \n- 🌡 **Temperature:** 7°C ~ 13°C (45°F ~ 55°F)\n\nIt'll be cool and cloudy, so a light jacket would be a good idea if you're going out. Let me know if there's anything else you'd like to know!"
tool_calls=None
+ + \ No newline at end of file diff --git a/tests/fixtures/official-model-registry/sources/openai-gpt-6-astra.md b/tests/fixtures/official-model-registry/sources/openai-gpt-6-astra.md new file mode 100644 index 00000000..71eb1d1f --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/openai-gpt-6-astra.md @@ -0,0 +1,46 @@ +# GPT-6 Astra + +- Model ID: gpt-6-astra +- Model type: reasoning +- Current snapshot: gpt-6-astra + +Our most capable model for the most demanding work. + +GPT-6 Astra is our most capable model for the most demanding work. +Use it for complex reasoning, coding, computer use, research, and document creation. +`reasoning.effort` supports `low`, `medium`, `high`, `xhigh`, and `max`. + +Get started with GPT-6 Astra using the [model guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra). + +## Snapshots +- gpt-6-astra + +## Current snapshot details +- Context window: 1,050,000 tokens +- Max input: 922,000 tokens +- Max output: 128,000 tokens +- Knowledge cutoff: 2026-04-30 +- Input modalities: text, image +- Output modalities: text +- Supported endpoints: responses, chat_completions, batch +- Supported features: streaming, structured_outputs, function_calling, file_search, image_input, web_search, prompt_caching + +## Supported tools +- web_search +- file_search +- image_generation +- code_interpreter +- hosted_shell +- apply_patch +- skills +- computer_use +- mcp +- tool_search + +## Pricing notes +- Prompts with more than 272K input tokens are priced at 2x input and cache rates and 1.5x output for the full request. +- Cache writes are billed at 1.25x the uncached input token rate. +- Batch and Flex are priced at 50% of Standard rates. Fast mode is priced at 2x the applicable rates. + +Playground: https://platform.openai.com/chat/edit?models=gpt-6-astra + diff --git a/tests/fixtures/official-model-registry/sources/openai-gpt-6-luna.md b/tests/fixtures/official-model-registry/sources/openai-gpt-6-luna.md new file mode 100644 index 00000000..a76aea1c --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/openai-gpt-6-luna.md @@ -0,0 +1,50 @@ +# GPT-6 Luna + +- Model ID: gpt-6-luna +- Model type: reasoning +- Current snapshot: gpt-6-luna + +Our most efficient model for focused, high-volume tasks. + +GPT-6 Luna is our most efficient model for focused, high-volume tasks. + +`reasoning.effort` supports `none`, `low`, `medium` (default), `high`, `xhigh`, and `max`. +Use the Responses API for built-in tools and function calling. Chat Completions supports function calling only with `reasoning_effort` set to `none`. + +EU data residency is available with Standard, Fast, Flex, and Batch processing. +See [data residency eligibility](https://developers.openai.com/api/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency). + +## Snapshots +- gpt-6-luna + +## Current snapshot details +- Context window: 1,050,000 tokens +- Max input: 922,000 tokens +- Max output: 128,000 tokens +- Knowledge cutoff: 2026-05-18 +- Input modalities: text, image +- Output modalities: text +- Supported endpoints: responses, chat_completions, batch +- Supported features: streaming, structured_outputs, function_calling, file_search, image_input, web_search, prompt_caching + +## Supported tools +- web_search +- file_search +- image_generation +- code_interpreter +- hosted_shell +- apply_patch +- skills +- computer_use +- mcp +- tool_search + +## Pricing notes +- Cached input tokens are priced at 10% of the uncached input token rate. +- Cache writes are billed at 1.25x the uncached input token rate. +- Prompts with more than 272K input tokens are priced at 2x input and cache rates and 1.5x output for the full request. +- Regional processing adds a 10% premium where available. EU data residency is available with Standard, Fast, Flex, and Batch processing. +- Batch and Flex are priced at 50% of Standard rates. Fast mode is priced at 2x the applicable rates. + +Playground: https://platform.openai.com/chat/edit?models=gpt-6-luna + diff --git a/tests/fixtures/official-model-registry/sources/openai-gpt-6-sol.md b/tests/fixtures/official-model-registry/sources/openai-gpt-6-sol.md new file mode 100644 index 00000000..41a37da2 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/openai-gpt-6-sol.md @@ -0,0 +1,51 @@ +# GPT-6 Sol + +- Model ID: gpt-6-sol +- Model type: reasoning +- Current snapshot: gpt-6-sol + +Built to power complex coding and agentic workflows. + +GPT-6 Sol is built for complex coding and agentic workflows. +See [GPT-6.1 Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol) for the newer Sol model. + +`reasoning.effort` supports `none`, `low`, `medium` (default), `high`, `xhigh`, and `max`. +Use the Responses API for built-in tools and function calling. Chat Completions supports function calling only with `reasoning_effort` set to `none`. + +EU data residency is available with Standard, Flex, and Batch processing. EU data residency is not available with Fast processing. +See [data residency eligibility](https://developers.openai.com/api/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency). + +## Snapshots +- gpt-6-sol + +## Current snapshot details +- Context window: 1,050,000 tokens +- Max input: 922,000 tokens +- Max output: 128,000 tokens +- Knowledge cutoff: 2026-04-20 +- Input modalities: text, image +- Output modalities: text +- Supported endpoints: responses, chat_completions, batch +- Supported features: streaming, structured_outputs, function_calling, file_search, image_input, web_search, prompt_caching + +## Supported tools +- web_search +- file_search +- image_generation +- code_interpreter +- hosted_shell +- apply_patch +- skills +- computer_use +- mcp +- tool_search + +## Pricing notes +- Cached input tokens are priced at 10% of the uncached input token rate. +- Cache writes are billed at 1.25x the uncached input token rate. +- Prompts with more than 272K input tokens are priced at 2x input and cache rates and 1.5x output for the full request. +- Regional processing adds a 10% premium where available. +- Batch and Flex are priced at 50% of Standard rates. Fast mode is priced at 2x the applicable rates. + +Playground: https://platform.openai.com/chat/edit?models=gpt-6-sol + diff --git a/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-sol.md b/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-sol.md new file mode 100644 index 00000000..a00f989a --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-sol.md @@ -0,0 +1,54 @@ +# GPT-6.1 Sol + +- Model ID: gpt-6.1-sol +- Model type: reasoning +- Current snapshot: gpt-6.1-sol + +Near-Astra performance for complex work at a lower cost. + +Use GPT-6.1 Sol for complex coding, computer use, and professional work. + +`reasoning.effort` supports `low`, `medium` (default), `high`, `xhigh`, and +`max`. + +Tool calling requires the Responses API. + +See the [GPT-6 guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra#gpt-61-sol) +for prompting and migration guidance. + +## Snapshots +- gpt-6.1-sol + +## Current snapshot details +- Context window: 1,050,000 tokens +- Max input: 922,000 tokens +- Max output: 128,000 tokens +- Knowledge cutoff: 2026-04-30 +- Input modalities: text, image +- Output modalities: text +- Supported endpoints: responses, chat_completions, batch +- Supported features: streaming, structured_outputs, function_calling, file_search, image_input, web_search, prompt_caching + +## Supported tools +- web_search +- file_search +- image_generation +- code_interpreter +- hosted_shell +- apply_patch +- skills +- computer_use +- mcp +- tool_search + +## Pricing notes +- Cached input tokens are priced at 5% of the uncached input token rate. +- Cache writes are billed at 1.25x the uncached input token rate. +- API prompts with more than 272K input tokens are priced at 2x input and cache rates and 1.5x output for the full request. +- Fast mode prices are 2x Standard. Batch and Flex prices are 50% lower than Standard. +- Ultrafast mode prices are 6x Standard. +- Regional processing adds a 10% premium where available. +- GPT-6.1 Sol uses a default context window of 500K tokens in Codex and ChatGPT Work. Usage drawn from your subscription has no long-context surcharge. See [Codex pricing](/codex/pricing). + +Playground: https://platform.openai.com/chat/edit?models=gpt-6.1-sol + diff --git a/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-terra.md b/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-terra.md new file mode 100644 index 00000000..a4496f57 --- /dev/null +++ b/tests/fixtures/official-model-registry/sources/openai-gpt-6.1-terra.md @@ -0,0 +1,54 @@ +# GPT-6.1 Terra + +- Model ID: gpt-6.1-terra +- Model type: reasoning +- Current snapshot: gpt-6.1-terra + +A fast, efficient model for visual reasoning, precise computer use, and clear, natural writing. + +Use GPT-6.1 Terra to match product photos to catalog entries, interpret +technical drawings, act on application screens, or draft and revise text. + +`reasoning.effort` supports `none`, `low`, `medium` (default), `high`, +`xhigh`, and `max`. + +Tool calling requires the Responses API. + +See the [GPT-6 guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra#gpt-61-terra) +for prompting and migration guidance. + +## Snapshots +- gpt-6.1-terra + +## Current snapshot details +- Context window: 1,050,000 tokens +- Max input: 922,000 tokens +- Max output: 128,000 tokens +- Knowledge cutoff: 2026-06-01 +- Input modalities: text, image +- Output modalities: text +- Supported endpoints: responses, chat_completions, batch +- Supported features: streaming, structured_outputs, function_calling, file_search, image_input, web_search, prompt_caching + +## Supported tools +- web_search +- file_search +- image_generation +- code_interpreter +- hosted_shell +- apply_patch +- skills +- computer_use +- mcp +- tool_search + +## Pricing notes +- Cached input tokens are priced at 5% of the uncached input token rate. +- Cache-write prices shown use 30-minute retention. Standard cache writes cost $1.25 per million tokens for 30-minute retention and $2.50 for 12-hour retention, before long-context adjustments. +- Prompts with more than 272K input tokens are priced at 2x input and cache rates and 1.5x output for the full request. +- Batch and Flex prices are 50% lower than Standard. +- Regional processing adds a 10% premium where available. +- Fast mode prices are 2x Standard. + +Playground: https://platform.openai.com/chat/edit?models=gpt-6.1-terra +