From 4dc518a5f46dd1d667760541355446ee16450bdf Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Sun, 19 Apr 2026 14:21:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=20API=20=E5=8F=82?= =?UTF-8?q?=E8=80=83=E6=96=87=E6=A1=A3=EF=BC=8C=E6=8B=86=E5=88=86=E4=B8=BA?= =?UTF-8?q?=E7=8B=AC=E7=AB=8B=E6=96=87=E4=BB=B6=E5=B9=B6=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=20CLI=20=E9=A3=8E=E6=A0=BC=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api_reference/anthropic/count_tokens.md | 3635 +-- docs/api_reference/anthropic/create.md | 1036 + docs/api_reference/anthropic/list.md | 240 + docs/api_reference/anthropic/messages.md | 24531 +++++++++++++--- docs/api_reference/anthropic/models.md | 291 - .../anthropic/{models_get.md => retrieve.md} | 114 +- .../api_reference/openai/Create embeddings.md | 175 + docs/api_reference/openai/Create image.md | 367 + .../openai/{models.md => List models.md} | 0 docs/api_reference/openai/Retrieve model.md | 69 + .../Create chat completion.md} | 0 .../openai/chat/Streaming events.md | 248 + .../Create a model response.md} | 0 .../Get input token counts.md} | 0 docs/conversion_anthropic.md | 786 + docs/conversion_design.md | 1248 +- docs/conversion_openai.md | 1165 + 17 files changed, 25227 insertions(+), 8678 deletions(-) create mode 100644 docs/api_reference/anthropic/create.md create mode 100644 docs/api_reference/anthropic/list.md delete mode 100644 docs/api_reference/anthropic/models.md rename docs/api_reference/anthropic/{models_get.md => retrieve.md} (64%) create mode 100644 docs/api_reference/openai/Create embeddings.md create mode 100644 docs/api_reference/openai/Create image.md rename docs/api_reference/openai/{models.md => List models.md} (100%) create mode 100644 docs/api_reference/openai/Retrieve model.md rename docs/api_reference/openai/{chat.md => chat/Create chat completion.md} (100%) create mode 100644 docs/api_reference/openai/chat/Streaming events.md rename docs/api_reference/openai/{chat_response.md => responses/Create a model response.md} (100%) rename docs/api_reference/openai/{count_token.md => responses/Get input token counts.md} (100%) create mode 100644 docs/conversion_anthropic.md create mode 100644 docs/conversion_openai.md diff --git a/docs/api_reference/anthropic/count_tokens.md b/docs/api_reference/anthropic/count_tokens.md index 093edcc..d9ecd06 100644 --- a/docs/api_reference/anthropic/count_tokens.md +++ b/docs/api_reference/anthropic/count_tokens.md @@ -1,5 +1,7 @@ ## Count Tokens +`$ ant messages count-tokens` + **post** `/v1/messages/count_tokens` Count the number of tokens in a Message. @@ -8,9 +10,9 @@ The Token Count API can be used to count the number of tokens in a Message, incl Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) -### Body Parameters +### Parameters -- `messages: array of MessageParam` +- `--message: array of MessageParam` Input messages. @@ -61,2489 +63,27 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d There is a limit of 100,000 messages in a single request. - - `content: string or array of ContentBlockParam` - - - `UnionMember0 = string` - - - `UnionMember1 = array of ContentBlockParam` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `ThinkingBlockParam = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `RedactedThinkingBlockParam = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `ToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `ToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` - - - `tool_use_id: string` - - - `type: "tool_result"` - - - `"tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `ToolReferenceBlockParam = object { tool_name, type, cache_control }` - - Tool reference block that can be included in tool_result content. - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `is_error: optional boolean` - - - `ServerToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebSearchToolResultBlockParamContent` - - - `WebSearchToolResultBlockItem = array of WebSearchResultBlockParam` - - - `encrypted_content: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `page_age: optional string` - - - `WebSearchToolRequestError = object { error_code, type }` - - - `error_code: WebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` - - - `WebFetchToolResultErrorBlockParam = object { error_code, type }` - - - `error_code: WebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `WebFetchBlockParam = object { content, type, url, retrieved_at }` - - - `content: DocumentBlockParam` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `retrieved_at: optional string` - - ISO 8601 timestamp when the content was retrieved - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `CodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: CodeExecutionToolResultBlockParamContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `CodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: CodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `CodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `EncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` - - - `BashCodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: BashCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of BashCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `TextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` - - - `TextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` - - - `error_code: TextEditorCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `error_message: optional string` - - - `TextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `num_lines: optional number` - - - `start_line: optional number` - - - `total_lines: optional number` - - - `TextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `TextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `lines: optional array of string` - - - `new_lines: optional number` - - - `new_start: optional number` - - - `old_lines: optional number` - - - `old_start: optional number` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` - - - `ToolSearchToolResultErrorParam = object { error_code, type }` - - - `error_code: ToolSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `ToolSearchToolSearchResultBlockParam = object { tool_references, type }` - - - `tool_references: array of ToolReferenceBlockParam` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ContainerUploadBlockParam = object { file_id, type, cache_control }` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `role: "user" or "assistant"` - - - `"user"` - - - `"assistant"` - -- `model: Model` +- `--model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` - - The model that will complete your prompt. - - See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - - `"claude-opus-4-7"` - - Frontier intelligence for long-running agents and coding - - - `"claude-mythos-preview"` - - New class of intelligence, strongest in coding and cybersecurity - - - `"claude-opus-4-6"` - - Frontier intelligence for long-running agents and coding - - - `"claude-sonnet-4-6"` - - Best combination of speed and intelligence - - - `"claude-haiku-4-5"` - - Fastest model with near-frontier intelligence - - - `"claude-haiku-4-5-20251001"` - - Fastest model with near-frontier intelligence - - - `"claude-opus-4-5"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-opus-4-5-20251101"` - - Premium model combining maximum intelligence with practical performance - - - `"claude-sonnet-4-5"` - - High-performance model for agents and coding - - - `"claude-sonnet-4-5-20250929"` - - High-performance model for agents and coding - - - `"claude-opus-4-1"` - - Exceptional model for specialized complex tasks - - - `"claude-opus-4-1-20250805"` - - Exceptional model for specialized complex tasks - - - `"claude-opus-4-0"` - - Powerful model for complex tasks - - - `"claude-opus-4-20250514"` - - Powerful model for complex tasks - - - `"claude-sonnet-4-0"` - - High-performance model with extended thinking - - - `"claude-sonnet-4-20250514"` - - High-performance model with extended thinking - - - `"claude-3-haiku-20240307"` - - Fast and cost-effective model - - - `UnionMember1 = string` - -- `cache_control: optional CacheControlEphemeral` +- `--cache-control: optional object { type, ttl }` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - -- `output_config: optional OutputConfig` +- `--output-config: optional object { effort, format }` Configuration options for the model's output, such as the output format. - - `effort: optional "low" or "medium" or "high" or 2 more` - - All possible effort levels. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - - - `"max"` - - - `format: optional JSONOutputFormat` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `schema: map[unknown]` - - The JSON schema of the format - - - `type: "json_schema"` - - - `"json_schema"` - -- `system: optional string or array of TextBlockParam` +- `--system: optional string or array of TextBlockParam` System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - -- `thinking: optional ThinkingConfigParam` +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` Configuration for enabling Claude's extended thinking. @@ -2551,107 +91,11 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - `ThinkingConfigEnabled = object { budget_tokens, type, display }` - - - `budget_tokens: number` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `type: "enabled"` - - - `"enabled"` - - - `display: optional "summarized" or "omitted"` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `"summarized"` - - - `"omitted"` - - - `ThinkingConfigDisabled = object { type }` - - - `type: "disabled"` - - - `"disabled"` - - - `ThinkingConfigAdaptive = object { type, display }` - - - `type: "adaptive"` - - - `"adaptive"` - - - `display: optional "summarized" or "omitted"` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `"summarized"` - - - `"omitted"` - -- `tool_choice: optional ToolChoice` +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - `ToolChoiceAuto = object { type, disable_parallel_tool_use }` - - The model will automatically decide whether to use tools. - - - `type: "auto"` - - - `"auto"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `ToolChoiceAny = object { type, disable_parallel_tool_use }` - - The model will use any available tools. - - - `type: "any"` - - - `"any"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceTool = object { name, type, disable_parallel_tool_use }` - - The model will use the specified tool with `tool_choice.name`. - - - `name: string` - - The name of the tool to use. - - - `type: "tool"` - - - `"tool"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceNone = object { type }` - - The model will not be allowed to use tools. - - - `type: "none"` - - - `"none"` - -- `tools: optional array of MessageCountTokensTool` +- `--tool: optional array of MessageCountTokensTool` Definitions of tools that the model may use. @@ -2715,1045 +159,9 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - `Tool = object { input_schema, name, allowed_callers, 7 more }` - - - `input_schema: object { type, properties, required }` - - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. - - This defines the shape of the `input` that your tool accepts and that the model will produce. - - - `type: "object"` - - - `"object"` - - - `properties: optional map[unknown]` - - - `required: optional array of string` - - - `name: string` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `description: optional string` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `eager_input_streaming: optional boolean` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `type: optional "custom"` - - - `"custom"` - - - `ToolBash20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "bash"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"bash"` - - - `type: "bash_20250124"` - - - `"bash_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250522"` - - - `"code_execution_20250522"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `MemoryTool20250818 = object { name, type, allowed_callers, 4 more }` - - - `name: "memory"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"memory"` - - - `type: "memory_20250818"` - - - `"memory_20250818"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_editor"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_editor"` - - - `type: "text_editor_20250124"` - - - `"text_editor_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250429"` - - - `"text_editor_20250429"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250728"` - - - `"text_editor_20250728"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `max_characters: optional number` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20250305"` - - - `"web_search_20250305"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20250910"` - - - `"web_fetch_20250910"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_search"` - - - `type: "web_search_20260209"` - - - `"web_search_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20260209"` - - - `"web_fetch_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebFetchTool20260309 = object { name, type, allowed_callers, 9 more }` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20260309"` - - - `"web_fetch_20260309"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `use_cache: optional boolean` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `ToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_bm25"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_bm25"` - - - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - - - `"tool_search_tool_bm25_20251119"` - - - `"tool_search_tool_bm25"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_regex"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_regex"` - - - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - - - `"tool_search_tool_regex_20251119"` - - - `"tool_search_tool_regex"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - ### Returns -- `MessageTokensCount = object { input_tokens }` +- `message_tokens_count: object { input_tokens }` - `input_tokens: number` @@ -3761,18 +169,9 @@ Learn more about token counting in our [user guide](https://docs.claude.com/en/d ### Example -```http -curl https://api.anthropic.com/v1/messages/count_tokens \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - -d '{ - "messages": [ - { - "content": "Hello, world", - "role": "user" - } - ], - "model": "claude-opus-4-6" - }' +```cli +ant messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 ``` diff --git a/docs/api_reference/anthropic/create.md b/docs/api_reference/anthropic/create.md new file mode 100644 index 0000000..ff6a8ed --- /dev/null +++ b/docs/api_reference/anthropic/create.md @@ -0,0 +1,1036 @@ +## Create + +`$ ant messages create` + +**post** `/v1/messages` + +Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. + +The Messages API can be used for either single queries or stateless multi-turn conversations. + +Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) + +### Parameters + +- `--max-tokens: number` + + The maximum number of tokens to generate before stopping. + + Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. + + Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional string` + + Container identifier for reuse across requests. + +- `--inference-geo: optional string` + + Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--metadata: optional object { user_id }` + + An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--service-tier: optional "auto" or "standard_only"` + + Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--stop-sequence: optional array of string` + + Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of ToolUnion` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +### Returns + +- `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Example + +```cli +ant messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` diff --git a/docs/api_reference/anthropic/list.md b/docs/api_reference/anthropic/list.md new file mode 100644 index 0000000..7eab3af --- /dev/null +++ b/docs/api_reference/anthropic/list.md @@ -0,0 +1,240 @@ +## List + +`$ ant models list` + +**get** `/v1/models` + +List available models. + +The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. + +### Parameters + +- `--after-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Query param: Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +- `--beta: optional array of AnthropicBeta` + + Header param: Optional header to specify the beta version(s) you want to use. + +### Returns + +- `ListResponse_ModelInfo_: object { data, first_id, has_more, last_id }` + + - `data: array of ModelInfo` + + - `id: string` + + Unique model identifier. + + - `capabilities: object { batch, citations, code_execution, 6 more }` + + Model capability information. + + - `batch: object { supported }` + + Whether the model supports the Batch API. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `citations: object { supported }` + + Whether the model supports citation generation. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `code_execution: object { supported }` + + Whether the model supports code execution tools. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` + + Context management support and available strategies. + + - `clear_thinking_20251015: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `clear_tool_uses_20250919: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `compact_20260112: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `effort: object { high, low, max, 3 more }` + + Effort (reasoning_effort) support and available levels. + + - `high: object { supported }` + + Whether the model supports high effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `low: object { supported }` + + Whether the model supports low effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `max: object { supported }` + + Whether the model supports max effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `medium: object { supported }` + + Whether the model supports medium effort level. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `xhigh: object { supported }` + + Indicates whether a capability is supported. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `image_input: object { supported }` + + Whether the model accepts image content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `pdf_input: object { supported }` + + Whether the model accepts PDF content blocks. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `structured_outputs: object { supported }` + + Whether the model supports structured output / JSON mode / strict tool schemas. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `thinking: object { supported, types }` + + Thinking capability and supported type configurations. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `types: object { adaptive, enabled }` + + Supported thinking type configurations. + + - `adaptive: object { supported }` + + Whether the model supports thinking with type 'adaptive' (auto). + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `enabled: object { supported }` + + Whether the model supports thinking with type 'enabled'. + + - `supported: boolean` + + Whether this capability is supported by the model. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. + + - `display_name: string` + + A human-readable name for the model. + + - `max_input_tokens: number` + + Maximum input context window size in tokens for this model. + + - `max_tokens: number` + + Maximum value for the `max_tokens` parameter when using this model. + + - `type: "model"` + + Object type. + + For Models, this is always `"model"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant models list \ + --api-key my-anthropic-api-key +``` diff --git a/docs/api_reference/anthropic/messages.md b/docs/api_reference/anthropic/messages.md index b0c9a5f..14aa06d 100644 --- a/docs/api_reference/anthropic/messages.md +++ b/docs/api_reference/anthropic/messages.md @@ -1,5 +1,9 @@ +# Messages + ## Create +`$ ant messages create` + **post** `/v1/messages` Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. @@ -8,9 +12,9 @@ The Messages API can be used for either single queries or stateless multi-turn c Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) -### Body Parameters +### Parameters -- `max_tokens: number` +- `--max-tokens: number` The maximum number of tokens to generate before stopping. @@ -18,7 +22,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. -- `messages: array of MessageParam` +- `--message: array of MessageParam` Input messages. @@ -69,2239 +73,754 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en There is a limit of 100,000 messages in a single request. - - `content: string or array of ContentBlockParam` - - - `UnionMember0 = string` - - - `UnionMember1 = array of ContentBlockParam` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `ThinkingBlockParam = object { signature, thinking, type }` - - - `signature: string` - - - `thinking: string` - - - `type: "thinking"` - - - `"thinking"` - - - `RedactedThinkingBlockParam = object { data, type }` - - - `data: string` - - - `type: "redacted_thinking"` - - - `"redacted_thinking"` - - - `ToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: string` - - - `type: "tool_use"` - - - `"tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `ToolResultBlockParam = object { tool_use_id, type, cache_control, 2 more }` - - - `tool_use_id: string` - - - `type: "tool_result"` - - - `"tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `SearchResultBlockParam = object { content, source, title, 3 more }` - - - `content: array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `source: string` - - - `title: string` - - - `type: "search_result"` - - - `"search_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `DocumentBlockParam = object { source, type, cache_control, 3 more }` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `ToolReferenceBlockParam = object { tool_name, type, cache_control }` - - Tool reference block that can be included in tool_result content. - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `is_error: optional boolean` - - - `ServerToolUseBlockParam = object { id, input, name, 3 more }` - - - `id: string` - - - `input: map[unknown]` - - - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - - - `"web_search"` - - - `"web_fetch"` - - - `"code_execution"` - - - `"bash_code_execution"` - - - `"text_editor_code_execution"` - - - `"tool_search_tool_regex"` - - - `"tool_search_tool_bm25"` - - - `type: "server_tool_use"` - - - `"server_tool_use"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebSearchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebSearchToolResultBlockParamContent` - - - `WebSearchToolResultBlockItem = array of WebSearchResultBlockParam` - - - `encrypted_content: string` - - - `title: string` - - - `type: "web_search_result"` - - - `"web_search_result"` - - - `url: string` - - - `page_age: optional string` - - - `WebSearchToolRequestError = object { error_code, type }` - - - `error_code: WebSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"max_uses_exceeded"` - - - `"too_many_requests"` - - - `"query_too_long"` - - - `"request_too_large"` - - - `type: "web_search_tool_result_error"` - - - `"web_search_tool_result_error"` - - - `tool_use_id: string` - - - `type: "web_search_tool_result"` - - - `"web_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `WebFetchToolResultBlockParam = object { content, tool_use_id, type, 2 more }` - - - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` - - - `WebFetchToolResultErrorBlockParam = object { error_code, type }` - - - `error_code: WebFetchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"url_too_long"` - - - `"url_not_allowed"` - - - `"url_not_accessible"` - - - `"unsupported_content_type"` - - - `"too_many_requests"` - - - `"max_uses_exceeded"` - - - `"unavailable"` - - - `type: "web_fetch_tool_result_error"` - - - `"web_fetch_tool_result_error"` - - - `WebFetchBlockParam = object { content, type, url, retrieved_at }` - - - `content: DocumentBlockParam` - - - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` - - - `Base64PDFSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "application/pdf"` - - - `"application/pdf"` - - - `type: "base64"` - - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "text/plain"` - - - `"text/plain"` - - - `type: "text"` - - - `"text"` - - - `ContentBlockSource = object { content, type }` - - - `content: string or array of ContentBlockSourceContent` - - - `UnionMember0 = string` - - - `ContentBlockSourceContent = array of ContentBlockSourceContent` - - - `TextBlockParam = object { text, type, cache_control, citations }` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - - - `ImageBlockParam = object { source, type, cache_control }` - - - `source: Base64ImageSource or URLImageSource` - - - `Base64ImageSource = object { data, media_type, type }` - - - `data: string` - - - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - - - `"image/jpeg"` - - - `"image/png"` - - - `"image/gif"` - - - `"image/webp"` - - - `type: "base64"` - - - `"base64"` - - - `URLImageSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "image"` - - - `"image"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "content"` - - - `"content"` - - - `URLPDFSource = object { type, url }` - - - `type: "url"` - - - `"url"` - - - `url: string` - - - `type: "document"` - - - `"document"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - - `enabled: optional boolean` - - - `context: optional string` - - - `title: optional string` - - - `type: "web_fetch_result"` - - - `"web_fetch_result"` - - - `url: string` - - Fetched content URL - - - `retrieved_at: optional string` - - ISO 8601 timestamp when the content was retrieved - - - `tool_use_id: string` - - - `type: "web_fetch_tool_result"` - - - `"web_fetch_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - Tool invocation directly from the model. - - - `DirectCaller = object { type }` - - Tool invocation directly from the model. - - - `type: "direct"` - - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` - - Tool invocation generated by a server-side tool. - - - `tool_id: string` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` - - - `tool_id: string` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `CodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: CodeExecutionToolResultBlockParamContent` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `CodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: CodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "code_execution_tool_result_error"` - - - `"code_execution_tool_result_error"` - - - `CodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "code_execution_result"` - - - `"code_execution_result"` - - - `EncryptedCodeExecutionResultBlockParam = object { content, encrypted_stdout, return_code, 2 more }` - - Code execution result with encrypted stdout for PFC + web_search results. - - - `content: array of CodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "code_execution_output"` - - - `"code_execution_output"` - - - `encrypted_stdout: string` - - - `return_code: number` - - - `stderr: string` - - - `type: "encrypted_code_execution_result"` - - - `"encrypted_code_execution_result"` - - - `tool_use_id: string` - - - `type: "code_execution_tool_result"` - - - `"code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `BashCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` - - - `BashCodeExecutionToolResultErrorParam = object { error_code, type }` - - - `error_code: BashCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"output_file_too_large"` - - - `type: "bash_code_execution_tool_result_error"` - - - `"bash_code_execution_tool_result_error"` - - - `BashCodeExecutionResultBlockParam = object { content, return_code, stderr, 2 more }` - - - `content: array of BashCodeExecutionOutputBlockParam` - - - `file_id: string` - - - `type: "bash_code_execution_output"` - - - `"bash_code_execution_output"` - - - `return_code: number` - - - `stderr: string` - - - `stdout: string` - - - `type: "bash_code_execution_result"` - - - `"bash_code_execution_result"` - - - `tool_use_id: string` - - - `type: "bash_code_execution_tool_result"` - - - `"bash_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `TextEditorCodeExecutionToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` - - - `TextEditorCodeExecutionToolResultErrorParam = object { error_code, type, error_message }` - - - `error_code: TextEditorCodeExecutionToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `"file_not_found"` - - - `type: "text_editor_code_execution_tool_result_error"` - - - `"text_editor_code_execution_tool_result_error"` - - - `error_message: optional string` - - - `TextEditorCodeExecutionViewResultBlockParam = object { content, file_type, type, 3 more }` - - - `content: string` - - - `file_type: "text" or "image" or "pdf"` - - - `"text"` - - - `"image"` - - - `"pdf"` - - - `type: "text_editor_code_execution_view_result"` - - - `"text_editor_code_execution_view_result"` - - - `num_lines: optional number` - - - `start_line: optional number` - - - `total_lines: optional number` - - - `TextEditorCodeExecutionCreateResultBlockParam = object { is_file_update, type }` - - - `is_file_update: boolean` - - - `type: "text_editor_code_execution_create_result"` - - - `"text_editor_code_execution_create_result"` - - - `TextEditorCodeExecutionStrReplaceResultBlockParam = object { type, lines, new_lines, 3 more }` - - - `type: "text_editor_code_execution_str_replace_result"` - - - `"text_editor_code_execution_str_replace_result"` - - - `lines: optional array of string` - - - `new_lines: optional number` - - - `new_start: optional number` - - - `old_lines: optional number` - - - `old_start: optional number` - - - `tool_use_id: string` - - - `type: "text_editor_code_execution_tool_result"` - - - `"text_editor_code_execution_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ToolSearchToolResultBlockParam = object { content, tool_use_id, type, cache_control }` - - - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` - - - `ToolSearchToolResultErrorParam = object { error_code, type }` - - - `error_code: ToolSearchToolResultErrorCode` - - - `"invalid_tool_input"` - - - `"unavailable"` - - - `"too_many_requests"` - - - `"execution_time_exceeded"` - - - `type: "tool_search_tool_result_error"` - - - `"tool_search_tool_result_error"` - - - `ToolSearchToolSearchResultBlockParam = object { tool_references, type }` - - - `tool_references: array of ToolReferenceBlockParam` - - - `tool_name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `type: "tool_search_tool_search_result"` - - - `"tool_search_tool_search_result"` - - - `tool_use_id: string` - - - `type: "tool_search_tool_result"` - - - `"tool_search_tool_result"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `ContainerUploadBlockParam = object { file_id, type, cache_control }` - - A content block that represents a file to be uploaded to the container - Files uploaded via this block will be available in the container's input directory. - - - `file_id: string` - - - `type: "container_upload"` - - - `"container_upload"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `role: "user" or "assistant"` - - - `"user"` - - - `"assistant"` - -- `model: Model` +- `--model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--container: optional string` + + Container identifier for reuse across requests. + +- `--inference-geo: optional string` + + Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + +- `--metadata: optional object { user_id }` + + An object describing metadata about the request. + +- `--output-config: optional object { effort, format }` + + Configuration options for the model's output, such as the output format. + +- `--service-tier: optional "auto" or "standard_only"` + + Determines whether to use priority capacity (if available) or standard capacity for this request. + + Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. + +- `--stop-sequence: optional array of string` + + Custom text sequences that will cause the model to stop generating. + + Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. + + If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. + +- `--system: optional string or array of TextBlockParam` + + System prompt. + + A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). + +- `--temperature: optional number` + + Amount of randomness injected into the response. + + Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. + + Note that even with `temperature` of `0.0`, the results will not be fully deterministic. + +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + +- `--tool: optional array of ToolUnion` + + Definitions of tools that the model may use. + + If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. + + There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). + + Each tool definition includes: + + * `name`: Name of the tool. + * `description`: Optional, but strongly-recommended description of the tool. + * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. + + For example, if you defined `tools` as: + + ```json + [ + { + "name": "get_stock_price", + "description": "Get the current stock price for a given ticker symbol.", + "input_schema": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." + } + }, + "required": ["ticker"] + } + } + ] + ``` + + And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: + + ```json + [ + { + "type": "tool_use", + "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "name": "get_stock_price", + "input": { "ticker": "^GSPC" } + } + ] + ``` + + You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: + + ```json + [ + { + "type": "tool_result", + "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", + "content": "259.75 USD" + } + ] + ``` + + Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. + + See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. + +- `--top-k: optional number` + + Only sample from the top K options for each subsequent token. + + Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +- `--top-p: optional number` + + Use nucleus sampling. + + In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + + Recommended for advanced use cases only. You usually only need to use `temperature`. + +### Returns + +- `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` The model that will complete your prompt. @@ -2375,233 +894,235 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Fast and cost-effective model - - `UnionMember1 = string` + - `role: "assistant"` -- `cache_control: optional CacheControlEphemeral` + Conversational role of the generated message. - Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + This will always be `"assistant"`. - - `type: "ephemeral"` + - `stop_details: object { category, explanation, type }` - - `"ephemeral"` + Structured information about a refusal. - - `ttl: optional "5m" or "1h"` + - `category: "cyber" or "bio"` - The time-to-live for the cache control breakpoint. + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. This may be one the following values: - - `5m`: 5 minutes - - `1h`: 1 hour + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations - Defaults to `5m`. + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - - `"5m"` + - `"end_turn"` - - `"1h"` + - `"max_tokens"` -- `container: optional string` + - `"stop_sequence"` - Container identifier for reuse across requests. + - `"tool_use"` -- `inference_geo: optional string` + - `"pause_turn"` - Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. + - `"refusal"` -- `metadata: optional Metadata` + - `stop_sequence: string` - An object describing metadata about the request. + Which custom stop sequence was generated, if any. - - `user_id: optional string` + This value will be a non-null string if one of your custom stop sequences was generated. - An external identifier for the user who is associated with the request. + - `type: "message"` - This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + Object type. -- `output_config: optional OutputConfig` + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Example + +```cli +ant messages create \ + --api-key my-anthropic-api-key \ + --max-tokens 1024 \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` + +## Count Tokens + +`$ ant messages count-tokens` + +**post** `/v1/messages/count_tokens` + +Count the number of tokens in a Message. + +The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. + +Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) + +### Parameters + +- `--message: array of MessageParam` + + Input messages. + + Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. + + Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. + + If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. + + Example with a single `user` message: + + ```json + [{"role": "user", "content": "Hello, Claude"}] + ``` + + Example with multiple conversational turns: + + ```json + [ + {"role": "user", "content": "Hello there."}, + {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, + {"role": "user", "content": "Can you explain LLMs in plain English?"}, + ] + ``` + + Example with a partially-filled response from Claude: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("}, + ] + ``` + + Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: + + ```json + {"role": "user", "content": "Hello, Claude"} + ``` + + ```json + {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} + ``` + + See [input examples](https://docs.claude.com/en/api/messages-examples). + + Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. + + There is a limit of 100,000 messages in a single request. + +- `--model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + +- `--cache-control: optional object { type, ttl }` + + Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. + +- `--output-config: optional object { effort, format }` Configuration options for the model's output, such as the output format. - - `effort: optional "low" or "medium" or "high" or 2 more` - - All possible effort levels. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - - - `"max"` - - - `format: optional JSONOutputFormat` - - A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - - `schema: map[unknown]` - - The JSON schema of the format - - - `type: "json_schema"` - - - `"json_schema"` - -- `service_tier: optional "auto" or "standard_only"` - - Determines whether to use priority capacity (if available) or standard capacity for this request. - - Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - - - `"auto"` - - - `"standard_only"` - -- `stop_sequences: optional array of string` - - Custom text sequences that will cause the model to stop generating. - - Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. - - If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - -- `stream: optional boolean` - - Whether to incrementally stream the response using server-sent events. - - See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - -- `system: optional string or array of TextBlockParam` +- `--system: optional string or array of TextBlockParam` System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - - `UnionMember0 = string` - - - `UnionMember1 = array of TextBlockParam` - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional array of TextCitationParam` - - - `CitationCharLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_char_index: number` - - - `start_char_index: number` - - - `type: "char_location"` - - - `"char_location"` - - - `CitationPageLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_page_number: number` - - - `start_page_number: number` - - - `type: "page_location"` - - - `"page_location"` - - - `CitationContentBlockLocationParam = object { cited_text, document_index, document_title, 3 more }` - - - `cited_text: string` - - - `document_index: number` - - - `document_title: string` - - - `end_block_index: number` - - - `start_block_index: number` - - - `type: "content_block_location"` - - - `"content_block_location"` - - - `CitationWebSearchResultLocationParam = object { cited_text, encrypted_index, title, 2 more }` - - - `cited_text: string` - - - `encrypted_index: string` - - - `title: string` - - - `type: "web_search_result_location"` - - - `"web_search_result_location"` - - - `url: string` - - - `CitationSearchResultLocationParam = object { cited_text, end_block_index, search_result_index, 4 more }` - - - `cited_text: string` - - - `end_block_index: number` - - - `search_result_index: number` - - - `source: string` - - - `start_block_index: number` - - - `title: string` - - - `type: "search_result_location"` - - - `"search_result_location"` - -- `temperature: optional number` - - Amount of randomness injected into the response. - - Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. - - Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - -- `thinking: optional ThinkingConfigParam` +- `--thinking: optional ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` Configuration for enabling Claude's extended thinking. @@ -2609,107 +1130,11 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - `ThinkingConfigEnabled = object { budget_tokens, type, display }` - - - `budget_tokens: number` - - Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. - - Must be ≥1024 and less than `max_tokens`. - - See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - - - `type: "enabled"` - - - `"enabled"` - - - `display: optional "summarized" or "omitted"` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `"summarized"` - - - `"omitted"` - - - `ThinkingConfigDisabled = object { type }` - - - `type: "disabled"` - - - `"disabled"` - - - `ThinkingConfigAdaptive = object { type, display }` - - - `type: "adaptive"` - - - `"adaptive"` - - - `display: optional "summarized" or "omitted"` - - Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - - - `"summarized"` - - - `"omitted"` - -- `tool_choice: optional ToolChoice` +- `--tool-choice: optional ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - - `ToolChoiceAuto = object { type, disable_parallel_tool_use }` - - The model will automatically decide whether to use tools. - - - `type: "auto"` - - - `"auto"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output at most one tool use. - - - `ToolChoiceAny = object { type, disable_parallel_tool_use }` - - The model will use any available tools. - - - `type: "any"` - - - `"any"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceTool = object { name, type, disable_parallel_tool_use }` - - The model will use the specified tool with `tool_choice.name`. - - - `name: string` - - The name of the tool to use. - - - `type: "tool"` - - - `"tool"` - - - `disable_parallel_tool_use: optional boolean` - - Whether to disable parallel tool use. - - Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - - `ToolChoiceNone = object { type }` - - The model will not be allowed to use tools. - - - `type: "none"` - - - `"none"` - -- `tools: optional array of ToolUnion` +- `--tool: optional array of MessageCountTokensTool` Definitions of tools that the model may use. @@ -2773,650 +1198,1679 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - - `Tool = object { input_schema, name, allowed_callers, 7 more }` +### Returns - - `input_schema: object { type, properties, required }` +- `message_tokens_count: object { input_tokens }` - [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + - `input_tokens: number` - This defines the shape of the `input` that your tool accepts and that the model will produce. + The total number of tokens across the provided list of messages, system prompt, and tools. - - `type: "object"` +### Example - - `"object"` +```cli +ant messages count-tokens \ + --api-key my-anthropic-api-key \ + --message '{content: [{text: x, type: text}], role: user}' \ + --model claude-opus-4-6 +``` - - `properties: optional map[unknown]` +## Domain Types - - `required: optional array of string` +### Base64 Image Source + +- `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + +### Base64 PDF Source + +- `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + +### Bash Code Execution Output Block + +- `bash_code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Bash Code Execution Output Block Param + +- `bash_code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + +### Bash Code Execution Result Block + +- `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Bash Code Execution Result Block Param + +- `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + +### Bash Code Execution Tool Result Block + +- `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + +### Bash Code Execution Tool Result Block Param + +- `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Bash Code Execution Tool Result Error + +- `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Bash Code Execution Tool Result Error Code + +- `bash_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + +### Bash Code Execution Tool Result Error Param + +- `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + +### Cache Control Ephemeral + +- `cache_control_ephemeral: object { type, ttl }` + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Cache Creation + +- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + +### Citation Char Location + +- `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + +### Citation Char Location Param + +- `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + +### Citation Content Block Location + +- `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Citation Content Block Location Param + +- `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + +### Citation Page Location + +- `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + +### Citation Page Location Param + +- `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + +### Citation Search Result Location Param + +- `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Citation Web Search Result Location Param + +- `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Citations Config + +- `citations_config: object { enabled }` + + - `enabled: boolean` + +### Citations Config Param + +- `citations_config_param: object { enabled }` + + - `enabled: optional boolean` + +### Citations Delta + +- `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + +### Citations Search Result Location + +- `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Citations Web Search Result Location + +- `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + +### Code Execution Output Block + +- `code_execution_output_block: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Code Execution Output Block Param + +- `code_execution_output_block_param: object { file_id, type }` + + - `file_id: string` + + - `type: "code_execution_output"` + +### Code Execution Result Block + +- `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Code Execution Result Block Param + +- `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + +### Code Execution Tool 20250522 + +- `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool 20250825 + +- `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool 20260120 + +- `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Code Execution Tool Result Block + +- `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + +### Code Execution Tool Result Block Content + +- `code_execution_tool_result_block_content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Code Execution Tool Result Block Param + +- `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Code Execution Tool Result Block Param Content + +- `code_execution_tool_result_block_param_content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Code Execution Tool Result Error + +- `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Code Execution Tool Result Error Code + +- `code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Code Execution Tool Result Error Param + +- `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + +### Container + +- `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + +### Container Upload Block + +- `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Container Upload Block Param + +- `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Content Block + +- `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` - `name: string` - Name of the tool. + - `type: "tool_use"` - This is how the tool will be called by the model and in `tool_use` blocks. + - `server_tool_use_block: object { id, caller, input, 2 more }` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + - `id: string` - - `"direct"` + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - `"code_execution_20250825"` + Tool invocation directly from the model. - - `"code_execution_20260120"` + - `direct_caller: object { type }` - - `cache_control: optional CacheControlEphemeral` + Tool invocation directly from the model. - Create a cache control breakpoint at this content block. + - `type: "direct"` - - `type: "ephemeral"` + - `server_tool_caller: object { tool_id, type }` - - `"ephemeral"` + Tool invocation generated by a server-side tool. - - `ttl: optional "5m" or "1h"` + - `tool_id: string` - The time-to-live for the cache control breakpoint. + - `type: "code_execution_20250825"` - This may be one the following values: + - `server_tool_caller_20260120: object { tool_id, type }` - - `5m`: 5 minutes - - `1h`: 1 hour + - `tool_id: string` - Defaults to `5m`. + - `type: "code_execution_20260120"` - - `"5m"` + - `input: map[unknown]` - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `description: optional string` - - Description of what this tool does. - - Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - - - `eager_input_streaming: optional boolean` - - Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `type: optional "custom"` - - - `"custom"` - - - `ToolBash20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "bash"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"bash"` - - - `type: "bash_20250124"` - - - `"bash_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250522 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250522"` - - - `"code_execution_20250522"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20250825 = object { name, type, allowed_callers, 3 more }` - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20250825"` - - - `"code_execution_20250825"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `CodeExecutionTool20260120 = object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20260120"` - - - `"code_execution_20260120"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `MemoryTool20250818 = object { name, type, allowed_callers, 4 more }` - - - `name: "memory"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"memory"` - - - `type: "memory_20250818"` - - - `"memory_20250818"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250124 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_editor"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_editor"` - - - `type: "text_editor_20250124"` - - - `"text_editor_20250124"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250429 = object { name, type, allowed_callers, 4 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250429"` - - - `"text_editor_20250429"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolTextEditor20250728 = object { name, type, allowed_callers, 5 more }` - - - `name: "str_replace_based_edit_tool"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"str_replace_based_edit_tool"` - - - `type: "text_editor_20250728"` - - - `"text_editor_20250728"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `input_examples: optional array of map[unknown]` - - - `max_characters: optional number` - - Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebSearchTool20250305 = object { name, type, allowed_callers, 7 more }` - - - `name: "web_search"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - `"web_search"` - - `type: "web_search_20250305"` - - - `"web_search_20250305"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20250910 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20250910"` + - `"code_execution"` - - `"web_fetch_20250910"` + - `"bash_code_execution"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + - `"text_editor_code_execution"` - - `"direct"` + - `"tool_search_tool_regex"` - - `"code_execution_20250825"` + - `"tool_search_tool_bm25"` - - `"code_execution_20260120"` + - `type: "server_tool_use"` - - `allowed_domains: optional array of string` + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` - List of domains to allow fetching from + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` - - `blocked_domains: optional array of string` + Tool invocation directly from the model. - List of domains to block fetching from + - `direct_caller: object { type }` - - `cache_control: optional CacheControlEphemeral` + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + +### Content Block Param + +- `content_block_param: TextBlockParam or ImageBlockParam or DocumentBlockParam or 13 more` + + Regular text content. + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - - `"ephemeral"` - - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. @@ -3432,360 +2886,1128 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"1h"` - - `citations: optional CitationsConfigParam` + - `citations: optional array of TextCitationParam` - Citations configuration for fetched documents. Citations are disabled by default. + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` - `enabled: optional boolean` - - `defer_loading: optional boolean` + - `context: optional string` - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + - `title: optional string` - - `max_content_tokens: optional number` + - `search_result_block_param: object { content, source, title, 3 more }` - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + - `content: array of TextBlockParam` - - `max_uses: optional number` + - `text: string` - Maximum number of times the tool can be used in the API request. + - `type: "text"` - - `strict: optional boolean` + - `cache_control: optional object { type, ttl }` - When true, guarantees schema validation on tool names and inputs + Create a cache control breakpoint at this content block. - - `WebSearchTool20260209 = object { name, type, allowed_callers, 7 more }` + - `type: "ephemeral"` - - `name: "web_search"` + - `ttl: optional "5m" or "1h"` - Name of the tool. + The time-to-live for the cache control breakpoint. - This is how the tool will be called by the model and in `tool_use` blocks. + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` - `"web_search"` - - `type: "web_search_20260209"` - - - `"web_search_20260209"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - - - `blocked_domains: optional array of string` - - If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `user_location: optional UserLocation` - - Parameters for the user's location. Used to provide more relevant search results. - - - `type: "approximate"` - - - `"approximate"` - - - `city: optional string` - - The city of the user. - - - `country: optional string` - - The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - - - `region: optional string` - - The region of the user. - - - `timezone: optional string` - - The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - - `WebFetchTool20260209 = object { name, type, allowed_callers, 8 more }` - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20260209"` + - `"code_execution"` - - `"web_fetch_20260209"` + - `"bash_code_execution"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `WebFetchTool20260309 = object { name, type, allowed_callers, 9 more }` - - Web fetch tool with use_cache parameter for bypassing cached content. - - - `name: "web_fetch"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"web_fetch"` - - - `type: "web_fetch_20260309"` - - - `"web_fetch_20260309"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `allowed_domains: optional array of string` - - List of domains to allow fetching from - - - `blocked_domains: optional array of string` - - List of domains to block fetching from - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `citations: optional CitationsConfigParam` - - Citations configuration for fetched documents. Citations are disabled by default. - - - `enabled: optional boolean` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `max_content_tokens: optional number` - - Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - - - `max_uses: optional number` - - Maximum number of times the tool can be used in the API request. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `use_cache: optional boolean` - - Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - - `ToolSearchToolBm25_20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_bm25"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"tool_search_tool_bm25"` - - - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - - - `"tool_search_tool_bm25_20251119"` - - - `"tool_search_tool_bm25"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` - - Create a cache control breakpoint at this content block. - - - `type: "ephemeral"` - - - `"ephemeral"` - - - `ttl: optional "5m" or "1h"` - - The time-to-live for the cache control breakpoint. - - This may be one the following values: - - - `5m`: 5 minutes - - `1h`: 1 hour - - Defaults to `5m`. - - - `"5m"` - - - `"1h"` - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `ToolSearchToolRegex20251119 = object { name, type, allowed_callers, 3 more }` - - - `name: "tool_search_tool_regex"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. + - `"text_editor_code_execution"` - `"tool_search_tool_regex"` - - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + - `"tool_search_tool_bm25"` - - `"tool_search_tool_regex_20251119"` + - `type: "server_tool_use"` - - `"tool_search_tool_regex"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `cache_control: optional CacheControlEphemeral` + - `cache_control: optional object { type, ttl }` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - - `"ephemeral"` - - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. @@ -3801,33 +4023,1480 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `"1h"` - - `defer_loading: optional boolean` + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + Tool invocation directly from the model. - - `strict: optional boolean` + - `direct_caller: object { type }` - When true, guarantees schema validation on tool names and inputs + Tool invocation directly from the model. -- `top_k: optional number` + - `type: "direct"` - Only sample from the top K options for each subsequent token. + - `server_tool_caller: object { tool_id, type }` - Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). + Tool invocation generated by a server-side tool. - Recommended for advanced use cases only. You usually only need to use `temperature`. + - `tool_id: string` -- `top_p: optional number` + - `type: "code_execution_20250825"` - Use nucleus sampling. + - `server_tool_caller_20260120: object { tool_id, type }` - In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. + - `tool_id: string` - Recommended for advanced use cases only. You usually only need to use `temperature`. + - `type: "code_execution_20260120"` -### Returns + - `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` -- `Message = object { id, container, content, 7 more }` + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Content Block Source + +- `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + +### Content Block Source Content + +- `content_block_source_content: TextBlockParam or ImageBlockParam` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Direct Caller + +- `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + +### Document Block + +- `document_block: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + +### Document Block Param + +- `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + +### Encrypted Code Execution Result Block + +- `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Encrypted Code Execution Result Block Param + +- `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + +### Image Block Param + +- `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Input JSON Delta + +- `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + +### JSON Output Format + +- `json_output_format: object { schema, type }` + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Memory Tool 20250818 + +- `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Message + +- `message: object { id, container, content, 7 more }` - `id: string` @@ -3835,7 +5504,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en The format and length of IDs may change over time. - - `container: Container` + - `container: object { id, expires_at }` Information about the container used in the request (for the code execution tool) @@ -3876,7 +5545,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en [{"type": "text", "text": "B)"}] ``` - - `TextBlock = object { citations, text, type }` + - `text_block: object { citations, text, type }` - `citations: array of TextCitation` @@ -3884,7 +5553,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. - - `CitationCharLocation = object { cited_text, document_index, document_title, 4 more }` + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` - `cited_text: string` @@ -3900,9 +5569,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "char_location"` - - `"char_location"` - - - `CitationPageLocation = object { cited_text, document_index, document_title, 4 more }` + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` - `cited_text: string` @@ -3918,9 +5585,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "page_location"` - - `"page_location"` - - - `CitationContentBlockLocation = object { cited_text, document_index, document_title, 4 more }` + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` - `cited_text: string` @@ -3936,9 +5601,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "content_block_location"` - - `"content_block_location"` - - - `CitationsWebSearchResultLocation = object { cited_text, encrypted_index, title, 2 more }` + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` - `cited_text: string` @@ -3948,11 +5611,9 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "web_search_result_location"` - - `"web_search_result_location"` - - `url: string` - - `CitationsSearchResultLocation = object { cited_text, end_block_index, search_result_index, 4 more }` + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` - `cited_text: string` @@ -3968,15 +5629,11 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "search_result_location"` - - `"search_result_location"` - - `text: string` - `type: "text"` - - `"text"` - - - `ThinkingBlock = object { signature, thinking, type }` + - `thinking_block: object { signature, thinking, type }` - `signature: string` @@ -3984,17 +5641,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "thinking"` - - `"thinking"` - - - `RedactedThinkingBlock = object { data, type }` + - `redacted_thinking_block: object { data, type }` - `data: string` - `type: "redacted_thinking"` - - `"redacted_thinking"` - - - `ToolUseBlock = object { id, caller, input, 2 more }` + - `tool_use_block: object { id, caller, input, 2 more }` - `id: string` @@ -4002,15 +5655,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Tool invocation directly from the model. - - `DirectCaller = object { type }` + - `direct_caller: object { type }` Tool invocation directly from the model. - `type: "direct"` - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` + - `server_tool_caller: object { tool_id, type }` Tool invocation generated by a server-side tool. @@ -4018,25 +5669,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_20250825"` - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` + - `server_tool_caller_20260120: object { tool_id, type }` - `tool_id: string` - `type: "code_execution_20260120"` - - `"code_execution_20260120"` - - `input: map[unknown]` - `name: string` - `type: "tool_use"` - - `"tool_use"` - - - `ServerToolUseBlock = object { id, caller, input, 2 more }` + - `server_tool_use_block: object { id, caller, input, 2 more }` - `id: string` @@ -4044,15 +5689,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Tool invocation directly from the model. - - `DirectCaller = object { type }` + - `direct_caller: object { type }` Tool invocation directly from the model. - `type: "direct"` - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` + - `server_tool_caller: object { tool_id, type }` Tool invocation generated by a server-side tool. @@ -4060,16 +5703,12 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_20250825"` - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` + - `server_tool_caller_20260120: object { tool_id, type }` - `tool_id: string` - `type: "code_execution_20260120"` - - `"code_execution_20260120"` - - `input: map[unknown]` - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` @@ -4090,23 +5729,19 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "server_tool_use"` - - `"server_tool_use"` - - - `WebSearchToolResultBlock = object { caller, content, tool_use_id, type }` + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` Tool invocation directly from the model. - - `DirectCaller = object { type }` + - `direct_caller: object { type }` Tool invocation directly from the model. - `type: "direct"` - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` + - `server_tool_caller: object { tool_id, type }` Tool invocation generated by a server-side tool. @@ -4114,21 +5749,17 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_20250825"` - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` + - `server_tool_caller_20260120: object { tool_id, type }` - `tool_id: string` - `type: "code_execution_20260120"` - - `"code_execution_20260120"` + - `content: WebSearchToolResultError or array of WebSearchResultBlock` - - `content: WebSearchToolResultBlockContent` + - `web_search_tool_result_error: object { error_code, type }` - - `WebSearchToolResultError = object { error_code, type }` - - - `error_code: WebSearchToolResultErrorCode` + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` - `"invalid_tool_input"` @@ -4144,9 +5775,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "web_search_tool_result_error"` - - `"web_search_tool_result_error"` - - - `UnionMember1 = array of WebSearchResultBlock` + - `union_member_1: array of WebSearchResultBlock` - `encrypted_content: string` @@ -4156,31 +5785,25 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "web_search_result"` - - `"web_search_result"` - - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - - `"web_search_tool_result"` - - - `WebFetchToolResultBlock = object { caller, content, tool_use_id, type }` + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` Tool invocation directly from the model. - - `DirectCaller = object { type }` + - `direct_caller: object { type }` Tool invocation directly from the model. - `type: "direct"` - - `"direct"` - - - `ServerToolCaller = object { tool_id, type }` + - `server_tool_caller: object { tool_id, type }` Tool invocation generated by a server-side tool. @@ -4188,21 +5811,17 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_20250825"` - - `"code_execution_20250825"` - - - `ServerToolCaller20260120 = object { tool_id, type }` + - `server_tool_caller_20260120: object { tool_id, type }` - `tool_id: string` - `type: "code_execution_20260120"` - - `"code_execution_20260120"` - - `content: WebFetchToolResultErrorBlock or WebFetchBlock` - - `WebFetchToolResultErrorBlock = object { error_code, type }` + - `web_fetch_tool_result_error_block: object { error_code, type }` - - `error_code: WebFetchToolResultErrorCode` + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` - `"invalid_tool_input"` @@ -4222,13 +5841,11 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "web_fetch_tool_result_error"` - - `"web_fetch_tool_result_error"` + - `web_fetch_block: object { content, retrieved_at, type, url }` - - `WebFetchBlock = object { content, retrieved_at, type, url }` + - `content: object { citations, source, title, type }` - - `content: DocumentBlock` - - - `citations: CitationsConfig` + - `citations: object { enabled }` Citation configuration for the document @@ -4236,46 +5853,34 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `source: Base64PDFSource or PlainTextSource` - - `Base64PDFSource = object { data, media_type, type }` + - `base64_pdf_source: object { data, media_type, type }` - `data: string` - `media_type: "application/pdf"` - - `"application/pdf"` - - `type: "base64"` - - `"base64"` - - - `PlainTextSource = object { data, media_type, type }` + - `plain_text_source: object { data, media_type, type }` - `data: string` - `media_type: "text/plain"` - - `"text/plain"` - - `type: "text"` - - `"text"` - - `title: string` The title of the document - `type: "document"` - - `"document"` - - `retrieved_at: string` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - - `"web_fetch_result"` - - `url: string` Fetched content URL @@ -4284,17 +5889,15 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "web_fetch_tool_result"` - - `"web_fetch_tool_result"` + - `code_execution_tool_result_block: object { content, tool_use_id, type }` - - `CodeExecutionToolResultBlock = object { content, tool_use_id, type }` - - - `content: CodeExecutionToolResultBlockContent` + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - - `CodeExecutionToolResultError = object { error_code, type }` + - `code_execution_tool_result_error: object { error_code, type }` - - `error_code: CodeExecutionToolResultErrorCode` + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` @@ -4306,9 +5909,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_tool_result_error"` - - `"code_execution_tool_result_error"` - - - `CodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` - `content: array of CodeExecutionOutputBlock` @@ -4316,8 +5917,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_output"` - - `"code_execution_output"` - - `return_code: number` - `stderr: string` @@ -4326,9 +5925,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_result"` - - `"code_execution_result"` - - - `EncryptedCodeExecutionResultBlock = object { content, encrypted_stdout, return_code, 2 more }` + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` Code execution result with encrypted stdout for PFC + web_search results. @@ -4338,8 +5935,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "code_execution_output"` - - `"code_execution_output"` - - `encrypted_stdout: string` - `return_code: number` @@ -4348,21 +5943,17 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "encrypted_code_execution_result"` - - `"encrypted_code_execution_result"` - - `tool_use_id: string` - `type: "code_execution_tool_result"` - - `"code_execution_tool_result"` - - - `BashCodeExecutionToolResultBlock = object { content, tool_use_id, type }` + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` - - `BashCodeExecutionToolResultError = object { error_code, type }` + - `bash_code_execution_tool_result_error: object { error_code, type }` - - `error_code: BashCodeExecutionToolResultErrorCode` + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` @@ -4376,9 +5967,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "bash_code_execution_tool_result_error"` - - `"bash_code_execution_tool_result_error"` - - - `BashCodeExecutionResultBlock = object { content, return_code, stderr, 2 more }` + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` - `content: array of BashCodeExecutionOutputBlock` @@ -4386,8 +5975,6 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "bash_code_execution_output"` - - `"bash_code_execution_output"` - - `return_code: number` - `stderr: string` @@ -4396,21 +5983,17 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "bash_code_execution_result"` - - `"bash_code_execution_result"` - - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - - `"bash_code_execution_tool_result"` - - - `TextEditorCodeExecutionToolResultBlock = object { content, tool_use_id, type }` + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` - - `TextEditorCodeExecutionToolResultError = object { error_code, error_message, type }` + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` - - `error_code: TextEditorCodeExecutionToolResultErrorCode` + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` @@ -4426,9 +6009,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "text_editor_code_execution_tool_result_error"` - - `"text_editor_code_execution_tool_result_error"` - - - `TextEditorCodeExecutionViewResultBlock = object { content, file_type, num_lines, 3 more }` + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` - `content: string` @@ -4448,17 +6029,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "text_editor_code_execution_view_result"` - - `"text_editor_code_execution_view_result"` - - - `TextEditorCodeExecutionCreateResultBlock = object { is_file_update, type }` + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - - `"text_editor_code_execution_create_result"` - - - `TextEditorCodeExecutionStrReplaceResultBlock = object { lines, new_lines, new_start, 3 more }` + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` - `lines: array of string` @@ -4472,21 +6049,17 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "text_editor_code_execution_str_replace_result"` - - `"text_editor_code_execution_str_replace_result"` - - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - - `"text_editor_code_execution_tool_result"` - - - `ToolSearchToolResultBlock = object { content, tool_use_id, type }` + - `tool_search_tool_result_block: object { content, tool_use_id, type }` - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` - - `ToolSearchToolResultError = object { error_code, error_message, type }` + - `tool_search_tool_result_error: object { error_code, error_message, type }` - - `error_code: ToolSearchToolResultErrorCode` + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` @@ -4500,9 +6073,7 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "tool_search_tool_result_error"` - - `"tool_search_tool_result_error"` - - - `ToolSearchToolSearchResultBlock = object { tool_references, type }` + - `tool_search_tool_search_result_block: object { tool_references, type }` - `tool_references: array of ToolReferenceBlock` @@ -4510,19 +6081,13 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "tool_reference"` - - `"tool_reference"` - - `type: "tool_search_tool_search_result"` - - `"tool_search_tool_search_result"` - - `tool_use_id: string` - `type: "tool_search_tool_result"` - - `"tool_search_tool_result"` - - - `ContainerUploadBlock = object { file_id, type }` + - `container_upload_block: object { file_id, type }` Response model for a file uploaded to the container. @@ -4530,15 +6095,4663 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en - `type: "container_upload"` - - `"container_upload"` - - - `model: Model` + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - - `UnionMember0 = "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more` + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### Message Count Tokens Tool + +- `message_count_tokens_tool: Tool or ToolBash20250124 or CodeExecutionTool20250522 or 13 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Message Delta Usage + +- `message_delta_usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Message Param + +- `message_param: object { content, role }` + + - `content: array of ContentBlockParam` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + + - `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: CodeExecutionToolResultErrorParam or CodeExecutionResultBlockParam or EncryptedCodeExecutionResultBlockParam` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block_param: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `bash_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam` + + - `bash_code_execution_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block_param: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlockParam` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `container_upload_block_param: object { file_id, type, cache_control }` + + A content block that represents a file to be uploaded to the container + Files uploaded via this block will be available in the container's input directory. + + - `file_id: string` + + - `type: "container_upload"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `role: "user" or "assistant"` + + - `"user"` + + - `"assistant"` + +### Message Tokens Count + +- `message_tokens_count: object { input_tokens }` + + - `input_tokens: number` + + The total number of tokens across the provided list of messages, system prompt, and tools. + +### Metadata + +- `metadata: object { user_id }` + + - `user_id: optional string` + + An external identifier for the user who is associated with the request. + + This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. + +### Output Config + +- `output_config: object { effort, format }` + + - `effort: optional "low" or "medium" or "high" or 2 more` + + All possible effort levels. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `format: optional object { schema, type }` + + A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + - `schema: map[unknown]` + + The JSON schema of the format + + - `type: "json_schema"` + +### Plain Text Source + +- `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + +### Raw Content Block Delta + +- `raw_content_block_delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Raw Content Block Delta Event + +- `raw_content_block_delta_event: object { delta, index, type }` + + - `delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `index: number` + + - `type: "content_block_delta"` + +### Raw Content Block Start Event + +- `raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `index: number` + + - `type: "content_block_start"` + +### Raw Content Block Stop Event + +- `raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Raw Message Delta Event + +- `raw_message_delta_event: object { delta, type, usage }` + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Raw Message Start Event + +- `raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` The model that will complete your prompt. @@ -4612,163 +10825,10989 @@ Learn more about the Messages API in our [user guide](https://docs.claude.com/en Fast and cost-effective model - - `UnionMember1 = string` + - `role: "assistant"` - - `role: "assistant"` + Conversational role of the generated message. - Conversational role of the generated message. + This will always be `"assistant"`. - This will always be `"assistant"`. + - `stop_details: object { category, explanation, type }` - - `"assistant"` + Structured information about a refusal. - - `stop_details: RefusalStopDetails` + - `category: "cyber" or "bio"` - Structured information about a refusal. + The policy category that triggered the refusal. - - `category: "cyber" or "bio"` + `null` when the refusal doesn't map to a named category. - The policy category that triggered the refusal. + - `"cyber"` - `null` when the refusal doesn't map to a named category. + - `"bio"` - - `"cyber"` + - `explanation: string` - - `"bio"` + Human-readable explanation of the refusal. - - `explanation: string` + This text is not guaranteed to be stable. `null` when no explanation is available for the category. - Human-readable explanation of the refusal. + - `type: "refusal"` - This text is not guaranteed to be stable. `null` when no explanation is available for the category. + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` - - `type: "refusal"` + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` - `"refusal"` - - `stop_reason: StopReason` + - `stop_sequence: string` - The reason that we stopped. + Which custom stop sequence was generated, if any. - This may be one the following values: + This value will be a non-null string if one of your custom stop sequences was generated. - * `"end_turn"`: the model reached a natural stopping point - * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum - * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated - * `"tool_use"`: the model invoked one or more tools - * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. - * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + - `type: "message"` - In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + Object type. - - `"end_turn"` + For Messages, this is always `"message"`. - - `"max_tokens"` + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` - - `"stop_sequence"` + Billing and rate-limit usage. - - `"tool_use"` + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - `"pause_turn"` + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - `"refusal"` + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - `stop_sequence: string` + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - Which custom stop sequence was generated, if any. + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` - This value will be a non-null string if one of your custom stop sequences was generated. + Breakdown of cached tokens by TTL - - `type: "message"` + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "message_start"` + +### Raw Message Stop Event + +- `raw_message_stop_event: object { type }` + + - `type: "message_stop"` + +### Raw Message Stream Event + +- `raw_message_stream_event: RawMessageStartEvent or RawMessageDeltaEvent or RawMessageStopEvent or 3 more` + + - `raw_message_start_event: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "message_start"` + + - `raw_message_delta_event: object { delta, type, usage }` + + - `delta: object { container, stop_details, stop_reason, stop_sequence }` + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + - `type: "message_delta"` + + - `usage: object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation_input_tokens: number` + + The cumulative number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The cumulative number of input tokens read from the cache. + + - `input_tokens: number` + + The cumulative number of input tokens which were used. + + - `output_tokens: number` + + The cumulative number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `raw_message_stop_event: object { type }` + + - `type: "message_stop"` + + - `raw_content_block_start_event: object { content_block, index, type }` + + - `content_block: TextBlock or ThinkingBlock or RedactedThinkingBlock or 9 more` + + Response model for a file uploaded to the container. + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `index: number` + + - `type: "content_block_start"` + + - `raw_content_block_delta_event: object { delta, index, type }` + + - `delta: TextDelta or InputJSONDelta or CitationsDelta or 2 more` + + - `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + + - `input_json_delta: object { partial_json, type }` + + - `partial_json: string` + + - `type: "input_json_delta"` + + - `citations_delta: object { citation, type }` + + - `citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `type: "citations_delta"` + + - `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + + - `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + + - `index: number` + + - `type: "content_block_delta"` + + - `raw_content_block_stop_event: object { index, type }` + + - `index: number` + + - `type: "content_block_stop"` + +### Redacted Thinking Block + +- `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Redacted Thinking Block Param + +- `redacted_thinking_block_param: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + +### Refusal Stop Details + +- `refusal_stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + +### Search Result Block Param + +- `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + +### Server Tool Caller + +- `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + +### Server Tool Caller 20260120 + +- `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Server Tool Usage + +- `server_tool_usage: object { web_fetch_requests, web_search_requests }` + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + +### Server Tool Use Block + +- `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + +### Server Tool Use Block Param + +- `server_tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Signature Delta + +- `signature_delta: object { signature, type }` + + - `signature: string` + + - `type: "signature_delta"` + +### Stop Reason + +- `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + +### Text Block + +- `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + +### Text Block Param + +- `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Citation + +- `text_citation: CitationCharLocation or CitationPageLocation or CitationContentBlockLocation or 2 more` + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Citation Param + +- `text_citation_param: CitationCharLocationParam or CitationPageLocationParam or CitationContentBlockLocationParam or 2 more` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + +### Text Delta + +- `text_delta: object { text, type }` + + - `text: string` + + - `type: "text_delta"` + +### Text Editor Code Execution Create Result Block + +- `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Text Editor Code Execution Create Result Block Param + +- `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + +### Text Editor Code Execution Str Replace Result Block + +- `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + +### Text Editor Code Execution Str Replace Result Block Param + +- `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + +### Text Editor Code Execution Tool Result Block + +- `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + +### Text Editor Code Execution Tool Result Block Param + +- `text_editor_code_execution_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam` + + - `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + + - `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + + - `text_editor_code_execution_create_result_block_param: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block_param: object { type, lines, new_lines, 3 more }` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `lines: optional array of string` + + - `new_lines: optional number` + + - `new_start: optional number` + + - `old_lines: optional number` + + - `old_start: optional number` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Text Editor Code Execution Tool Result Error + +- `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + +### Text Editor Code Execution Tool Result Error Code + +- `text_editor_code_execution_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + +### Text Editor Code Execution Tool Result Error Param + +- `text_editor_code_execution_tool_result_error_param: object { error_code, type, error_message }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `error_message: optional string` + +### Text Editor Code Execution View Result Block + +- `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + +### Text Editor Code Execution View Result Block Param + +- `text_editor_code_execution_view_result_block_param: object { content, file_type, type, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `type: "text_editor_code_execution_view_result"` + + - `num_lines: optional number` + + - `start_line: optional number` + + - `total_lines: optional number` + +### Thinking Block + +- `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Thinking Block Param + +- `thinking_block_param: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + +### Thinking Config Adaptive + +- `thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Config Disabled + +- `thinking_config_disabled: object { type }` + + - `type: "disabled"` + +### Thinking Config Enabled + +- `thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Config Param + +- `thinking_config_param: ThinkingConfigEnabled or ThinkingConfigDisabled or ThinkingConfigAdaptive` + + Configuration for enabling Claude's extended thinking. + + When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `thinking_config_enabled: object { budget_tokens, type, display }` + + - `budget_tokens: number` + + Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. + + Must be ≥1024 and less than `max_tokens`. + + See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. + + - `type: "enabled"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + + - `thinking_config_disabled: object { type }` + + - `type: "disabled"` + + - `thinking_config_adaptive: object { type, display }` + + - `type: "adaptive"` + + - `display: optional "summarized" or "omitted"` + + Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. + + - `"summarized"` + + - `"omitted"` + +### Thinking Delta + +- `thinking_delta: object { thinking, type }` + + - `thinking: string` + + - `type: "thinking_delta"` + +### Tool + +- `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + +### Tool Bash 20250124 + +- `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Choice + +- `tool_choice: ToolChoiceAuto or ToolChoiceAny or ToolChoiceTool or ToolChoiceNone` + + How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. + + - `tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + + - `tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + + - `tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Tool Choice Any + +- `tool_choice_any: object { type, disable_parallel_tool_use }` + + The model will use any available tools. + + - `type: "any"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Tool Choice Auto + +- `tool_choice_auto: object { type, disable_parallel_tool_use }` + + The model will automatically decide whether to use tools. + + - `type: "auto"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output at most one tool use. + +### Tool Choice None + +- `tool_choice_none: object { type }` + + The model will not be allowed to use tools. + + - `type: "none"` + +### Tool Choice Tool + +- `tool_choice_tool: object { name, type, disable_parallel_tool_use }` + + The model will use the specified tool with `tool_choice.name`. + + - `name: string` + + The name of the tool to use. + + - `type: "tool"` + + - `disable_parallel_tool_use: optional boolean` + + Whether to disable parallel tool use. + + Defaults to `false`. If set to `true`, the model will output exactly one tool use. + +### Tool Reference Block + +- `tool_reference_block: object { tool_name, type }` + + - `tool_name: string` + + - `type: "tool_reference"` + +### Tool Reference Block Param + +- `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Tool Result Block Param + +- `tool_result_block_param: object { tool_use_id, type, cache_control, 2 more }` + + - `tool_use_id: string` + + - `type: "tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `content: optional array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `search_result_block_param: object { content, source, title, 3 more }` + + - `content: array of TextBlockParam` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `source: string` + + - `title: string` + + - `type: "search_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `document_block_param: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `tool_reference_block_param: object { tool_name, type, cache_control }` + + Tool reference block that can be included in tool_result content. + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `is_error: optional boolean` + +### Tool Search Tool Bm25 20251119 + +- `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Search Tool Regex 20251119 + +- `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Search Tool Result Block + +- `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + +### Tool Search Tool Result Block Param + +- `tool_search_tool_result_block_param: object { content, tool_use_id, type, cache_control }` + + - `content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam` + + - `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + +### Tool Search Tool Result Error + +- `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + +### Tool Search Tool Result Error Code + +- `tool_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + +### Tool Search Tool Result Error Param + +- `tool_search_tool_result_error_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "tool_search_tool_result_error"` + +### Tool Search Tool Search Result Block + +- `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + +### Tool Search Tool Search Result Block Param + +- `tool_search_tool_search_result_block_param: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlockParam` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "tool_search_tool_search_result"` + +### Tool Text Editor 20250124 + +- `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Text Editor 20250429 + +- `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Text Editor 20250728 + +- `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Union + +- `tool_union: Tool or ToolBash20250124 or CodeExecutionTool20250522 or 13 more` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `tool: object { input_schema, name, allowed_callers, 7 more }` + + - `input_schema: object { type, properties, required }` + + [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. + + This defines the shape of the `input` that your tool accepts and that the model will produce. + + - `type: "object"` + + - `properties: optional map[unknown]` + + - `required: optional array of string` + + - `name: string` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `description: optional string` + + Description of what this tool does. + + Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. + + - `eager_input_streaming: optional boolean` + + Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `type: optional "custom"` + + - `"custom"` + + - `tool_bash_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "bash"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "bash_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250522: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250522"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20250825: object { name, type, allowed_callers, 3 more }` + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20250825"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `code_execution_tool_20260120: object { name, type, allowed_callers, 3 more }` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `memory_tool_20250818: object { name, type, allowed_callers, 4 more }` + + - `name: "memory"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "memory_20250818"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250124: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_editor"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250124"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250429: object { name, type, allowed_callers, 4 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250429"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_text_editor_20250728: object { name, type, allowed_callers, 5 more }` + + - `name: "str_replace_based_edit_tool"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "text_editor_20250728"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `input_examples: optional array of map[unknown]` + + - `max_characters: optional number` + + Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + + - `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + + - `tool_search_tool_bm25_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_bm25"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + + - `"tool_search_tool_bm25"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `tool_search_tool_regex_20251119: object { name, type, allowed_callers, 3 more }` + + - `name: "tool_search_tool_regex"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + + - `"tool_search_tool_regex"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Tool Use Block + +- `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + +### Tool Use Block Param + +- `tool_use_block_param: object { id, input, name, 3 more }` + + - `id: string` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### URL Image Source + +- `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### URL PDF Source + +- `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + +### Usage + +- `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + +### User Location + +- `user_location: object { type, city, country, 2 more }` + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Fetch Block + +- `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + +### Web Fetch Block Param + +- `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + +### Web Fetch Tool 20250910 + +- `web_fetch_tool_20250910: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20250910"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Web Fetch Tool 20260209 + +- `web_fetch_tool_20260209: object { name, type, allowed_callers, 8 more }` + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + +### Web Fetch Tool 20260309 + +- `web_fetch_tool_20260309: object { name, type, allowed_callers, 9 more }` + + Web fetch tool with use_cache parameter for bypassing cached content. + + - `name: "web_fetch"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_fetch_20260309"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + List of domains to allow fetching from + + - `blocked_domains: optional array of string` + + List of domains to block fetching from + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + Citations configuration for fetched documents. Citations are disabled by default. + + - `enabled: optional boolean` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_content_tokens: optional number` + + Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `use_cache: optional boolean` + + Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. + +### Web Fetch Tool Result Block + +- `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + +### Web Fetch Tool Result Block Param + +- `web_fetch_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam` + + - `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block_param: object { content, type, url, retrieved_at }` + + - `content: object { source, type, cache_control, 3 more }` + + - `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `content_block_source: object { content, type }` + + - `content: string or array of ContentBlockSourceContent` + + - `union_member_0: string` + + - `content_block_source_content: array of ContentBlockSourceContent` + + - `text_block_param: object { text, type, cache_control, citations }` + + - `text: string` + + - `type: "text"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional array of TextCitationParam` + + - `citation_char_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location_param: object { cited_text, document_index, document_title, 3 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citation_web_search_result_location_param: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citation_search_result_location_param: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `image_block_param: object { source, type, cache_control }` + + - `source: Base64ImageSource or URLImageSource` + + - `base64_image_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` + + - `"image/jpeg"` + + - `"image/png"` + + - `"image/gif"` + + - `"image/webp"` + + - `type: "base64"` + + - `url_image_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "image"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `type: "content"` + + - `url_pdf_source: object { type, url }` + + - `type: "url"` + + - `url: string` + + - `type: "document"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `citations: optional object { enabled }` + + - `enabled: optional boolean` + + - `context: optional string` + + - `title: optional string` + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `retrieved_at: optional string` + + ISO 8601 timestamp when the content was retrieved + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Web Fetch Tool Result Error Block + +- `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Web Fetch Tool Result Error Block Param + +- `web_fetch_tool_result_error_block_param: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + +### Web Fetch Tool Result Error Code + +- `web_fetch_tool_result_error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + +### Web Search Result Block + +- `web_search_result_block: object { encrypted_content, page_age, title, 2 more }` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Web Search Result Block Param + +- `web_search_result_block_param: object { encrypted_content, title, type, 2 more }` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + +### Web Search Tool 20250305 + +- `web_search_tool_20250305: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20250305"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Search Tool 20260209 + +- `web_search_tool_20260209: object { name, type, allowed_callers, 7 more }` + + - `name: "web_search"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "web_search_20260209"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `allowed_domains: optional array of string` + + If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. + + - `blocked_domains: optional array of string` + + If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `max_uses: optional number` + + Maximum number of times the tool can be used in the API request. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `user_location: optional object { type, city, country, 2 more }` + + Parameters for the user's location. Used to provide more relevant search results. + + - `type: "approximate"` + + - `city: optional string` + + The city of the user. + + - `country: optional string` + + The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + + - `region: optional string` + + The region of the user. + + - `timezone: optional string` + + The [IANA timezone](https://nodatime.org/TimeZones) of the user. + +### Web Search Tool Request Error + +- `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Block + +- `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + +### Web Search Tool Result Block Content + +- `web_search_tool_result_block_content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + +### Web Search Tool Result Block Param + +- `web_search_tool_result_block_param: object { content, tool_use_id, type, 2 more }` + + - `content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `cache_control: optional object { type, ttl }` + + Create a cache control breakpoint at this content block. + + - `type: "ephemeral"` + + - `ttl: optional "5m" or "1h"` + + The time-to-live for the cache control breakpoint. + + This may be one the following values: + + - `5m`: 5 minutes + - `1h`: 1 hour + + Defaults to `5m`. + + - `"5m"` + + - `"1h"` + + - `caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + +### Web Search Tool Result Block Param Content + +- `web_search_tool_result_block_param_content: array of WebSearchResultBlockParam or WebSearchToolRequestError` + + - `web_search_tool_result_block_item: array of WebSearchResultBlockParam` + + - `encrypted_content: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `page_age: optional string` + + - `web_search_tool_request_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Error + +- `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + +### Web Search Tool Result Error Code + +- `web_search_tool_result_error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + +# Batches + +## Create + +`$ ant messages:batches create` + +**post** `/v1/messages/batches` + +Send a batch of Message creation requests. + +The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--request: array of object { custom_id, params }` + + List of requests for prompt completion. Each is an individual request to create a Message. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` Object type. - For Messages, this is always `"message"`. - - - `"message"` - - - `usage: Usage` - - Billing and rate-limit usage. - - Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. - - Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. - - For example, `output_tokens` will be non-zero, even for an empty string response from Claude. - - Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - - - `cache_creation: CacheCreation` - - Breakdown of cached tokens by TTL - - - `ephemeral_1h_input_tokens: number` - - The number of input tokens used to create the 1 hour cache entry. - - - `ephemeral_5m_input_tokens: number` - - The number of input tokens used to create the 5 minute cache entry. - - - `cache_creation_input_tokens: number` - - The number of input tokens used to create the cache entry. - - - `cache_read_input_tokens: number` - - The number of input tokens read from the cache. - - - `inference_geo: string` - - The geographic region where inference was performed for this request. - - - `input_tokens: number` - - The number of input tokens which were used. - - - `output_tokens: number` - - The number of output tokens which were used. - - - `server_tool_use: ServerToolUsage` - - The number of server tool requests. - - - `web_fetch_requests: number` - - The number of web fetch tool requests. - - - `web_search_requests: number` - - The number of web search tool requests. - - - `service_tier: "standard" or "priority" or "batch"` - - If the request used the priority, standard, or batch tier. - - - `"standard"` - - - `"priority"` - - - `"batch"` + For Message Batches, this is always `"message_batch"`. ### Example -```http -curl https://api.anthropic.com/v1/messages \ - -H 'Content-Type: application/json' \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" \ - --max-time 600 \ - -d '{ - "max_tokens": 1024, - "messages": [ - { - "content": "Hello, world", - "role": "user" - } - ], - "model": "claude-opus-4-6" - }' +```cli +ant messages:batches create \ + --api-key my-anthropic-api-key \ + --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-4-6}}' ``` + +## Retrieve + +`$ ant messages:batches retrieve` + +**get** `/v1/messages/batches/{message_batch_id}` + +This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches retrieve \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## List + +`$ ant messages:batches list` + +**get** `/v1/messages/batches` + +List all Message Batches within a Workspace. Most recently created batches are returned first. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--after-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. + +- `--before-id: optional string` + + ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. + +- `--limit: optional number` + + Number of items to return per page. + + Defaults to `20`. Ranges from `1` to `1000`. + +### Returns + +- `ListResponse_MessageBatch_: object { data, first_id, has_more, last_id }` + + - `data: array of MessageBatch` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + + - `first_id: string` + + First ID in the `data` list. Can be used as the `before_id` for the previous page. + + - `has_more: boolean` + + Indicates if there are more results in the requested page direction. + + - `last_id: string` + + Last ID in the `data` list. Can be used as the `after_id` for the next page. + +### Example + +```cli +ant messages:batches list \ + --api-key my-anthropic-api-key +``` + +## Cancel + +`$ ant messages:batches cancel` + +**post** `/v1/messages/batches/{message_batch_id}/cancel` + +Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. + +The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Example + +```cli +ant messages:batches cancel \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Delete + +`$ ant messages:batches delete` + +**delete** `/v1/messages/batches/{message_batch_id}` + +Delete a Message Batch. + +Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Example + +```cli +ant messages:batches delete \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Results + +`$ ant messages:batches results` + +**get** `/v1/messages/batches/{message_batch_id}/results` + +Streams the results of a Message Batch as a `.jsonl` file. + +Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + +Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) + +### Parameters + +- `--message-batch-id: string` + + ID of the Message Batch. + +### Returns + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Example + +```cli +ant messages:batches results \ + --api-key my-anthropic-api-key \ + --message-batch-id message_batch_id +``` + +## Domain Types + +### Deleted Message Batch + +- `deleted_message_batch: object { id, type }` + + - `id: string` + + ID of the Message Batch. + + - `type: "message_batch_deleted"` + + Deleted object type. + + For Message Batches, this is always `"message_batch_deleted"`. + +### Message Batch + +- `message_batch: object { id, archived_at, cancel_initiated_at, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `archived_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. + + - `cancel_initiated_at: string` + + RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. + + - `created_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch was created. + + - `ended_at: string` + + RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. + + Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. + + - `expires_at: string` + + RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. + + - `processing_status: "in_progress" or "canceling" or "ended"` + + Processing status of the Message Batch. + + - `"in_progress"` + + - `"canceling"` + + - `"ended"` + + - `request_counts: object { canceled, errored, expired, 2 more }` + + Tallies requests within the Message Batch, categorized by their status. + + Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + + - `results_url: string` + + URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. + + Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. + + - `type: "message_batch"` + + Object type. + + For Message Batches, this is always `"message_batch"`. + +### Message Batch Canceled Result + +- `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + +### Message Batch Errored Result + +- `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + +### Message Batch Expired Result + +- `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Individual Response + +- `message_batch_individual_response: object { custom_id, result }` + + This is a single line in the response `.jsonl` file and does not represent the response as a whole. + + - `custom_id: string` + + Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. + + Must be unique for each request within the Message Batch. + + - `result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Request Counts + +- `message_batch_request_counts: object { canceled, errored, expired, 2 more }` + + - `canceled: number` + + Number of requests in the Message Batch that have been canceled. + + This is zero until processing of the entire Message Batch has ended. + + - `errored: number` + + Number of requests in the Message Batch that encountered an error. + + This is zero until processing of the entire Message Batch has ended. + + - `expired: number` + + Number of requests in the Message Batch that have expired. + + This is zero until processing of the entire Message Batch has ended. + + - `processing: number` + + Number of requests in the Message Batch that are processing. + + - `succeeded: number` + + Number of requests in the Message Batch that have completed successfully. + + This is zero until processing of the entire Message Batch has ended. + +### Message Batch Result + +- `message_batch_result: MessageBatchSucceededResult or MessageBatchErroredResult or MessageBatchCanceledResult or MessageBatchExpiredResult` + + Processing result for this request. + + Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. + + - `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` + + - `message_batch_errored_result: object { error, type }` + + - `error: object { error, request_id, type }` + + - `error: InvalidRequestError or AuthenticationError or BillingError or 6 more` + + - `invalid_request_error: object { message, type }` + + - `message: string` + + - `type: "invalid_request_error"` + + - `authentication_error: object { message, type }` + + - `message: string` + + - `type: "authentication_error"` + + - `billing_error: object { message, type }` + + - `message: string` + + - `type: "billing_error"` + + - `permission_error: object { message, type }` + + - `message: string` + + - `type: "permission_error"` + + - `not_found_error: object { message, type }` + + - `message: string` + + - `type: "not_found_error"` + + - `rate_limit_error: object { message, type }` + + - `message: string` + + - `type: "rate_limit_error"` + + - `gateway_timeout_error: object { message, type }` + + - `message: string` + + - `type: "timeout_error"` + + - `api_error_object: object { message, type }` + + - `message: string` + + - `type: "api_error"` + + - `overloaded_error: object { message, type }` + + - `message: string` + + - `type: "overloaded_error"` + + - `request_id: string` + + - `type: "error"` + + - `type: "errored"` + + - `message_batch_canceled_result: object { type }` + + - `type: "canceled"` + + - `message_batch_expired_result: object { type }` + + - `type: "expired"` + +### Message Batch Succeeded Result + +- `message_batch_succeeded_result: object { message, type }` + + - `message: object { id, container, content, 7 more }` + + - `id: string` + + Unique object identifier. + + The format and length of IDs may change over time. + + - `container: object { id, expires_at }` + + Information about the container used in the request (for the code execution tool) + + - `id: string` + + Identifier for the container used in this request + + - `expires_at: string` + + The time at which the container will expire. + + - `content: array of ContentBlock` + + Content generated by the model. + + This is an array of content blocks, each of which has a `type` that determines its shape. + + Example: + + ```json + [{"type": "text", "text": "Hi, I'm Claude."}] + ``` + + If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. + + For example, if the input `messages` were: + + ```json + [ + {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, + {"role": "assistant", "content": "The best answer is ("} + ] + ``` + + Then the response `content` might be: + + ```json + [{"type": "text", "text": "B)"}] + ``` + + - `text_block: object { citations, text, type }` + + - `citations: array of TextCitation` + + Citations supporting the text block. + + The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. + + - `citation_char_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_char_index: number` + + - `file_id: string` + + - `start_char_index: number` + + - `type: "char_location"` + + - `citation_page_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_page_number: number` + + - `file_id: string` + + - `start_page_number: number` + + - `type: "page_location"` + + - `citation_content_block_location: object { cited_text, document_index, document_title, 4 more }` + + - `cited_text: string` + + - `document_index: number` + + - `document_title: string` + + - `end_block_index: number` + + - `file_id: string` + + - `start_block_index: number` + + - `type: "content_block_location"` + + - `citations_web_search_result_location: object { cited_text, encrypted_index, title, 2 more }` + + - `cited_text: string` + + - `encrypted_index: string` + + - `title: string` + + - `type: "web_search_result_location"` + + - `url: string` + + - `citations_search_result_location: object { cited_text, end_block_index, search_result_index, 4 more }` + + - `cited_text: string` + + - `end_block_index: number` + + - `search_result_index: number` + + - `source: string` + + - `start_block_index: number` + + - `title: string` + + - `type: "search_result_location"` + + - `text: string` + + - `type: "text"` + + - `thinking_block: object { signature, thinking, type }` + + - `signature: string` + + - `thinking: string` + + - `type: "thinking"` + + - `redacted_thinking_block: object { data, type }` + + - `data: string` + + - `type: "redacted_thinking"` + + - `tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: string` + + - `type: "tool_use"` + + - `server_tool_use_block: object { id, caller, input, 2 more }` + + - `id: string` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `input: map[unknown]` + + - `name: "web_search" or "web_fetch" or "code_execution" or 4 more` + + - `"web_search"` + + - `"web_fetch"` + + - `"code_execution"` + + - `"bash_code_execution"` + + - `"text_editor_code_execution"` + + - `"tool_search_tool_regex"` + + - `"tool_search_tool_bm25"` + + - `type: "server_tool_use"` + + - `web_search_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebSearchToolResultError or array of WebSearchResultBlock` + + - `web_search_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"max_uses_exceeded"` + + - `"too_many_requests"` + + - `"query_too_long"` + + - `"request_too_large"` + + - `type: "web_search_tool_result_error"` + + - `union_member_1: array of WebSearchResultBlock` + + - `encrypted_content: string` + + - `page_age: string` + + - `title: string` + + - `type: "web_search_result"` + + - `url: string` + + - `tool_use_id: string` + + - `type: "web_search_tool_result"` + + - `web_fetch_tool_result_block: object { caller, content, tool_use_id, type }` + + - `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120` + + Tool invocation directly from the model. + + - `direct_caller: object { type }` + + Tool invocation directly from the model. + + - `type: "direct"` + + - `server_tool_caller: object { tool_id, type }` + + Tool invocation generated by a server-side tool. + + - `tool_id: string` + + - `type: "code_execution_20250825"` + + - `server_tool_caller_20260120: object { tool_id, type }` + + - `tool_id: string` + + - `type: "code_execution_20260120"` + + - `content: WebFetchToolResultErrorBlock or WebFetchBlock` + + - `web_fetch_tool_result_error_block: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more` + + - `"invalid_tool_input"` + + - `"url_too_long"` + + - `"url_not_allowed"` + + - `"url_not_accessible"` + + - `"unsupported_content_type"` + + - `"too_many_requests"` + + - `"max_uses_exceeded"` + + - `"unavailable"` + + - `type: "web_fetch_tool_result_error"` + + - `web_fetch_block: object { content, retrieved_at, type, url }` + + - `content: object { citations, source, title, type }` + + - `citations: object { enabled }` + + Citation configuration for the document + + - `enabled: boolean` + + - `source: Base64PDFSource or PlainTextSource` + + - `base64_pdf_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "application/pdf"` + + - `type: "base64"` + + - `plain_text_source: object { data, media_type, type }` + + - `data: string` + + - `media_type: "text/plain"` + + - `type: "text"` + + - `title: string` + + The title of the document + + - `type: "document"` + + - `retrieved_at: string` + + ISO 8601 timestamp when the content was retrieved + + - `type: "web_fetch_result"` + + - `url: string` + + Fetched content URL + + - `tool_use_id: string` + + - `type: "web_fetch_tool_result"` + + - `code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: CodeExecutionToolResultError or CodeExecutionResultBlock or EncryptedCodeExecutionResultBlock` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `type: "code_execution_tool_result_error"` + + - `code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "code_execution_result"` + + - `encrypted_code_execution_result_block: object { content, encrypted_stdout, return_code, 2 more }` + + Code execution result with encrypted stdout for PFC + web_search results. + + - `content: array of CodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "code_execution_output"` + + - `encrypted_stdout: string` + + - `return_code: number` + + - `stderr: string` + + - `type: "encrypted_code_execution_result"` + + - `tool_use_id: string` + + - `type: "code_execution_tool_result"` + + - `bash_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock` + + - `bash_code_execution_tool_result_error: object { error_code, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"output_file_too_large"` + + - `type: "bash_code_execution_tool_result_error"` + + - `bash_code_execution_result_block: object { content, return_code, stderr, 2 more }` + + - `content: array of BashCodeExecutionOutputBlock` + + - `file_id: string` + + - `type: "bash_code_execution_output"` + + - `return_code: number` + + - `stderr: string` + + - `stdout: string` + + - `type: "bash_code_execution_result"` + + - `tool_use_id: string` + + - `type: "bash_code_execution_tool_result"` + + - `text_editor_code_execution_tool_result_block: object { content, tool_use_id, type }` + + - `content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock` + + - `text_editor_code_execution_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `"file_not_found"` + + - `error_message: string` + + - `type: "text_editor_code_execution_tool_result_error"` + + - `text_editor_code_execution_view_result_block: object { content, file_type, num_lines, 3 more }` + + - `content: string` + + - `file_type: "text" or "image" or "pdf"` + + - `"text"` + + - `"image"` + + - `"pdf"` + + - `num_lines: number` + + - `start_line: number` + + - `total_lines: number` + + - `type: "text_editor_code_execution_view_result"` + + - `text_editor_code_execution_create_result_block: object { is_file_update, type }` + + - `is_file_update: boolean` + + - `type: "text_editor_code_execution_create_result"` + + - `text_editor_code_execution_str_replace_result_block: object { lines, new_lines, new_start, 3 more }` + + - `lines: array of string` + + - `new_lines: number` + + - `new_start: number` + + - `old_lines: number` + + - `old_start: number` + + - `type: "text_editor_code_execution_str_replace_result"` + + - `tool_use_id: string` + + - `type: "text_editor_code_execution_tool_result"` + + - `tool_search_tool_result_block: object { content, tool_use_id, type }` + + - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock` + + - `tool_search_tool_result_error: object { error_code, error_message, type }` + + - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` + + - `"invalid_tool_input"` + + - `"unavailable"` + + - `"too_many_requests"` + + - `"execution_time_exceeded"` + + - `error_message: string` + + - `type: "tool_search_tool_result_error"` + + - `tool_search_tool_search_result_block: object { tool_references, type }` + + - `tool_references: array of ToolReferenceBlock` + + - `tool_name: string` + + - `type: "tool_reference"` + + - `type: "tool_search_tool_search_result"` + + - `tool_use_id: string` + + - `type: "tool_search_tool_result"` + + - `container_upload_block: object { file_id, type }` + + Response model for a file uploaded to the container. + + - `file_id: string` + + - `type: "container_upload"` + + - `model: "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more or string` + + The model that will complete your prompt. + + See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. + + - `"claude-opus-4-7"` + + Frontier intelligence for long-running agents and coding + + - `"claude-mythos-preview"` + + New class of intelligence, strongest in coding and cybersecurity + + - `"claude-opus-4-6"` + + Frontier intelligence for long-running agents and coding + + - `"claude-sonnet-4-6"` + + Best combination of speed and intelligence + + - `"claude-haiku-4-5"` + + Fastest model with near-frontier intelligence + + - `"claude-haiku-4-5-20251001"` + + Fastest model with near-frontier intelligence + + - `"claude-opus-4-5"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-opus-4-5-20251101"` + + Premium model combining maximum intelligence with practical performance + + - `"claude-sonnet-4-5"` + + High-performance model for agents and coding + + - `"claude-sonnet-4-5-20250929"` + + High-performance model for agents and coding + + - `"claude-opus-4-1"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-1-20250805"` + + Exceptional model for specialized complex tasks + + - `"claude-opus-4-0"` + + Powerful model for complex tasks + + - `"claude-opus-4-20250514"` + + Powerful model for complex tasks + + - `"claude-sonnet-4-0"` + + High-performance model with extended thinking + + - `"claude-sonnet-4-20250514"` + + High-performance model with extended thinking + + - `"claude-3-haiku-20240307"` + + Fast and cost-effective model + + - `role: "assistant"` + + Conversational role of the generated message. + + This will always be `"assistant"`. + + - `stop_details: object { category, explanation, type }` + + Structured information about a refusal. + + - `category: "cyber" or "bio"` + + The policy category that triggered the refusal. + + `null` when the refusal doesn't map to a named category. + + - `"cyber"` + + - `"bio"` + + - `explanation: string` + + Human-readable explanation of the refusal. + + This text is not guaranteed to be stable. `null` when no explanation is available for the category. + + - `type: "refusal"` + + - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 3 more` + + The reason that we stopped. + + This may be one the following values: + + * `"end_turn"`: the model reached a natural stopping point + * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum + * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated + * `"tool_use"`: the model invoked one or more tools + * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. + * `"refusal"`: when streaming classifiers intervene to handle potential policy violations + + In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. + + - `"end_turn"` + + - `"max_tokens"` + + - `"stop_sequence"` + + - `"tool_use"` + + - `"pause_turn"` + + - `"refusal"` + + - `stop_sequence: string` + + Which custom stop sequence was generated, if any. + + This value will be a non-null string if one of your custom stop sequences was generated. + + - `type: "message"` + + Object type. + + For Messages, this is always `"message"`. + + - `usage: object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 5 more }` + + Billing and rate-limit usage. + + Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. + + Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. + + For example, `output_tokens` will be non-zero, even for an empty string response from Claude. + + Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. + + - `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }` + + Breakdown of cached tokens by TTL + + - `ephemeral_1h_input_tokens: number` + + The number of input tokens used to create the 1 hour cache entry. + + - `ephemeral_5m_input_tokens: number` + + The number of input tokens used to create the 5 minute cache entry. + + - `cache_creation_input_tokens: number` + + The number of input tokens used to create the cache entry. + + - `cache_read_input_tokens: number` + + The number of input tokens read from the cache. + + - `inference_geo: string` + + The geographic region where inference was performed for this request. + + - `input_tokens: number` + + The number of input tokens which were used. + + - `output_tokens: number` + + The number of output tokens which were used. + + - `server_tool_use: object { web_fetch_requests, web_search_requests }` + + The number of server tool requests. + + - `web_fetch_requests: number` + + The number of web fetch tool requests. + + - `web_search_requests: number` + + The number of web search tool requests. + + - `service_tier: "standard" or "priority" or "batch"` + + If the request used the priority, standard, or batch tier. + + - `"standard"` + + - `"priority"` + + - `"batch"` + + - `type: "succeeded"` diff --git a/docs/api_reference/anthropic/models.md b/docs/api_reference/anthropic/models.md deleted file mode 100644 index c5d04a2..0000000 --- a/docs/api_reference/anthropic/models.md +++ /dev/null @@ -1,291 +0,0 @@ -## List - -**get** `/v1/models` - -List available models. - -The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. - -### Query Parameters - -- `after_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - -- `before_id: optional string` - - ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - -- `limit: optional number` - - Number of items to return per page. - - Defaults to `20`. Ranges from `1` to `1000`. - -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` - - Optional header to specify the beta version(s) you want to use. - - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 20 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"advisor-tool-2026-03-01"` - - - `"user-profiles-2026-03-24"` - -### Returns - -- `data: array of ModelInfo` - - - `id: string` - - Unique model identifier. - - - `capabilities: ModelCapabilities` - - Model capability information. - - - `batch: CapabilitySupport` - - Whether the model supports the Batch API. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `citations: CapabilitySupport` - - Whether the model supports citation generation. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `code_execution: CapabilitySupport` - - Whether the model supports code execution tools. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `context_management: ContextManagementCapability` - - Context management support and available strategies. - - - `clear_thinking_20251015: CapabilitySupport` - - Indicates whether a capability is supported. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `clear_tool_uses_20250919: CapabilitySupport` - - Indicates whether a capability is supported. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `compact_20260112: CapabilitySupport` - - Indicates whether a capability is supported. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `effort: EffortCapability` - - Effort (reasoning_effort) support and available levels. - - - `high: CapabilitySupport` - - Whether the model supports high effort level. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `low: CapabilitySupport` - - Whether the model supports low effort level. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `max: CapabilitySupport` - - Whether the model supports max effort level. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `medium: CapabilitySupport` - - Whether the model supports medium effort level. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `xhigh: CapabilitySupport` - - Indicates whether a capability is supported. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `image_input: CapabilitySupport` - - Whether the model accepts image content blocks. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `pdf_input: CapabilitySupport` - - Whether the model accepts PDF content blocks. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `structured_outputs: CapabilitySupport` - - Whether the model supports structured output / JSON mode / strict tool schemas. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `thinking: ThinkingCapability` - - Thinking capability and supported type configurations. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `types: ThinkingTypes` - - Supported thinking type configurations. - - - `adaptive: CapabilitySupport` - - Whether the model supports thinking with type 'adaptive' (auto). - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `enabled: CapabilitySupport` - - Whether the model supports thinking with type 'enabled'. - - - `supported: boolean` - - Whether this capability is supported by the model. - - - `created_at: string` - - RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - - - `display_name: string` - - A human-readable name for the model. - - - `max_input_tokens: number` - - Maximum input context window size in tokens for this model. - - - `max_tokens: number` - - Maximum value for the `max_tokens` parameter when using this model. - - - `type: "model"` - - Object type. - - For Models, this is always `"model"`. - - - `"model"` - -- `first_id: string` - - First ID in the `data` list. Can be used as the `before_id` for the previous page. - -- `has_more: boolean` - - Indicates if there are more results in the requested page direction. - -- `last_id: string` - - Last ID in the `data` list. Can be used as the `after_id` for the next page. - -### Example - -```http -curl https://api.anthropic.com/v1/models \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" -``` diff --git a/docs/api_reference/anthropic/models_get.md b/docs/api_reference/anthropic/retrieve.md similarity index 64% rename from docs/api_reference/anthropic/models_get.md rename to docs/api_reference/anthropic/retrieve.md index 4c9a5cb..e0517be 100644 --- a/docs/api_reference/anthropic/models_get.md +++ b/docs/api_reference/anthropic/retrieve.md @@ -1,86 +1,36 @@ ## Retrieve +`$ ant models retrieve` + **get** `/v1/models/{model_id}` Get a specific model. The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. -### Path Parameters +### Parameters -- `model_id: string` +- `--model-id: string` Model identifier or alias. -### Header Parameters - -- `"anthropic-beta": optional array of AnthropicBeta` +- `--beta: optional array of AnthropicBeta` Optional header to specify the beta version(s) you want to use. - - `UnionMember0 = string` - - - `UnionMember1 = "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 20 more` - - - `"message-batches-2024-09-24"` - - - `"prompt-caching-2024-07-31"` - - - `"computer-use-2024-10-22"` - - - `"computer-use-2025-01-24"` - - - `"pdfs-2024-09-25"` - - - `"token-counting-2024-11-01"` - - - `"token-efficient-tools-2025-02-19"` - - - `"output-128k-2025-02-19"` - - - `"files-api-2025-04-14"` - - - `"mcp-client-2025-04-04"` - - - `"mcp-client-2025-11-20"` - - - `"dev-full-thinking-2025-05-14"` - - - `"interleaved-thinking-2025-05-14"` - - - `"code-execution-2025-05-22"` - - - `"extended-cache-ttl-2025-04-11"` - - - `"context-1m-2025-08-07"` - - - `"context-management-2025-06-27"` - - - `"model-context-window-exceeded-2025-08-26"` - - - `"skills-2025-10-02"` - - - `"fast-mode-2026-02-01"` - - - `"output-300k-2026-03-24"` - - - `"advisor-tool-2026-03-01"` - - - `"user-profiles-2026-03-24"` - ### Returns -- `ModelInfo = object { id, capabilities, created_at, 4 more }` +- `model_info: object { id, capabilities, created_at, 4 more }` - `id: string` Unique model identifier. - - `capabilities: ModelCapabilities` + - `capabilities: object { batch, citations, code_execution, 6 more }` Model capability information. - - `batch: CapabilitySupport` + - `batch: object { supported }` Whether the model supports the Batch API. @@ -88,7 +38,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `citations: CapabilitySupport` + - `citations: object { supported }` Whether the model supports citation generation. @@ -96,7 +46,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `code_execution: CapabilitySupport` + - `code_execution: object { supported }` Whether the model supports code execution tools. @@ -104,11 +54,11 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `context_management: ContextManagementCapability` + - `context_management: object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }` Context management support and available strategies. - - `clear_thinking_20251015: CapabilitySupport` + - `clear_thinking_20251015: object { supported }` Indicates whether a capability is supported. @@ -116,7 +66,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `clear_tool_uses_20250919: CapabilitySupport` + - `clear_tool_uses_20250919: object { supported }` Indicates whether a capability is supported. @@ -124,7 +74,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `compact_20260112: CapabilitySupport` + - `compact_20260112: object { supported }` Indicates whether a capability is supported. @@ -136,11 +86,11 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `effort: EffortCapability` + - `effort: object { high, low, max, 3 more }` Effort (reasoning_effort) support and available levels. - - `high: CapabilitySupport` + - `high: object { supported }` Whether the model supports high effort level. @@ -148,7 +98,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `low: CapabilitySupport` + - `low: object { supported }` Whether the model supports low effort level. @@ -156,7 +106,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `max: CapabilitySupport` + - `max: object { supported }` Whether the model supports max effort level. @@ -164,7 +114,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `medium: CapabilitySupport` + - `medium: object { supported }` Whether the model supports medium effort level. @@ -176,7 +126,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `xhigh: CapabilitySupport` + - `xhigh: object { supported }` Indicates whether a capability is supported. @@ -184,7 +134,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `image_input: CapabilitySupport` + - `image_input: object { supported }` Whether the model accepts image content blocks. @@ -192,7 +142,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `pdf_input: CapabilitySupport` + - `pdf_input: object { supported }` Whether the model accepts PDF content blocks. @@ -200,7 +150,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `structured_outputs: CapabilitySupport` + - `structured_outputs: object { supported }` Whether the model supports structured output / JSON mode / strict tool schemas. @@ -208,7 +158,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `thinking: ThinkingCapability` + - `thinking: object { supported, types }` Thinking capability and supported type configurations. @@ -216,11 +166,11 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `types: ThinkingTypes` + - `types: object { adaptive, enabled }` Supported thinking type configurations. - - `adaptive: CapabilitySupport` + - `adaptive: object { supported }` Whether the model supports thinking with type 'adaptive' (auto). @@ -228,7 +178,7 @@ The Models API response can be used to determine information about a specific mo Whether this capability is supported by the model. - - `enabled: CapabilitySupport` + - `enabled: object { supported }` Whether the model supports thinking with type 'enabled'. @@ -258,12 +208,10 @@ The Models API response can be used to determine information about a specific mo For Models, this is always `"model"`. - - `"model"` - ### Example -```http -curl https://api.anthropic.com/v1/models/$MODEL_ID \ - -H 'anthropic-version: 2023-06-01' \ - -H "X-Api-Key: $ANTHROPIC_API_KEY" +```cli +ant models retrieve \ + --api-key my-anthropic-api-key \ + --model-id model_id ``` diff --git a/docs/api_reference/openai/Create embeddings.md b/docs/api_reference/openai/Create embeddings.md new file mode 100644 index 0000000..8ebb6be --- /dev/null +++ b/docs/api_reference/openai/Create embeddings.md @@ -0,0 +1,175 @@ +## Create embeddings + +**post** `/embeddings` + +Creates an embedding vector representing the input text. + +### Body Parameters + +- `input: string or array of string or array of number or array of array of number` + + Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for all embedding models), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. In addition to the per-input token limit, all embedding models enforce a maximum of 300,000 tokens summed across all inputs in a single request. + + - `String = string` + + The string that will be turned into an embedding. + + - `Array = array of string` + + The array of strings that will be turned into an embedding. + + - `Array = array of number` + + The array of integers that will be turned into an embedding. + + - `Array = array of array of number` + + The array of arrays containing integers that will be turned into an embedding. + +- `model: string or EmbeddingModel` + + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + + - `string` + + - `EmbeddingModel = "text-embedding-ada-002" or "text-embedding-3-small" or "text-embedding-3-large"` + + - `"text-embedding-ada-002"` + + - `"text-embedding-3-small"` + + - `"text-embedding-3-large"` + +- `dimensions: optional number` + + The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models. + +- `encoding_format: optional "float" or "base64"` + + The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/). + + - `"float"` + + - `"base64"` + +- `user: optional string` + + A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids). + +### Returns + +- `CreateEmbeddingResponse object { data, model, object, usage }` + + - `data: array of Embedding` + + The list of embeddings generated by the model. + + - `embedding: array of number` + + The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the [embedding guide](/docs/guides/embeddings). + + - `index: number` + + The index of the embedding in the list of embeddings. + + - `object: "embedding"` + + The object type, which is always "embedding". + + - `"embedding"` + + - `model: string` + + The name of the model used to generate the embedding. + + - `object: "list"` + + The object type, which is always "list". + + - `"list"` + + - `usage: object { prompt_tokens, total_tokens }` + + The usage information for the request. + + - `prompt_tokens: number` + + The number of tokens used by the prompt. + + - `total_tokens: number` + + The total number of tokens used by the request. + +### Example + +```http +curl https://api.openai.com/v1/embeddings \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "input": "The quick brown fox jumped over the lazy dog", + "model": "text-embedding-3-small", + "encoding_format": "float", + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "data": [ + { + "embedding": [ + 0 + ], + "index": 0, + "object": "embedding" + } + ], + "model": "model", + "object": "list", + "usage": { + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` + +### Example + +```http +curl https://api.openai.com/v1/embeddings \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' +``` + +#### Response + +```json +{ + "object": "list", + "data": [ + { + "object": "embedding", + "embedding": [ + 0.0023064255, + -0.009327292, + .... (1536 floats total for ada-002) + -0.0028842222, + ], + "index": 0 + } + ], + "model": "text-embedding-ada-002", + "usage": { + "prompt_tokens": 8, + "total_tokens": 8 + } +} +``` diff --git a/docs/api_reference/openai/Create image.md b/docs/api_reference/openai/Create image.md new file mode 100644 index 0000000..742b512 --- /dev/null +++ b/docs/api_reference/openai/Create image.md @@ -0,0 +1,367 @@ +## Create image + +**post** `/images/generations` + +Creates an image given a prompt. [Learn more](/docs/guides/images). + +### Body Parameters + +- `prompt: string` + + A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. + +- `background: optional "transparent" or "opaque" or "auto"` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for the GPT image models. Must be one of + `transparent`, `opaque` or `auto` (default value). When `auto` is used, the + model will automatically determine the best background for the image. + + If `transparent`, the output format needs to support transparency, so it + should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + +- `model: optional string or ImageModel` + + The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used. + + - `string` + + - `ImageModel = "gpt-image-1.5" or "dall-e-2" or "dall-e-3" or 2 more` + + - `"gpt-image-1.5"` + + - `"dall-e-2"` + + - `"dall-e-3"` + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + +- `moderation: optional "low" or "auto"` + + Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). + + - `"low"` + + - `"auto"` + +- `n: optional number` + + The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. + +- `output_compression: optional number` + + The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100. + +- `output_format: optional "png" or "jpeg" or "webp"` + + The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`. + + - `"png"` + + - `"jpeg"` + + - `"webp"` + +- `partial_images: optional number` + + The number of partial images to generate. This parameter is used for + streaming responses that return partial images. Value must be between 0 and 3. + When set to 0, the response will be a single image sent in one streaming event. + + Note that the final image may be sent before the full number of partial images + are generated if the full image is generated more quickly. + +- `quality: optional "standard" or "hd" or "low" or 3 more` + + The quality of the image that will be generated. + + - `auto` (default value) will automatically select the best quality for the given model. + - `high`, `medium` and `low` are supported for the GPT image models. + - `hd` and `standard` are supported for `dall-e-3`. + - `standard` is the only option for `dall-e-2`. + + - `"standard"` + + - `"hd"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + +- `response_format: optional "url" or "b64_json"` + + The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images. + + - `"url"` + + - `"b64_json"` + +- `size: optional "auto" or "1024x1024" or "1536x1024" or 5 more` + + The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for the GPT image models, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`. + + - `"auto"` + + - `"1024x1024"` + + - `"1536x1024"` + + - `"1024x1536"` + + - `"256x256"` + + - `"512x512"` + + - `"1792x1024"` + + - `"1024x1792"` + +- `stream: optional boolean` + + Generate the image in streaming mode. Defaults to `false`. See the + [Image generation guide](/docs/guides/image-generation) for more information. + This parameter is only supported for the GPT image models. + +- `style: optional "vivid" or "natural"` + + The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. + + - `"vivid"` + + - `"natural"` + +- `user: optional string` + + A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids). + +### Returns + +- `ImagesResponse object { created, background, data, 4 more }` + + The response from the image generation endpoint. + + - `created: number` + + The Unix timestamp (in seconds) of when the image was created. + + - `background: optional "transparent" or "opaque"` + + The background parameter used for the image generation. Either `transparent` or `opaque`. + + - `"transparent"` + + - `"opaque"` + + - `data: optional array of Image` + + The list of generated images. + + - `b64_json: optional string` + + The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`. + + - `revised_prompt: optional string` + + For `dall-e-3` only, the revised prompt that was used to generate the image. + + - `url: optional string` + + When using `dall-e-2` or `dall-e-3`, the URL of the generated image if `response_format` is set to `url` (default value). Unsupported for the GPT image models. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the image generation. Either `png`, `webp`, or `jpeg`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `quality: optional "low" or "medium" or "high"` + + The quality of the image generated. Either `low`, `medium`, or `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `size: optional "1024x1024" or "1024x1536" or "1536x1024"` + + The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + + For `gpt-image-1` only, the token usage information for the image generation. + + - `input_tokens: number` + + The number of tokens (images and text) in the input prompt. + + - `input_tokens_details: object { image_tokens, text_tokens }` + + The input tokens detailed information for the image generation. + + - `image_tokens: number` + + The number of image tokens in the input prompt. + + - `text_tokens: number` + + The number of text tokens in the input prompt. + + - `output_tokens: number` + + The number of output tokens generated by the model. + + - `total_tokens: number` + + The total number of tokens (images and text) used for the image generation. + + - `output_tokens_details: optional object { image_tokens, text_tokens }` + + The output token details for the image generation. + + - `image_tokens: number` + + The number of image output tokens generated by the model. + + - `text_tokens: number` + + The number of text output tokens generated by the model. + +### Example + +```http +curl https://api.openai.com/v1/images/generations \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "prompt": "A cute baby sea otter", + "background": "transparent", + "moderation": "low", + "n": 1, + "output_compression": 100, + "output_format": "png", + "partial_images": 1, + "quality": "medium", + "response_format": "url", + "size": "1024x1024", + "style": "vivid", + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "created": 0, + "background": "transparent", + "data": [ + { + "b64_json": "b64_json", + "revised_prompt": "revised_prompt", + "url": "url" + } + ], + "output_format": "png", + "quality": "low", + "size": "1024x1024", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "image_tokens": 0, + "text_tokens": 0 + }, + "output_tokens": 0, + "total_tokens": 0, + "output_tokens_details": { + "image_tokens": 0, + "text_tokens": 0 + } + } +} +``` + +### Generate image + +```http +curl https://api.openai.com/v1/images/generations \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-image-1.5", + "prompt": "A cute baby sea otter", + "n": 1, + "size": "1024x1024" + }' +``` + +#### Response + +```json +{ + "created": 1713833628, + "data": [ + { + "b64_json": "..." + } + ], + "usage": { + "total_tokens": 100, + "input_tokens": 50, + "output_tokens": 50, + "input_tokens_details": { + "text_tokens": 10, + "image_tokens": 40 + } + } +} +``` + +### Streaming + +```http +curl https://api.openai.com/v1/images/generations \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-image-1.5", + "prompt": "A cute baby sea otter", + "n": 1, + "size": "1024x1024", + "stream": true + }' \ + --no-buffer +``` + +#### Response + +```json +event: image_generation.partial_image +data: {"type":"image_generation.partial_image","b64_json":"...","partial_image_index":0} + +event: image_generation.completed +data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}} +``` diff --git a/docs/api_reference/openai/models.md b/docs/api_reference/openai/List models.md similarity index 100% rename from docs/api_reference/openai/models.md rename to docs/api_reference/openai/List models.md diff --git a/docs/api_reference/openai/Retrieve model.md b/docs/api_reference/openai/Retrieve model.md new file mode 100644 index 0000000..c12d735 --- /dev/null +++ b/docs/api_reference/openai/Retrieve model.md @@ -0,0 +1,69 @@ +## Retrieve model + +**get** `/models/{model}` + +Retrieves a model instance, providing basic information about the model such as the owner and permissioning. + +### Path Parameters + +- `model: string` + +### Returns + +- `Model object { id, created, object, owned_by }` + + Describes an OpenAI model offering that can be used with the API. + + - `id: string` + + The model identifier, which can be referenced in the API endpoints. + + - `created: number` + + The Unix timestamp (in seconds) when the model was created. + + - `object: "model"` + + The object type, which is always "model". + + - `"model"` + + - `owned_by: string` + + The organization that owns the model. + +### Example + +```http +curl https://api.openai.com/v1/models/$MODEL \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "created": 0, + "object": "model", + "owned_by": "owned_by" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/models/VAR_chat_model_id \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "VAR_chat_model_id", + "object": "model", + "created": 1686935002, + "owned_by": "openai" +} +``` diff --git a/docs/api_reference/openai/chat.md b/docs/api_reference/openai/chat/Create chat completion.md similarity index 100% rename from docs/api_reference/openai/chat.md rename to docs/api_reference/openai/chat/Create chat completion.md diff --git a/docs/api_reference/openai/chat/Streaming events.md b/docs/api_reference/openai/chat/Streaming events.md new file mode 100644 index 0000000..c6d369e --- /dev/null +++ b/docs/api_reference/openai/chat/Streaming events.md @@ -0,0 +1,248 @@ +## Streaming events + +Stream Chat Completions in real time. Receive chunks of completions returned from the model using server-sent events. [Learn more](https://developers.openai.com/docs/guides/streaming-responses?api-mode=chat). + +Represents a streamed chunk of a chat completion response returned by the model, based on the provided input. [Learn more](https://developers.openai.com/docs/guides/streaming-responses). + +id: string + +A unique identifier for the chat completion. Each chunk has the same ID. + +choices: array of object { delta, finish\_reason, index, logprobs } + +A list of chat completion choices. Can contain more than one elements if `n` is greater than 1. Can also be empty for the last chunk if you set `stream_options: {"include_usage": true}`. + +delta: object { content, function\_call, refusal, 2 more } + +A chat completion delta generated by streamed model responses. + +content: optional string + +The contents of the chunk message. + +Deprecatedfunction\_call: optional object { arguments, name } + +Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. + +arguments: optional string + +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. + +name: optional string + +The name of the function to call. + +refusal: optional string + +The refusal message generated by the model. + +role: optional "developer" or "system" or "user" or 2 more + +The role of the author of this message. + +One of the following: + +"developer" + +"system" + +"user" + +"assistant" + +"tool" + +tool\_calls: optional array of object { index, id, function, type } + +index: number + +id: optional string + +The ID of the tool call. + +function: optional object { arguments, name } + +arguments: optional string + +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. + +name: optional string + +The name of the function to call. + +type: optional "function" + +The type of the tool. Currently, only `function` is supported. + +finish\_reason: "stop" or "length" or "tool\_calls" or 2 more + +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, or `function_call` (deprecated) if the model called a function. + +One of the following: + +"stop" + +"length" + +"tool\_calls" + +"content\_filter" + +"function\_call" + +index: number + +The index of the choice in the list of choices. + +logprobs: optional object { content, refusal } + +Log probability information for the choice. + +A list of message content tokens with log probability information. + +token: string + +The token. + +bytes: array of number + +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. + +logprob: number + +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. + +top\_logprobs: array of object { token, bytes, logprob } + +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. + +token: string + +The token. + +bytes: array of number + +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. + +logprob: number + +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. + +A list of message refusal tokens with log probability information. + +token: string + +The token. + +bytes: array of number + +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. + +logprob: number + +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. + +top\_logprobs: array of object { token, bytes, logprob } + +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. + +token: string + +The token. + +bytes: array of number + +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. + +logprob: number + +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. + +created: number + +The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp. + +model: string + +The model to generate the completion. + +object: "chat.completion.chunk" + +The object type, which is always `chat.completion.chunk`. + +service\_tier: optional "auto" or "default" or "flex" or 2 more + +Specifies the processing type used for serving the request. + +- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. +- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. +- If set to '[flex](https://developers.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. +- When not set, the default behavior is 'auto'. + +When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + +One of the following: + +"auto" + +"default" + +"flex" + +"scale" + +"priority" + +Deprecatedsystem\_fingerprint: optional string + +This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. + +usage: optional [CompletionUsage](https://developers.openai.com/api/reference/resources/completions#\(resource\)%20completions%20%3E%20\(model\)%20completion_usage%20%3E%20\(schema\)) { completion\_tokens, prompt\_tokens, total\_tokens, 2 more } + +An optional field that will only be present when you set `stream_options: {"include_usage": true}` in your request. When present, it contains a null value **except for the last chunk** which contains the token usage statistics for the entire request. + +**NOTE:** If the stream is interrupted or cancelled, you may not receive the final usage chunk which contains the total token usage for the request. + +completion\_tokens: number + +Number of tokens in the generated completion. + +prompt\_tokens: number + +Number of tokens in the prompt. + +total\_tokens: number + +Total number of tokens used in the request (prompt + completion). + +completion\_tokens\_details: optional object { accepted\_prediction\_tokens, audio\_tokens, reasoning\_tokens, rejected\_prediction\_tokens } + +Breakdown of tokens used in a completion. + +accepted\_prediction\_tokens: optional number + +When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion. + +audio\_tokens: optional number + +Audio input tokens generated by the model. + +reasoning\_tokens: optional number + +Tokens generated by the model for reasoning. + +rejected\_prediction\_tokens: optional number + +When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits. + +prompt\_tokens\_details: optional object { audio\_tokens, cached\_tokens } + +Breakdown of tokens used in the prompt. + +audio\_tokens: optional number + +Audio input tokens present in the prompt. + +cached\_tokens: optional number + +Cached tokens present in the prompt. \ No newline at end of file diff --git a/docs/api_reference/openai/chat_response.md b/docs/api_reference/openai/responses/Create a model response.md similarity index 100% rename from docs/api_reference/openai/chat_response.md rename to docs/api_reference/openai/responses/Create a model response.md diff --git a/docs/api_reference/openai/count_token.md b/docs/api_reference/openai/responses/Get input token counts.md similarity index 100% rename from docs/api_reference/openai/count_token.md rename to docs/api_reference/openai/responses/Get input token counts.md diff --git a/docs/conversion_anthropic.md b/docs/conversion_anthropic.md new file mode 100644 index 0000000..edc2e68 --- /dev/null +++ b/docs/conversion_anthropic.md @@ -0,0 +1,786 @@ +# Anthropic 协议适配清单 + +> 依据 [conversion_design.md](./conversion_design.md) 附录 D 模板编撰，覆盖 Anthropic API 的全部对接细节。 + +--- + +## 目录 + +1. [协议基本信息](#1-协议基本信息) +2. [接口识别](#2-接口识别) +3. [请求头构建](#3-请求头构建) +4. [核心层 — Chat 请求编解码](#4-核心层--chat-请求编解码) +5. [核心层 — Chat 响应编解码](#5-核心层--chat-响应编解码) +6. [核心层 — 流式编解码](#6-核心层--流式编解码) +7. [扩展层接口](#7-扩展层接口) +8. [错误编码](#8-错误编码) +9. [自检清单](#9-自检清单) + +--- + +## 1. 协议基本信息 + +| 项目 | 说明 | +|------|------| +| 协议名称 | `"anthropic"` | +| 协议版本 | `2023-06-01`（通过 `anthropic-version` Header 传递） | +| Base URL | `https://api.anthropic.com` | +| 认证方式 | `x-api-key: ` | + +--- + +## 2. 接口识别 + +### 2.1 URL 路径模式 + +| URL 路径 | InterfaceType | +|----------|---------------| +| `/v1/messages` | CHAT | +| `/v1/models` | MODELS | +| `/v1/models/{model}` | MODEL_INFO | +| `/v1/batches` | 透传 | +| `/v1/messages/count_tokens` | 透传 | +| `/v1/*` | 透传 | + +### 2.2 接口能力矩阵 + +``` +Anthropic.supportsInterface(type): + CHAT: return true + MODELS: return true + MODEL_INFO: return true + EMBEDDINGS: return false // Anthropic 无此接口 + RERANK: return false // Anthropic 无此接口 + default: return false +``` + +### 2.3 URL 映射表 + +``` +Anthropic.buildUrl(nativePath, interfaceType): + switch interfaceType: + case CHAT: return "/v1/messages" + case MODELS: return "/v1/models" + case MODEL_INFO: return "/v1/models/{modelId}" + default: return nativePath +``` + +不支持 EMBEDDINGS 和 RERANK（`supportsInterface` 返回 false），引擎会自动走透传逻辑。 + +--- + +## 3. 请求头构建 + +### 3.1 buildHeaders + +``` +Anthropic.buildHeaders(provider): + result = {} + result["x-api-key"] = provider.api_key + result["anthropic-version"] = provider.adapter_config["anthropic_version"] ?? "2023-06-01" + if provider.adapter_config["anthropic_beta"]: + result["anthropic-beta"] = provider.adapter_config["anthropic_beta"].join(",") + result["Content-Type"] = "application/json" + return result +``` + +### 3.2 adapter_config 契约 + +| Key | 类型 | 必填 | 默认值 | 说明 | +|-----|------|------|--------|------| +| `anthropic_version` | String | 否 | `"2023-06-01"` | API 版本，映射为 `anthropic-version` Header | +| `anthropic_beta` | Array\ | 否 | `[]` | Beta 功能标识列表，逗号拼接为 `anthropic-beta` Header | + +--- + +## 4. 核心层 — Chat 请求编解码 + +### 4.1 Decoder（Anthropic → Canonical） + +#### 系统消息 + +``` +decodeSystem(system): + if system is None: return None + if system is String: return system + return system.map(s => SystemBlock {text: s.text}) +``` + +Anthropic 使用顶层 `system` 字段（String 或 SystemBlock 数组），直接提取为 `canonical.system`。 + +#### 消息角色映射 + +| Anthropic role | Canonical role | 说明 | +|----------------|---------------|------| +| `user` | `user` | 直接映射；可能包含 tool_result | +| `assistant` | `assistant` | 直接映射 | + +**关键差异**：Anthropic 没有 `system` 和 `tool` 角色。system 通过顶层字段传递；tool_result 嵌入 user 消息的 content 数组中。 + +#### 内容块解码 + +``` +decodeContentBlocks(content): + if content is String: return [{type: "text", text: content}] + return content.map(block => { + switch block.type: + "text" → TextBlock{text: block.text} + "tool_use" → ToolUseBlock{id: block.id, name: block.name, input: block.input} + "tool_result" → ToolResultBlock{tool_use_id: block.tool_use_id, ...} + "thinking" → ThinkingBlock{thinking: block.thinking} + "redacted_thinking" → 丢弃 // 仅 Anthropic 使用，不在中间层保留 + }) +``` + +**tool_result 角色转换**： + +``` +decodeMessage(msg): + switch msg.role: + case "user": + blocks = decodeContentBlocks(msg.content) + toolResults = blocks.filter(b => b.type == "tool_result") + others = blocks.filter(b => b.type != "tool_result") + if toolResults.length > 0: + return [ + ...(others.length > 0 ? [{role: "user", content: others}] : []), + {role: "tool", content: toolResults}] + return [{role: "user", content: blocks}] + case "assistant": + return [{role: "assistant", content: decodeContentBlocks(msg.content)}] +``` + +Anthropic user 消息中的 `tool_result` 块被拆分为独立的 Canonical `tool` 角色消息。 + +#### 工具定义 + +| Anthropic | Canonical | 说明 | +|-----------|-----------|------| +| `tools[].name` | `tools[].name` | 直接映射 | +| `tools[].description` | `tools[].description` | 直接映射 | +| `tools[].input_schema` | `tools[].input_schema` | 字段名相同 | +| `tools[].type` | — | Anthropic 无 function 包装层 | + +#### 工具选择 + +| Anthropic tool_choice | Canonical ToolChoice | +|-----------------------|---------------------| +| `{type: "auto"}` | `{type: "auto"}` | +| `{type: "none"}` | `{type: "none"}` | +| `{type: "any"}` | `{type: "any"}` | +| `{type: "tool", name}` | `{type: "tool", name}` | + +#### 参数映射 + +| Anthropic | Canonical | 说明 | +|-----------|-----------|------| +| `max_tokens` | `parameters.max_tokens` | 直接映射；Anthropic 必填 | +| `temperature` | `parameters.temperature` | 直接映射 | +| `top_p` | `parameters.top_p` | 直接映射 | +| `top_k` | `parameters.top_k` | 直接映射 | +| `stop_sequences` (Array) | `parameters.stop_sequences` (Array) | 直接映射 | +| `stream` | `stream` | 直接映射 | + +#### 新增公共字段 + +``` +decodeExtras(raw): + user_id = raw.metadata?.user_id + output_format = decodeOutputFormat(raw.output_config) + parallel_tool_use = raw.disable_parallel_tool_use == true ? false : null + thinking = raw.thinking ? ThinkingConfig { + type: raw.thinking.type, // "enabled" | "disabled" | "adaptive" + budget_tokens: raw.thinking.budget_tokens, + effort: raw.output_config?.effort } : null +``` + +**ThinkingConfig 三种类型解码**： + +| Anthropic thinking.type | Canonical thinking.type | 说明 | +|-------------------------|----------------------|------| +| `"enabled"` | `"enabled"` | 有 budget_tokens，直接映射 | +| `"disabled"` | `"disabled"` | 直接映射 | +| `"adaptive"` | `"adaptive"` | Anthropic 自动决定是否启用思考，映射为 `"adaptive"`（新增 Canonical 值） | + +> **注意**：`thinking.display`（`"summarized"` / `"omitted"`）为 Anthropic 特有字段，控制响应中思考内容的显示方式，不晋升为公共字段。 + +**output_config 解码**： + +``` +decodeOutputFormat(output_config): + if output_config?.format?.type == "json_schema": + return { type: "json_schema", json_schema: { name: "output", schema: output_config.format.schema, strict: true } } + return null +``` + +| Anthropic | Canonical | 提取规则 | +|-----------|-----------|---------| +| `metadata.user_id` | `user_id` | 从嵌套对象提取 | +| `output_config.format` | `output_format` | 仅支持 `json_schema` 类型；映射为 Canonical OutputFormat | +| `output_config.effort` | `thinking.effort` | `"low"` / `"medium"` / `"high"` / `"xhigh"` / `"max"` 直接映射 | +| `disable_parallel_tool_use` | `parallel_tool_use` | **语义反转**：true → false | +| `thinking.type` | `thinking.type` | 直接映射 | +| `thinking.budget_tokens` | `thinking.budget_tokens` | 直接映射 | + +#### 协议特有字段 + +| 字段 | 处理方式 | +|------|---------| +| `cache_control` | 忽略（仅 Anthropic 使用，不晋升为公共字段） | +| `redacted_thinking` | 解码时丢弃，不在中间层保留 | +| `metadata` (除 user_id) | 忽略 | +| `thinking.display` | 忽略（控制响应显示方式，不影响请求语义） | +| `container` | 忽略（容器标识，协议特有） | +| `inference_geo` | 忽略（地理区域控制，协议特有） | +| `service_tier` | 忽略（服务层级选择，协议特有） | + +#### 协议约束 + +- `max_tokens` 为**必填**字段 +- messages 必须以 `user` 角色开始 +- `user` 和 `assistant` 角色必须严格交替（除连续 tool_result 场景） +- tool_result 必须紧跟在包含对应 tool_use 的 assistant 消息之后 + +### 4.2 Encoder（Canonical → Anthropic） + +#### 模型名称 + +使用 `provider.model_name` 覆盖 `canonical.model`。 + +#### 系统消息注入 + +``` +encodeSystem(system): + if system is String: return system + return system.map(s => ({text: s.text})) +``` + +将 `canonical.system` 编码为 Anthropic 顶层 `system` 字段。 + +#### 消息编码 + +**关键差异**：Canonical 的 `tool` 角色消息需要合并到 Anthropic 的 `user` 消息中： + +``` +encodeMessages(canonical): + result = [] + for msg in canonical.messages: + switch msg.role: + case "user": + result.append({role: "user", content: encodeContentBlocks(msg.content)}) + case "assistant": + result.append({role: "assistant", content: encodeContentBlocks(msg.content)}) + case "tool": + // tool 角色转为 Anthropic 的 user 消息内 tool_result 块 + toolResults = msg.content.filter(b => b.type == "tool_result") + if result.length > 0 && result.last.role == "user": + result.last.content = result.last.content + toolResults + else: + result.append({role: "user", content: toolResults}) +``` + +#### 角色约束处理 + +Anthropic 要求 user/assistant 严格交替。编码时需要： +1. 将 Canonical `tool` 角色合并到相邻 `user` 消息中 +2. 确保首条消息为 `user` 角色（若无，自动注入空 user 消息） +3. 合并连续同角色消息 + +#### 工具编码 + +``` +encodeTools(canonical): + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + name: t.name, description: t.description, input_schema: t.input_schema})) + +encodeToolChoice(choice): + switch choice.type: + "auto" → {type: "auto"} + "none" → {type: "none"} + "any" → {type: "any"} + "tool" → {type: "tool", name: choice.name} +``` + +#### 公共字段编码 + +``` +encodeRequest(canonical, provider): + result = { + model: provider.model_name, + messages: encodeMessages(canonical), + max_tokens: canonical.parameters.max_tokens, + temperature: canonical.parameters.temperature, + top_p: canonical.parameters.top_p, + top_k: canonical.parameters.top_k, + stream: canonical.stream + } + if canonical.system: + result.system = encodeSystem(canonical.system) + if canonical.parameters.stop_sequences: + result.stop_sequences = canonical.parameters.stop_sequences + if canonical.user_id: + result.metadata = {user_id: canonical.user_id} + if canonical.output_format or canonical.thinking?.effort: + result.output_config = {} + if canonical.output_format: + result.output_config.format = encodeOutputFormat(canonical.output_format) + if canonical.thinking?.effort: + result.output_config.effort = canonical.thinking.effort + if canonical.parallel_tool_use == false: + result.disable_parallel_tool_use = true + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + name: t.name, description: t.description, input_schema: t.input_schema})) + if canonical.tool_choice: + result.tool_choice = encodeToolChoice(canonical.tool_choice) + if canonical.thinking: + result.thinking = encodeThinkingConfig(canonical.thinking) + return result + +encodeThinkingConfig(canonical): + switch canonical.type: + "enabled": + cfg = {type: "enabled", budget_tokens: canonical.budget_tokens} + return cfg + "disabled": + return {type: "disabled"} + "adaptive": + return {type: "adaptive"} + return {type: "disabled"} + +encodeOutputFormat(output_format): + switch output_format.type: + "json_schema": + return {type: "json_schema", schema: output_format.json_schema.schema} + "json_object": + return {type: "json_schema", schema: {type: "object"}} +``` + +#### 降级处理 + +对照架构文档 §8.4 三级降级策略，确认每个不支持字段的处理： + +| Canonical 字段 | Anthropic 不支持时 | 降级策略 | +|---------------|-------------------|---------| +| `thinking.effort` | Anthropic 通过 `output_config.effort` 传递 | 自动映射为 `output_config.effort` | +| `stop_reason: "content_filter"` | Anthropic 无此值 | 自动映射为 `"end_turn"` | +| `output_format: "text"` | Anthropic 无 text 输出格式 | 丢弃，不设置 output_config | +| `output_format: "json_object"` | Anthropic 用 json_schema 替代 | 替代方案：生成空 schema 的 json_schema | + +--- + +## 5. 核心层 — Chat 响应编解码 + +逐字段对照 §4.7 CanonicalResponse 确认映射关系。 + +### 5.1 响应结构 + +``` +Anthropic 响应顶层结构: +{ + id: String, + type: "message", + role: "assistant", + model: String, + content: [ContentBlock...], + stop_reason: String, + stop_sequence: String | null, + stop_details: Object | null, + container: Object | null, + usage: { input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, + cache_creation?, inference_geo?, server_tool_use?, service_tier? } +} +``` + +**新增字段**（对比 §4.7 CanonicalResponse）： + +| Anthropic 字段 | 说明 | +|----------------|------| +| `stop_details` | 结构化拒绝信息：`{type: "refusal", category, explanation}`，仅 `stop_reason == "refusal"` 时存在 | +| `container` | 容器信息：`{id, expires_at}`，仅使用 code execution 工具时存在 | + +### 5.2 Decoder（Anthropic → Canonical） + +``` +decodeResponse(anthropicResp): + blocks = [] + for block in anthropicResp.content: + switch block.type: + "text" → blocks.append({type: "text", text: block.text}) + "tool_use" → blocks.append({type: "tool_use", id: block.id, name: block.name, input: block.input}) + "thinking" → blocks.append({type: "thinking", thinking: block.thinking}) + "redacted_thinking" → 丢弃 // 仅 Anthropic 使用，不在中间层保留 + return CanonicalResponse {id, model, content: blocks, stop_reason: mapStopReason(anthropicResp.stop_reason), + usage: CanonicalUsage {input_tokens, output_tokens, + cache_read_tokens: anthropicResp.usage.cache_read_input_tokens, + cache_creation_tokens: anthropicResp.usage.cache_creation_input_tokens}} +``` + +**内容块解码**： +- `text` → TextBlock（直接映射；忽略 `citations` 字段） +- `tool_use` → ToolUseBlock（直接映射；忽略 `caller` 字段） +- `thinking` → ThinkingBlock（直接映射；忽略 `signature` 字段） +- `redacted_thinking` → 丢弃（协议特有，不晋升为公共字段） +- `server_tool_use` / `web_search_tool_result` / `code_execution_tool_result` 等 → 丢弃（服务端工具块，协议特有） + +**停止原因映射**： + +| Anthropic stop_reason | Canonical stop_reason | 说明 | +|-----------------------|-----------------------|------| +| `"end_turn"` | `"end_turn"` | 直接映射 | +| `"max_tokens"` | `"max_tokens"` | 直接映射 | +| `"tool_use"` | `"tool_use"` | 直接映射 | +| `"stop_sequence"` | `"stop_sequence"` | 直接映射 | +| `"pause_turn"` | `"pause_turn"` | 长轮次暂停，映射为 Canonical 新增值 | +| `"refusal"` | `"refusal"` | 安全拒绝，直接映射 | + +**Token 用量映射**： + +| Anthropic usage | Canonical Usage | 说明 | +|-----------------|-----------------|------| +| `input_tokens` | `input_tokens` | 直接映射 | +| `output_tokens` | `output_tokens` | 直接映射 | +| `cache_read_input_tokens` | `cache_read_tokens` | 字段名映射 | +| `cache_creation_input_tokens` | `cache_creation_tokens` | 字段名映射 | +| `cache_creation` | — | 协议特有（按 TTL 细分），不晋升 | +| `inference_geo` | — | 协议特有，不晋升 | +| `server_tool_use` | — | 协议特有，不晋升 | +| `service_tier` | — | 协议特有，不晋升 | +| — | `reasoning_tokens` | Anthropic 不返回此字段，始终为 null | + +**协议特有内容**： + +| 字段 | 处理方式 | +|------|---------| +| `redacted_thinking` | 解码时丢弃 | +| `stop_sequence` | 解码时忽略（Canonical 用 stop_reason 覆盖） | +| `stop_details` | 解码时忽略（协议特有，不晋升） | +| `container` | 解码时忽略（协议特有，不晋升） | +| `text.citations` | 解码时忽略（协议特有，不晋升） | +| `tool_use.caller` | 解码时忽略（协议特有，不晋升） | +| `thinking.signature` | 解码时忽略（协议特有，不晋升；同协议透传时自然保留） | + +### 5.3 Encoder（Canonical → Anthropic） + +``` +encodeResponse(canonical): + blocks = canonical.content.map(block => { + switch block.type: + "text" → {type: "text", text: block.text} + "tool_use" → {type: "tool_use", id: block.id, name: block.name, input: block.input} + "thinking" → {type: "thinking", thinking: block.thinking}}) + return {id: canonical.id, type: "message", role: "assistant", model: canonical.model, + content: blocks, + stop_reason: mapCanonicalStopReason(canonical.stop_reason), + stop_sequence: None, + usage: {input_tokens: canonical.usage.input_tokens, output_tokens: canonical.usage.output_tokens, + cache_read_input_tokens: canonical.usage.cache_read_tokens, + cache_creation_input_tokens: canonical.usage.cache_creation_tokens}} +``` + +**内容块编码**： +- TextBlock → `{type: "text", text}`（直接映射） +- ToolUseBlock → `{type: "tool_use", id, name, input}`（直接映射） +- ThinkingBlock → `{type: "thinking", thinking}`（直接映射） + +**停止原因映射**： + +| Canonical stop_reason | Anthropic stop_reason | +|-----------------------|-----------------------| +| `"end_turn"` | `"end_turn"` | +| `"max_tokens"` | `"max_tokens"` | +| `"tool_use"` | `"tool_use"` | +| `"stop_sequence"` | `"stop_sequence"` | +| `"pause_turn"` | `"pause_turn"` | +| `"refusal"` | `"refusal"` | +| `"content_filter"` | `"end_turn"`（降级） | + +**降级处理**： + +| Canonical 字段 | Anthropic 不支持时 | 降级策略 | +|---------------|-------------------|---------| +| `stop_reason: "content_filter"` | Anthropic 无此值 | 自动映射为 `"end_turn"` | +| `reasoning_tokens` | Anthropic 无此字段 | 丢弃 | + +**协议特有内容**： + +| 字段 | 处理方式 | +|------|---------| +| `redacted_thinking` | 编码时不产出 | +| `stop_sequence` | 编码时始终为 null | +| `stop_details` | 编码时不产出 | +| `container` | 编码时不产出 | +| `text.citations` | 编码时不产出 | +| `thinking.signature` | 编码时不产出（同协议透传时自然保留） | + +--- + +## 6. 核心层 — 流式编解码 + +### 6.1 SSE 格式 + +Anthropic 使用命名 SSE 事件，与 CanonicalStreamEvent 几乎 1:1 对应： + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_xxx","model":"claude-4",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":10}} + +event: message_stop +data: {"type":"message_stop"} + +event: ping +data: {"type":"ping"} +``` + +### 6.2 StreamDecoder（Anthropic SSE → Canonical 事件） + +Anthropic SSE 事件与 CanonicalStreamEvent 几乎 1:1 映射，状态机最简单： + +| Anthropic SSE 事件 | Canonical 事件 | 说明 | +|---|---|---| +| `message_start` | MessageStartEvent | 直接映射 | +| `content_block_start` | ContentBlockStartEvent | 直接映射 content_block | +| `content_block_delta` | ContentBlockDeltaEvent | 见下方 delta 类型映射表 | +| `content_block_stop` | ContentBlockStopEvent | 直接映射 | +| `message_delta` | MessageDeltaEvent | 直接映射 delta 和 usage | +| `message_stop` | MessageStopEvent | 直接映射 | +| `ping` | PingEvent | 直接映射 | +| `error` | ErrorEvent | 直接映射 | + +**delta 类型映射**（`content_block_delta` 事件内）： + +| Anthropic delta 类型 | Canonical delta 类型 | 说明 | +|---------------------|---------------------|------| +| `text_delta` | `{type: "text_delta", text}` | 直接映射 | +| `input_json_delta` | `{type: "input_json_delta", partial_json}` | 直接映射 | +| `thinking_delta` | `{type: "thinking_delta", thinking}` | 直接映射 | +| `citations_delta` | 丢弃 | 协议特有，不晋升为公共字段 | +| `signature_delta` | 丢弃 | 协议特有（用于多轮思考签名连续性），不晋升 | + +**content_block_start 类型映射**： + +| Anthropic content_block 类型 | Canonical content_block | 说明 | +|------------------------------|----------------------|------| +| `{type: "text", text: ""}` | `{type: "text", text: ""}` | 直接映射 | +| `{type: "tool_use", id, name, input: {}}` | `{type: "tool_use", id, name, input: {}}` | 直接映射 | +| `{type: "thinking", thinking: ""}` | `{type: "thinking", thinking: ""}` | 直接映射 | +| `{type: "redacted_thinking", data: ""}` | 丢弃整个 block | 跳过后续 delta 直到 content_block_stop | +| `server_tool_use` / `web_search_tool_result` 等 | 丢弃 | 服务端工具块，协议特有 | + +### 6.3 StreamDecoder 状态机 + +``` +StreamDecoderState { + messageStarted: Boolean + openBlocks: Set + currentBlockType: Map + currentBlockId: Map + redactedBlocks: Set // 追踪需要丢弃的 redacted_thinking block + utf8Remainder: Option // UTF-8 跨 chunk 安全 + accumulatedUsage: Option +} +``` + +Anthropic Decoder 无需 OpenAI 的 `toolCallIdMap` / `toolCallNameMap` / `toolCallArguments`，因为 Anthropic 的事件已经有明确的结构。 + +**关键处理**： + +- **`redacted_thinking`**：在 `content_block_start` 事件中检测类型，将 index 加入 `redactedBlocks`，后续 delta 和 stop 事件均丢弃 +- **`citations_delta` / `signature_delta`**：在 delta 映射时直接丢弃，不影响 block 生命周期 +- **`server_tool_use` 等服务端工具块**：与 `redacted_thinking` 处理方式一致，加入 `redactedBlocks` 丢弃 +- **UTF-8 安全**：跨 chunk 截断的 UTF-8 字节需要用 `utf8Remainder` 缓冲 +- **usage 累积**：`message_delta` 中的 usage 与 `message_start` 中的 usage 合并 + +### 6.4 StreamEncoder（Canonical → Anthropic SSE） + +| Canonical 事件 | Anthropic SSE 事件 | 说明 | +|---|---|---| +| MessageStartEvent | `event: message_start` | 直接映射 | +| ContentBlockStartEvent | `event: content_block_start` | 直接映射 content_block | +| ContentBlockDeltaEvent | `event: content_block_delta` | 见下方 delta 编码表 | +| ContentBlockStopEvent | `event: content_block_stop` | 直接映射 | +| MessageDeltaEvent | `event: message_delta` | 直接映射 | +| MessageStopEvent | `event: message_stop` | 直接映射 | +| PingEvent | `event: ping` | 直接映射 | +| ErrorEvent | `event: error` | 直接映射 | + +**delta 编码表**： + +| Canonical delta 类型 | Anthropic delta 类型 | 说明 | +|---------------------|---------------------|------| +| `{type: "text_delta", text}` | `text_delta` | 直接映射 | +| `{type: "input_json_delta", partial_json}` | `input_json_delta` | 直接映射 | +| `{type: "thinking_delta", thinking}` | `thinking_delta` | 直接映射 | + +**缓冲策略**：无需缓冲，每个 Canonical 事件直接编码为对应的 Anthropic SSE 事件。 + +**SSE 编码格式**： + +``` +event: \n +data: \n +\n +``` + +--- + +## 7. 扩展层接口 + +### 7.1 /models & /models/{model} + +**列表接口** `GET /v1/models`： + +| 项目 | 说明 | +|------|------| +| 接口是否存在 | 是 | +| 请求格式 | GET 请求，支持 `limit`、`after_id`、`before_id` 查询参数 | + +响应 Decoder（Anthropic → Canonical）： + +``` +decodeModelsResponse(anthropicResp): + return CanonicalModelList { + models: anthropicResp.data.map(m => CanonicalModel { + id: m.id, name: m.display_name ?? m.id, created: parseTimestamp(m.created_at), + owned_by: "anthropic"})} + +parseTimestamp(timestamp): + // Anthropic 返回 RFC 3339 字符串（如 "2025-05-14T00:00:00Z"），需转为 Unix 时间戳 + return rfc3339ToUnix(timestamp) ?? 0 +``` + +响应 Encoder（Canonical → Anthropic）： + +``` +encodeModelsResponse(canonical): + return {data: canonical.models.map(m => ({ + id: m.id, + display_name: m.name ?? m.id, + created_at: m.created ? unixToRfc3339(m.created) : epochRfc3339(), + type: "model"})), + has_more: false, + first_id: canonical.models[0]?.id, last_id: canonical.models.last?.id} +``` + +**详情接口** `GET /v1/models/{model}`： + +| 项目 | 说明 | +|------|------| +| 接口是否存在 | 是 | +| 请求格式 | GET 请求，路径参数 `model_id` | + +响应 Decoder（Anthropic → Canonical）： + +``` +decodeModelInfoResponse(anthropicResp): + return CanonicalModelInfo { + id: anthropicResp.id, name: anthropicResp.display_name ?? anthropicResp.id, + created: parseTimestamp(anthropicResp.created_at), owned_by: "anthropic" } +``` + +响应 Encoder（Canonical → Anthropic）： + +``` +encodeModelInfoResponse(canonical): + return {id: canonical.id, + display_name: canonical.name ?? canonical.id, + created_at: canonical.created ? unixToRfc3339(canonical.created) : epochRfc3339(), + type: "model"} +``` + +**字段映射**（列表和详情共用）： + +| Anthropic | Canonical | 说明 | +|-----------|-----------|------| +| `data[].id` | `models[].id` | 直接映射 | +| `data[].display_name` | `models[].name` | Anthropic 特有的显示名称 | +| `data[].created_at` | `models[].created` | **类型转换**：Anthropic 为 RFC 3339 字符串，Canonical 为 Unix 时间戳 | +| `data[].type: "model"` | — | 固定值 | +| `has_more` | — | 编码时固定为 false | +| `first_id` / `last_id` | — | 从列表提取 | +| `data[].capabilities` | — | 协议特有，不晋升 | +| `data[].max_input_tokens` | — | 协议特有，不晋升 | +| `data[].max_tokens` | — | 协议特有，不晋升 | + +**跨协议对接示例**（入站 `/anthropic/v1/models`，目标 OpenAI）： + +``` +入站: GET /anthropic/v1/models, x-api-key: sk-ant-xxx + → client=anthropic, provider=openai + → URL: /v1/models, Headers: Authorization: Bearer sk-xxx + +OpenAI 上游响应: {object: "list", data: [{id: "gpt-4o", object: "model", created: 1700000000, owned_by: "openai"}]} + → OpenAI.decodeModelsResponse → CanonicalModelList + → Anthropic.encodeModelsResponse + +返回客户端: {data: [{id: "gpt-4o", display_name: "gpt-4o", created_at: "2023-11-04T18:26:40Z", type: "model"}], + has_more: false, first_id: "gpt-4o", last_id: "gpt-4o"} +``` + +--- + +## 8. 错误编码 + +### 8.1 错误响应格式 + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "Error message" + } +} +``` + +### 8.2 encodeError + +``` +Anthropic.encodeError(error): + return {type: "error", error: {type: error.code, message: error.message}} +``` + +### 8.3 常用 HTTP 状态码 + +| HTTP Status | 说明 | +|-------------|------| +| 400 | 请求格式错误 | +| 401 | 认证失败（无效 API key） | +| 403 | 无权限访问 | +| 404 | 接口不存在 | +| 429 | 速率限制 | +| 500 | 服务器内部错误 | +| 529 | 服务过载 | + +--- + +## 9. 自检清单 + +| 章节 | 检查项 | +|------|--------| +| §2 | [x] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | +| §2 | [x] 所有 InterfaceType 的 `buildUrl` 映射已确定 | +| §3 | [x] `buildHeaders(provider)` 已实现，adapter_config 契约已文档化 | +| §4 | [x] Chat 请求的 Decoder 和 Encoder 已实现（逐字段对照 §4.1/§4.2） | +| §4 | [x] 角色映射和消息顺序约束已处理（tool→user 合并、首消息 user 保证、交替约束） | +| §4 | [x] 工具调用（tool_use / tool_result）的编解码已处理 | +| §4 | [x] 协议特有字段已识别并确定处理方式（cache_control 忽略、redacted_thinking 丢弃） | +| §5 | [x] Chat 响应的 Decoder 和 Encoder 已实现（逐字段对照 §4.7） | +| §5 | [x] stop_reason 映射表已确认 | +| §5 | [x] usage 字段映射已确认（input_tokens / cache_read_input_tokens 等） | +| §6 | [x] 流式 StreamDecoder 和 StreamEncoder 已实现（对照 §4.8） | +| §7 | [x] 扩展层接口的编解码已实现（/models、/models/{model}） | +| §8 | [x] `encodeError` 已实现 | diff --git a/docs/conversion_design.md b/docs/conversion_design.md index 139b95b..f1a3925 100644 --- a/docs/conversion_design.md +++ b/docs/conversion_design.md @@ -1,6 +1,6 @@ # LLM API Protocol Conversion Layer — Architecture Design -> 语言无关的 HTTP 层 SDK。以 Hub-and-Spoke 架构实现 OpenAI / Anthropic 协议间的双向转换，覆盖完整 HTTP 接口体系，同协议自动透传，为新协议和多模态预留扩展点。 +> 语言无关的 HTTP 层 SDK。以 Hub-and-Spoke 架构实现多协议间的双向转换，覆盖完整 HTTP 接口体系，同协议自动透传，为新协议和多模态预留扩展点。 --- @@ -13,12 +13,13 @@ 5. [Protocol Adapter 接口](#5-protocol-adapter-接口) 6. [Conversion Engine（转换引擎）](#6-conversion-engine转换引擎) 7. [流式转换架构](#7-流式转换架构) -8. [OpenAI 协议适配器](#8-openai-协议适配器) -9. [Anthropic 协议适配器](#9-anthropic-协议适配器) -10. [字段映射参考](#10-字段映射参考) -11. [扩展点设计](#11-扩展点设计) -12. [错误处理](#12-错误处理) -13. [参考实现对比](#13-参考实现对比) +8. [扩展点设计](#8-扩展点设计) +9. [错误处理](#9-错误处理) +10. [附录 A：模块依赖](#附录-a模块依赖) +11. [附录 B：接口速查](#附录-b接口速查) +12. [附录 C：字段晋升规范](#附录-c字段晋升规范) +13. [附录 D：协议适配清单模板](#附录-d协议适配清单模板) +14. [附录 E：协议适配文档索引](#附录-e协议适配文档索引) --- @@ -28,9 +29,9 @@ | 目标 | 说明 | |------|------| -| **完整 HTTP 接口体系转换** | 覆盖 /models、/embeddings、/files、/rerank 等全部接口的 URL 路由映射、请求头转换、请求体/响应体格式转换 | -| **输入输出解耦** | 客户端协议和上游协议独立指定，任意组合 | -| **同协议透传** | source == target 时跳过转换，零语义损失、零序列化开销 | +| **完整 HTTP 接口体系转换** | 覆盖 /models、/embeddings、/rerank 等全部接口的 URL 路由映射、请求头转换、请求体/响应体格式转换 | +| **输入输出解耦** | 客户端协议和服务端协议独立指定，任意组合 | +| **同协议透传** | client == provider 时跳过转换，零语义损失、零序列化开销 | | **尽力转换** | 能对接的参数尽可能对接，不能对接的各自忽略，保障最大覆盖面 | | **协议可扩展** | 添加新协议只需实现 Adapter，不修改核心引擎 | | **流式优先** | SSE 流式转换作为核心能力，与非流式同等地位 | @@ -42,8 +43,7 @@ | 约束 | 说明 | |------|------| | 部署形态 | HTTP 层 SDK，处理 HTTP 请求/响应转换（URL + Headers + Body），不包含 HTTP 服务器启动/监听 | -| 当前协议 | OpenAI API、Anthropic API | -| 当前模态 | 仅文本（含 Tool Calling），接口体系覆盖 /models、/count_tokens、/embeddings、/files、/rerank | +| 当前模态 | 仅文本（含 Tool Calling），接口体系覆盖 /models、/embeddings、/rerank | | Provider 必传 | 每次转换调用需传入 TargetProvider，提供目标上游的地址、认证、模型名等信息 | | 适配器注册 | 所有 ProtocolAdapter 通过代码注册，不支持动态增减 | | 有状态特性 | 初始不实现，架构预留扩展点 | @@ -52,12 +52,12 @@ | 决策 | 依据 | |------|------| -| HTTP 层 SDK | 编程工具启动时调用 /models、/count_tokens 等接口，缺失会报错或功能降级 | -| Hub-and-Spoke | new-api 验证了以规范格式为枢纽的可行性，O(n²) 降为 O(n) | +| HTTP 层 SDK | 编程工具启动时调用 /models 等接口，缺失会报错或功能降级 | +| Hub-and-Spoke | 以规范格式为枢纽，将 O(n²) 的协议对转换降为 O(n) | | 自定义 Canonical Model | 不选用厂商格式，避免语义损失和厂商锁定 | -| 协议前缀路由 | CC-Switch 的 `/claude/`、`/codex/`、`/gemini/` 前缀验证了 URL 前缀区分协议的可行性 | +| 协议识别外部化 | 协议识别是调用方职责，引擎不绑定具体识别方式 | | 接口分层 + 尽力转换 | 不同接口差异程度不同，分层处理最大化覆盖面 | -| 同协议透传 | CC-Switch 的 Anthropic→Anthropic 直通验证了零转换性能优势 | +| 同协议透传 | 零转换的性能优势已验证 | --- @@ -69,89 +69,81 @@ ┌─────────────────────────────────────────────────────────────────────────┐ │ 上层 HTTP 框架（用户自选） │ │ Express / FastAPI / Axum / Gin / 任意框架 │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ 协议识别 + 前缀剥离（调用方职责） │ │ +│ │ │ │ +│ │ 入站: /{protocol}/{native_path} │ │ +│ │ │ │ +│ │ //v1/chat/completions → client=protocol_a, /v1/... │ │ +│ │ //v1/messages → client=protocol_b, /v1/... │ │ +│ │ │ │ +│ │ Step 1: 识别 client protocol（URL 前缀 / 配置映射 / 任意方式） │ │ +│ │ Step 2: 剥离前缀 → 得到 nativePath │ │ +│ │ Step 3: 确定 provider protocol（配置决定） │ │ +│ └─────────────────────────────┬───────────────────────────────────┘ │ └───────────────────────────────┬─────────────────────────────────────────┘ - │ HTTP 请求/响应 + │ nativePath + clientProtocol + providerProtocol ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Conversion Engine (SDK) │ │ │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ Protocol Prefix Router │ │ -│ │ │ │ -│ │ 入站: /{protocol}/{native_path} │ │ -│ │ │ │ -│ │ /openai/v1/chat/completions → source=openai, CHAT │ │ -│ │ /anthropic/v1/messages → source=anthropic, CHAT │ │ -│ │ /openai/v1/models → source=openai, MODELS │ │ -│ │ /anthropic/v1/models → source=anthropic, MODELS │ │ -│ │ /openai/v1/* → source=openai, UNKNOWN │ │ -│ │ /anthropic/v1/* → source=anthropic, UNKNOWN │ │ -│ │ │ │ -│ │ Step 1: URL 前缀 → source protocol（唯一依据，无歧义） │ │ -│ │ Step 2: 剥离前缀 → 识别 InterfaceType │ │ -│ │ Step 3: target protocol 由配置决定 │ │ -│ └─────────────────────────────┬───────────────────────────────────┘ │ -│ │ │ │ ┌────────────┼────────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────────┐ ┌─────────┐ ┌──────────┐ │ │ │ Passthrough │ │核心接口层│ │扩展接口层 │ │ │ │ 同协议直通 │ │ Chat │ │ Models │ │ │ │ 或未知接口 │ │ 流式 │ │ Embed │ │ -│ │ 直接转发 │ │ Tool │ │ Files │ │ -│ └──────────────┘ │ Thinking│ │ Rerank │ │ -│ └────┬────┘ └────┬─────┘ │ -│ ┌──────────▼──────────▼───────┐ │ -│ │ ProtocolAdapter 层 │ │ -│ │ ┌────────┐ ┌───────────┐ │ │ -│ │ │OpenAI │ │Anthropic │ │ │ -│ │ │Adapter │ │Adapter │ │ │ -│ │ └────────┘ └───────────┘ │ │ -│ └──────────────┬───────────────┘ │ -│ ┌──────────────▼───────────────┐ │ -│ │ Canonical Model │ │ -│ └──────────────────────────────┘ │ +│ │ 直接转发 │ │ Tool │ │ Rerank │ │ +│ └──────────────┘ │ Thinking│ └──────────┘ │ +│ └────┬────┘ │ +│ ┌──────────▼───────────────┐ │ +│ │ ProtocolAdapter 层 │ │ +│ │ ┌────────┐ ┌─────────┐ │ │ +│ │ │Protocol│ │Protocol │ │ │ +│ │ │ A │ │ B │ │ │ +│ │ └────────┘ └─────────┘ │ │ +│ └──────────────┬────────────┘ │ +│ ┌──────────────▼────────────┐ │ +│ │ Canonical Model │ │ +│ └───────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### 2.2 URL 路由规则 -入站 URL 采用协议前缀：`/{protocol}/{native_path}`。前缀是协议识别的**唯一依据**。 +调用方负责识别协议并剥离前缀，将 `nativePath`、`clientProtocol`、`providerProtocol` 传入引擎。调用方可自行决定识别方式（URL 前缀、配置映射等）。 ``` -入站 URL 剥离前缀后 出站（target=anthropic） -────────────────────────────────────────────────────────────────────────────────── -/openai/v1/chat/completions → /v1/chat/completions → /v1/messages -/anthropic/v1/messages → /v1/messages → /v1/chat/completions -/openai/v1/models → /v1/models → /v1/models -/anthropic/v1/models → /v1/models → /v1/models -/openai/v1/embeddings → /v1/embeddings → 不支持，透传或返回错误 -/anthropic/v1/messages/count_tokens→ /v1/messages/count_tokens→ OpenAI 无此接口 +入站 URL 调用方剥离前缀后 引擎出站 +────────────────────────────────────────────────────────────────────────────── +//v1/chat/completions → /v1/chat/completions → 目标协议路径 +//v1/messages → /v1/messages → 目标协议路径 +//v1/models → /v1/models → /v1/models（通常不变） ``` -协议前缀仅用于入站侧。出站到上游 API 时使用目标协议原生路径（无前缀）。 +出站到上游 API 时使用服务端协议原生路径（无前缀）。 ### 2.3 请求处理流程 每个 HTTP 请求的转换流程： ``` -客户端入站 SDK 内部处理 上游出站 +客户端入站 调用方（协议识别+前缀剥离） SDK 内部处理 上游出站 ┌──────────────────┐ ┌──────────────────┐ -│ URL: │ 1. 前缀提取: /anthropic/ → source=anthropic │ URL: │ -│ /anthropic/ │ 2. 前缀剥离: /v1/messages │ /v1/chat/ │ -│ v1/messages │ 3. 接口识别: CHAT │ completions │ -│ Headers: │ 4. 同协议? ──yes──▶ 剥离前缀后直接转发 │ Headers: │ -│ x-api-key │ └──no──▶ 继续转换 │ Authorization │ -│ Body: │ 5. URL 映射: /v1/messages → /v1/chat/completions │ Body: │ -│ {model,system, │ 6. Header 转换: x-api-key → Authorization: Bearer │ {model,messages,│ -│ messages,...} │ 7. Body 转换: Anthropic → Canonical → OpenAI │ tools,...} │ +│ URL: │ 调用方完成: 1. 接口识别: CHAT │ URL: │ +│ // │ · clientProtocol 2. 同协议? ──yes──▶ 直接转发│ 目标协议 │ +│ v1/... │ · nativePath └──no──▶ 继续转换 │ 原生路径 │ +│ Headers: │ · providerProtocol 3. URL 映射: 目标路径 │ Headers: │ +│ 协议原生格式 │ 4. Header 构建: 目标格式 │ 目标协议格式 │ +│ Body: │ 5. Body 转换: D→C→E │ Body: │ +│ 协议原生格式 │ │ 目标协议格式 │ └──────────────────┘ └──────────────────┘ ``` -响应方向同理（含流式）。 +响应方向同理（含流式）。D=Decoder, C=Canonical, E=Encoder。 -**同协议透传**：source == target 时，仅剥离前缀后原样转发到上游。 +**同协议透传**：client == provider 时，仅重建 Header 后原样转发到上游。 **未知接口透传**：无法识别的路径，URL+Header 适配后 Body 原样转发。 --- @@ -162,47 +154,18 @@ | 层级 | 接口 | 转换方式 | |------|------|---------| -| **核心层** | Chat Completions, Messages | Canonical Model 深度转换 | -| **扩展层** | /models, /embeddings, /files, /rerank, /count_tokens | 轻量级字段映射 | -| **透传层** | /batches, /fine-tuning, /audio/*, /images/*, /video/*, /moderations 等未知路径 | URL+Header 适配后 Body 原样转发 | +| **核心层** | Chat 接口（各协议的核心对话接口） | Canonical Model 深度转换 | +| **扩展层** | /models, /models/{model}, /embeddings, /rerank | 轻量级字段映射 | +| **透传层** | /files, /count_tokens, /batches, /fine-tuning, /audio/*, /images/*, /video/*, /moderations 等未知路径 | URL+Header 适配后 Body 原样转发 | **接口纳入原则**：只有 ≥2 个协议提供相同功能的接口才纳入转换层（核心层或扩展层），其余走透传。 **尽力转换策略**： - 双方都支持且可映射 → 完整转换（如 /models） -- 目标协议不支持该接口 → 透传到上游或返回空响应/错误（可配置） +- 服务端协议不支持该接口 → 透传到上游或返回空响应/错误（可配置） - 未知接口 → 始终透传 -### 3.2 OpenAI 接口体系 - -``` -OpenAI API -├── /v1/chat/completions [核心层] -├── /v1/models [扩展层] -├── /v1/models/{model} [扩展层] -├── /v1/embeddings [扩展层] -├── /v1/files [扩展层] -├── /v1/files/{id}/content [扩展层] -├── /v1/rerank [扩展层] -├── /v1/batches [透传层] -├── /v1/fine_tuning/jobs [透传层] -├── /v1/audio/* [透传层] -├── /v1/images/* [透传层] -├── /v1/moderations [透传层] -├── /v1/realtime [透传层] -└── /v1/* [透传层] -``` - -### 3.3 Anthropic 接口体系 - -``` -Anthropic API -├── /v1/messages [核心层] -├── /v1/messages/count_tokens [扩展层] -├── /v1/models [扩展层] -├── /v1/batches [扩展层] -└── /v1/* [透传层] -``` +**各协议的接口清单**详见各自的协议适配文档（附录 E）。 --- @@ -210,7 +173,9 @@ Anthropic API 协议无关的统一内部表示，Hub-and-Spoke 架构的枢纽。**核心层**使用完整 Canonical Model 深度转换；**扩展层**使用轻量 Canonical Models 做字段映射；**透传层**不使用。 -设计原则：超集设计、类型化 discriminated union、前向兼容。Canonical Model 面向当前已适配协议（OpenAI、Anthropic）的公共语义进行抽象，字段随协议扩展演进（详见附录 D：字段晋升规范）。 +设计原则：超集设计、类型化 discriminated union、前向兼容。Canonical Model 面向当前已适配协议的公共语义进行抽象，字段随协议扩展演进（详见附录 C：字段晋升规范）。 + +**适配新协议时**：对照本节定义逐字段确认映射关系。协议特有字段不纳入 Canonical，同协议透传时自然保留，跨协议时丢弃（详见附录 C 字段分类规则）。 ### 4.1 CanonicalRequest @@ -242,6 +207,9 @@ RequestParameters { max_tokens: Option temperature: Option top_p: Option + top_k: Option + frequency_penalty: Option + presence_penalty: Option stop_sequences: Option> } ``` @@ -289,9 +257,9 @@ ToolChoice = Union< ``` ThinkingConfig { - type: Enum // Anthropic 启用时 budget_tokens 必填 - budget_tokens: Option // Anthropic: thinking tokens 不计入 max_tokens - effort: Option> // OpenAI + type: Enum + budget_tokens: Option // token 级控制 + effort: Option> // 抽象级别控制 } ``` @@ -312,7 +280,7 @@ CanonicalResponse { id: String model: String content: Array - stop_reason: Option // end_turn | max_tokens | tool_use | stop_sequence | content_filter + stop_reason: Option // end_turn | max_tokens | tool_use | stop_sequence | content_filter | refusal usage: CanonicalUsage } @@ -325,9 +293,9 @@ CanonicalUsage { } ``` -### 4.7 CanonicalStreamEvent +### 4.8 CanonicalStreamEvent -采用 Anthropic 风格的类型化事件模型（比 OpenAI delta 模型语义更明确，双向转换更容易）： +采用类型化事件模型，具有显式的 start/stop 生命周期，语义明确，便于任意协议间的双向转换： ``` CanonicalStreamEvent = Union< @@ -356,45 +324,35 @@ delta: Union< > ``` -### 4.8 扩展层 Canonical Models +### 4.9 扩展层 Canonical Models ``` // /models CanonicalModelList { models: Array } CanonicalModel { id, name, created, owned_by } +// /models/{model} +CanonicalModelInfo { id, name, created, owned_by } + // /embeddings CanonicalEmbeddingRequest { model, input, encoding_format?, dimensions? } CanonicalEmbeddingResponse { data: [{index, embedding}], model, usage } -// /count_tokens -CanonicalTokenCountRequest { model, messages, system?, tools? } -CanonicalTokenCountResponse { input_tokens } - -// /files -CanonicalFileObject { id, object, filename?, bytes?, created_at?, purpose?, status? } - // /rerank CanonicalRerankRequest { model, query, documents, top_n?, return_documents? } CanonicalRerankResponse { results: [{index, relevance_score, document?}], model } ``` -### 4.9 设计说明 +### 4.10 设计说明 **`system` 为什么独立于 `messages`？** -Anthropic 用顶层 `system` 字段，OpenAI 用 `messages[role="system"]`。独立 `system` 语义更清晰，Decoder 提取、Encoder 注入。 +不同协议对系统消息的处理方式不同：有的用顶层字段，有的嵌入 messages 数组。独立 `system` 语义更清晰，Decoder 提取、Encoder 注入，适配时按各自协议规范处理即可。 -**流式事件为什么用 Anthropic 风格？** -类型化事件有显式的 start/stop 生命周期，语义明确；OpenAI delta 模型需要状态机推断语义，双向转换更复杂。 +**流式事件为什么用类型化事件模型？** +类型化事件有显式的 start/stop 生命周期，语义明确。delta 模型需要状态机推断语义，增加双向转换的复杂度。新协议适配时，如协议原生支持类似生命周期，直接映射；如使用 delta 模型，需在 StreamDecoder 中用状态机转换。 -**`user_id` 为什么从 `metadata` 中提升？** -OpenAI 用顶层 `user`，Anthropic 用 `metadata.user_id`。两者语义相同，提升为独立字段更清晰。 - -**`output_format` 为什么替代 `response_format`？** -OpenAI 的 `response_format` 和 Anthropic 新模型的 `output_format` 表达相同意图（控制输出格式），统一为 `output_format` 避免命名偏向。 - -**`parallel_tool_use` 为什么独立为顶层字段？** -OpenAI 用 `parallel_tool_calls`（允许），Anthropic 用 `disable_parallel_tool_use`（禁止），语义反转但表达相同控制。统一为正向语义。 +**`user_id`、`output_format`、`parallel_tool_use` 为什么独立为顶层字段？** +这些是多个协议共同表达的公共语义，只是字段名、嵌套位置或语义方向（正/反）有差异。统一为协议中立的顶层字段，避免命名偏向。适配新协议时，对照各字段在 Canonical 中的定义，实现提取（Decoder）和注入（Encoder）即可。 --- @@ -409,17 +367,15 @@ TargetProvider { base_url: String // 上游 API 地址 api_key: String // 上游认证密钥 model_name: String // 目标模型名（调用方完成映射后传入） - adapter_config: Map // 协议专属配置（如 anthropic-version） + adapter_config: Map // 协议专属配置 } ``` -`adapter_config` 由各 Adapter 自行定义所需的 key，引擎不感知含义，原样透传。示例： -- Anthropic: `{ "anthropic_version": "2023-06-01", "anthropic_beta": ["..."] }` -- OpenAI: `{ "organization": "org-xxx" }` 或空 +`adapter_config` 由各 Adapter 自行定义所需的 key，引擎不感知含义，原样透传。各 Adapter 需在协议适配文档中声明自己从 `adapter_config` 读取的 key 列表和默认值。 ### 5.2 ProtocolAdapter -每种协议的完整适配器，融入所有接口类型的处理能力。所有 Adapter 通过代码注册，不支持动态增减。 +每种协议的完整适配器，融入所有接口类型的处理能力。所有 Adapter 通过代码注册，不支持动态增减。新协议可通过空函数（如不支持的扩展层接口直接透传）渐进适配，接口集中定义方便明确所有应实现的内容。 ``` interface ProtocolAdapter { @@ -428,7 +384,7 @@ interface ProtocolAdapter { supportsPassthrough(): Boolean // 同协议透传开关，默认 true // HTTP 级别 - mapUrl(nativePath: String, interfaceType: InterfaceType): Option + buildUrl(nativePath: String, interfaceType: InterfaceType): String // 始终返回有效 URL；未知接口返回 nativePath buildHeaders(provider: TargetProvider): Map supportsInterface(interfaceType: InterfaceType): Boolean @@ -448,15 +404,12 @@ interface ProtocolAdapter { // 扩展层 decodeModelsResponse(raw): CanonicalModelList encodeModelsResponse(canonical): RawResponse + decodeModelInfoResponse(raw): CanonicalModelInfo + encodeModelInfoResponse(canonical): RawResponse decodeEmbeddingRequest(raw): CanonicalEmbeddingRequest encodeEmbeddingRequest(canonical, provider): RawRequest decodeEmbeddingResponse(raw): CanonicalEmbeddingResponse encodeEmbeddingResponse(canonical): RawResponse - decodeTokenCountRequest(raw): CanonicalTokenCountRequest - encodeTokenCountRequest(canonical, provider): RawRequest - decodeTokenCountResponse(raw): CanonicalTokenCountResponse - encodeTokenCountResponse(canonical): RawResponse - encodeFileListResponse(canonical): RawResponse decodeRerankRequest(raw): CanonicalRerankRequest encodeRerankRequest(canonical, provider): RawRequest decodeRerankResponse(raw): CanonicalRerankResponse @@ -464,20 +417,17 @@ interface ProtocolAdapter { } ``` -**`buildHeaders` vs 原 `mapHeaders`**：Adapter 只需从 `provider` 中提取自己协议需要的认证和配置信息，构建自己的 Header 格式。不再需要理解其他协议的 Header。 +**`buildHeaders` 的设计**：Adapter 只需从 `provider` 中提取自己协议需要的认证和配置信息，构建自己的 Header 格式。不再需要理解其他协议的 Header。 ### 5.3 InterfaceType ``` InterfaceType = Enum< - CHAT, MODELS, MODEL_INFO, EMBEDDINGS, FILES, RERANK, - COUNT_TOKENS, BATCHES, FINE_TUNING, - AUDIO, IMAGES, REALTIME, UNKNOWN + CHAT, MODELS, MODEL_INFO, EMBEDDINGS, RERANK, + AUDIO, IMAGES // 预留：多模态扩展时启用 > ``` -注：`MODERATIONS` 移除，仅 OpenAI 单协议支持，走透传层。 - ### 5.4 StreamDecoder / StreamEncoder ``` @@ -502,21 +452,16 @@ interface AdapterRegistry { } ``` -协议识别规则：URL 第一个路径段即协议标识。 - -``` -/openai/v1/... → "openai" -/anthropic/v1/... → "anthropic" -/gemini/v1beta/... → "gemini" (未来) -未知前缀 → null, 上层框架自行处理 -``` - --- ## 6. Conversion Engine（转换引擎） ### 6.1 ConversionEngine +ConversionEngine 是无状态的格式转换工具，仅做协议间的编解码和字段映射，不持有会话状态，线程安全，可复用。 + +**协议识别**：`clientProtocol` 和 `providerProtocol` 由调用方确定并传入引擎（详见 §2.2）。 + ``` class ConversionEngine { registry: AdapterRegistry @@ -525,52 +470,52 @@ class ConversionEngine { registerAdapter(adapter): void use(middleware): void - isPassthrough(source, target): Boolean { - return source == target && registry.get(source).supportsPassthrough() + isPassthrough(clientProtocol, providerProtocol): Boolean { + return clientProtocol == providerProtocol && registry.get(clientProtocol).supportsPassthrough() } // 非流式请求转换 - convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest { - nativePath = stripProtocolPrefix(request.url) + convertHttpRequest(request, clientProtocol, providerProtocol, provider): HttpRequest { + nativePath = request.url interfaceType = detectInterfaceType(nativePath) - if isPassthrough(sourceProtocol, targetProtocol): - targetAdapter = registry.get(targetProtocol) + if isPassthrough(clientProtocol, providerProtocol): + providerAdapter = registry.get(providerProtocol) return {url: provider.base_url + nativePath, method: request.method, - headers: targetAdapter.buildHeaders(provider), body: request.body} + headers: providerAdapter.buildHeaders(provider), body: request.body} - sourceAdapter = registry.get(sourceProtocol) - targetAdapter = registry.get(targetProtocol) + clientAdapter = registry.get(clientProtocol) + providerAdapter = registry.get(providerProtocol) - targetUrl = targetAdapter.mapUrl(nativePath, interfaceType) ?? nativePath - targetHeaders = targetAdapter.buildHeaders(provider) - targetBody = convertBody(interfaceType, sourceAdapter, targetAdapter, provider, request.body) + providerUrl = providerAdapter.buildUrl(nativePath, interfaceType) + providerHeaders = providerAdapter.buildHeaders(provider) + providerBody = convertBody(interfaceType, clientAdapter, providerAdapter, provider, request.body) - return {url: provider.base_url + targetUrl, method: request.method, - headers: targetHeaders, body: targetBody} + return {url: provider.base_url + providerUrl, method: request.method, + headers: providerHeaders, body: providerBody} } // 非流式响应转换 - convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse { - if isPassthrough(sourceProtocol, targetProtocol): return response + convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType): HttpResponse { + if isPassthrough(clientProtocol, providerProtocol): return response - sourceAdapter = registry.get(sourceProtocol) - targetAdapter = registry.get(targetProtocol) - targetBody = convertResponseBody(interfaceType, sourceAdapter, targetAdapter, response.body) + clientAdapter = registry.get(clientProtocol) + providerAdapter = registry.get(providerProtocol) + providerBody = convertResponseBody(interfaceType, clientAdapter, providerAdapter, response.body) - return {status: response.status, headers: response.headers, body: targetBody} + return {status: response.status, headers: response.headers, body: providerBody} } - // 流式转换 - createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter { - if isPassthrough(sourceProtocol, targetProtocol): - targetAdapter = registry.get(targetProtocol) - return new PassthroughStreamConverter(targetAdapter.buildHeaders(provider)) + // 流式转换：从 provider 协议解码，编码为 client 协议 + createStreamConverter(clientProtocol, providerProtocol, provider): StreamConverter { + if isPassthrough(clientProtocol, providerProtocol): + providerAdapter = registry.get(providerProtocol) + return new PassthroughStreamConverter(providerAdapter.buildHeaders(provider)) - source = registry.get(sourceProtocol) - target = registry.get(targetProtocol) + providerAdapter = registry.get(providerProtocol) + clientAdapter = registry.get(clientProtocol) return new CanonicalStreamConverter( - source.createStreamDecoder(), target.createStreamEncoder(), middlewareChain) + providerAdapter.createStreamDecoder(), clientAdapter.createStreamEncoder(), middlewareChain) } } ``` @@ -578,29 +523,30 @@ class ConversionEngine { ### 6.2 Body 转换分发 ``` -function convertBody(interfaceType, sourceAdapter, targetAdapter, provider, body): +function convertBody(interfaceType, clientAdapter, providerAdapter, provider, body): switch interfaceType: case CHAT: - canonical = sourceAdapter.decodeRequest(body) + canonical = clientAdapter.decodeRequest(body) canonical = middlewareChain.apply(canonical) - return targetAdapter.encodeRequest(canonical, provider) + return providerAdapter.encodeRequest(canonical, provider) case MODELS: return body // GET 请求，无 body + case MODEL_INFO: + return body // GET 请求，无 body case EMBEDDINGS: - if !sourceAdapter.supportsInterface(EMBEDDINGS) - || !targetAdapter.supportsInterface(EMBEDDINGS): + if !clientAdapter.supportsInterface(EMBEDDINGS) + || !providerAdapter.supportsInterface(EMBEDDINGS): return body // 尽力转换：不支持则透传 - return targetAdapter.encodeEmbeddingRequest( - sourceAdapter.decodeEmbeddingRequest(body), provider) + return providerAdapter.encodeEmbeddingRequest( + clientAdapter.decodeEmbeddingRequest(body), provider) case RERANK: // 同 EMBEDDINGS 模式 - case COUNT_TOKENS: - // 同 EMBEDDINGS 模式 default: return body // 透传层：原样转发 -function convertResponseBody(interfaceType, sourceAdapter, targetAdapter, body): +function convertResponseBody(interfaceType, clientAdapter, providerAdapter, body): // 结构与 convertBody 对称，CHAT 走 Canonical 深度转换，扩展层走轻量映射，默认透传 + // 各接口的具体响应转换逻辑详见各协议适配文档（附录 E） ``` ### 6.3 StreamConverter @@ -638,8 +584,8 @@ class CanonicalStreamConverter implements StreamConverter { ``` interface ConversionMiddleware { - intercept(canonical, sourceProtocol, targetProtocol, context): canonical | error - interceptStreamEvent?(event, sourceProtocol, targetProtocol, context): event | error + intercept(canonical, clientProtocol, providerProtocol, context): canonical | error + interceptStreamEvent?(event, clientProtocol, providerProtocol, context): event | error } ConversionContext { conversionId, interfaceType, timestamp, metadata } @@ -653,40 +599,30 @@ ConversionContext { conversionId, interfaceType, timestamp, metadata } ``` engine = new ConversionEngine() -engine.registerAdapter(new OpenAIAdapter()) -engine.registerAdapter(new AnthropicAdapter()) +engine.registerAdapter(new ProtocolAAdapter()) +engine.registerAdapter(new ProtocolBAdapter()) -// 场景1: OpenAI→Anthropic Chat -// 入站: /openai/v1/chat/completions +// 场景1: 跨协议 Chat 转换 +// 入站: /protocol_a/v1/chat/completions provider = TargetProvider { - base_url: "https://api.anthropic.com", - api_key: "sk-ant-xxx", - model_name: "claude-sonnet-4-20250514", - adapter_config: { "anthropic_version": "2023-06-01" } + base_url: "https://api.protocol-b.com", + api_key: "xxx", + model_name: "model-b", + adapter_config: { ... } } -out = engine.convertHttpRequest(inRequest, "openai", "anthropic", provider) -// 出站 /v1/messages, headers: x-api-key + anthropic-version +out = engine.convertHttpRequest(inRequest, "protocol_a", "protocol_b", provider) +// 出站: 目标协议路径 + 目标协议 headers + 转换后的 body // 场景2: /models 跨协议 -// 入站: /anthropic/v1/models -provider = TargetProvider { - base_url: "https://api.openai.com", - api_key: "sk-xxx", model_name: "", adapter_config: {} -} -out = engine.convertHttpRequest(inRequest, "anthropic", "openai", provider) -// source=anthropic, 出站 /v1/models + Authorization: Bearer +out = engine.convertHttpRequest(inRequest, "protocol_a", "protocol_b", provider) +// URL: /v1/models（通常不变）, headers 按目标协议格式重建 // 场景3: 同协议透传 -// 入站: /openai/v1/chat/completions -provider = TargetProvider { - base_url: "https://api.openai.com", - api_key: "sk-xxx", model_name: "", adapter_config: {} -} -out = engine.convertHttpRequest(inRequest, "openai", "openai", provider) -// source=openai == target=openai → 剥离前缀, 用 provider 重建 headers 后原样转发 +out = engine.convertHttpRequest(inRequest, "protocol_a", "protocol_a", provider) +// client == provider → 剥离前缀, 用 provider 重建 headers 后原样转发 -// 场景4: 流式转换 -converter = engine.createStreamConverter("anthropic", "openai", provider) +// 场景4: 流式转换（从 provider 协议解码，编码为 client 协议） +converter = engine.createStreamConverter("protocol_a", "protocol_b", provider) for chunk in upstreamSSE { for out in converter.processChunk(chunk) { sendToClient(out) } } @@ -717,7 +653,9 @@ converter.flush() └───────────┘ └──────────┘ └───────────┘ ``` -### 7.2 StreamDecoder 状态 +### 7.2 StreamDecoder 通用状态 + +StreamDecoder 需要跟踪以下通用状态。具体协议的 Decoder 可根据需要扩展： ``` StreamDecoderState { @@ -725,536 +663,42 @@ StreamDecoderState { openBlocks: Set currentBlockType: Map currentBlockId: Map - toolCallIdMap: Map // OpenAI 特有 - toolCallNameMap: Map // OpenAI 特有 - toolCallArguments: Map // OpenAI 特有 utf8Remainder: Option // UTF-8 跨 chunk 安全 accumulatedUsage: Option } ``` -### 7.3 事件映射 +**协议特有状态**：某些协议的 SSE 格式需要额外状态（如工具调用参数累积、工具调用索引映射等），在各自的协议适配文档中定义。 -**Anthropic SSE ↔ Canonical**：几乎 1:1 映射，事件类型完全对应。 +### 7.3 事件映射概述 -**OpenAI SSE → Canonical**（需要状态机）： +StreamDecoder 将协议原生 SSE 事件翻译为 CanonicalStreamEvent，StreamEncoder 做反向翻译。映射复杂度取决于协议的 SSE 格式： -| OpenAI chunk | Canonical 事件 | -|---|---| -| 首个 chunk (id/model) | MessageStartEvent | -| delta.content 首次 | ContentBlockStart(text) + ContentBlockDelta(text_delta) | -| delta.content 后续 | ContentBlockDelta(text_delta) | -| delta.tool_calls[i] 首次 | ContentBlockStart(tool_use) | -| delta.tool_calls[i].arguments | ContentBlockDelta(input_json_delta) | -| delta.reasoning_content | ContentBlockStart(thinking) + ContentBlockDelta(thinking_delta) | -| finish_reason | ContentBlockStop × N + MessageDeltaEvent + MessageStopEvent | -| [DONE] | flush() | +- **类型化事件协议**（事件有明确的 start/delta/stop 生命周期）：与 CanonicalStreamEvent 接近 1:1 映射，状态机最简单 +- **Delta 模型协议**（只有增量 delta chunk，无显式生命周期）：需要状态机推断 block 边界，管理工具调用索引和参数累积 +- **缓冲策略**：部分协议的 Encoder 需要缓冲 ContentBlockStart 事件，等待首次 ContentBlockDelta 时合并输出 -**Canonical → OpenAI SSE**（Encoder 端）： - -| Canonical 事件 | OpenAI chunk | -|---|---| -| MessageStartEvent | 首个 chunk (id, model, delta:{}) | -| ContentBlockStart(text) | 缓冲，不输出 | -| ContentBlockDelta(text) | {choices:[{delta:{content:"..."}}]}（首次合并 block_start） | -| ContentBlockStart(tool) | 缓冲 | -| ContentBlockDelta(input_json) | {choices:[{delta:{tool_calls:[...]}}]}（首次含 id/name） | -| ContentBlockStop | 不输出 | -| MessageDeltaEvent | {choices:[{finish_reason:"..."}]} | -| MessageStopEvent | [DONE] | -| PingEvent | 丢弃 | +各协议的具体事件映射表详见各自的协议适配文档（附录 E）。 --- -## 8. OpenAI 协议适配器 +## 8. 扩展点设计 -### 8.1 URL 路径映射 - -``` -OpenAI.mapUrl(nativePath, interfaceType): - switch interfaceType: - case CHAT: return "/v1/chat/completions" - case MODELS: return "/v1/models" - case MODEL_INFO: return "/v1/models/{modelId}" - case EMBEDDINGS: return "/v1/embeddings" - case FILES: return nativePath - case RERANK: return "/v1/rerank" - default: return nativePath -``` - -### 8.2 请求头构建 - -``` -OpenAI.buildHeaders(provider): - result = {} - result["Authorization"] = "Bearer " + provider.api_key - if provider.adapter_config["organization"]: - result["OpenAI-Organization"] = provider.adapter_config["organization"] - result["Content-Type"] = "application/json" - return result -``` - -### 8.3 接口能力声明 - -``` -OpenAI.supportsInterface(type): - CHAT...IMAGES: return true // 全部支持 - COUNT_TOKENS: return false // OpenAI 无此接口 - default: return false -``` - -### 8.4 Chat 请求 Decoder/Encoder - -#### Decoder: decodeRequest → CanonicalRequest - -``` -decodeSystemPrompt(messages): - systemMsgs = messages.filter(m => m.role == "system") - remaining = messages.filter(m => m.role != "system") - if systemMsgs.length == 0: return {system: None, messages: remaining} - return {system: systemMsgs.map(m => extractText(m.content)).join("\n\n"), messages: remaining} -``` - -``` -decodeMessage(msg): - switch msg.role: - case "user": - return {role: "user", content: decodeUserContent(msg.content)} - case "assistant": - blocks = [] - if msg.content: blocks.append({type: "text", text: extractText(msg.content)}) - if msg.refusal: blocks.append({type: "text", text: msg.refusal}) - if msg.tool_calls: - for tc in msg.tool_calls: - blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, - input: JSON.parse(tc.function.arguments)}) - return {role: "assistant", content: blocks} - case "tool": - return {role: "tool", content: [{ - type: "tool_result", tool_use_id: msg.tool_call_id, - content: msg.content, is_error: false}]} -``` - -#### Encoder: encodeRequest ← CanonicalRequest - -``` -encodeRequest(canonical, provider): - result = { - model: provider.model_name, - messages: encodeSystemPrompt(canonical) + canonical.messages.flatMap(encodeMessage), - max_tokens: canonical.parameters.max_tokens, - temperature: canonical.parameters.temperature, - top_p: canonical.parameters.top_p, - stream: canonical.stream - } - if canonical.parameters.stop_sequences: - result.stop = canonical.parameters.stop_sequences - if canonical.user_id: - result.user = canonical.user_id - if canonical.output_format: - result.response_format = encodeOutputFormat(canonical.output_format) - if canonical.parallel_tool_use != null: - result.parallel_tool_calls = canonical.parallel_tool_use - if canonical.tools: - result.tools = canonical.tools.map(t => ({ - type: "function", function: {name: t.name, description: t.description, parameters: t.input_schema}})) - if canonical.tool_choice: - result.tool_choice = encodeToolChoice(canonical.tool_choice) - if canonical.thinking && canonical.thinking.type == "enabled": - result.reasoning_effort = canonical.thinking.effort ?? "medium" - return result - -encodeOutputFormat(format): - switch format.type: - "json_object" → {type: "json_object"} - "json_schema" → {type: "json_schema", json_schema: format.json_schema} - "text" → null - -encodeToolChoice(choice): - switch choice.type: - "auto" → "auto" - "none" → "none" - "any" → "required" - "tool" → {type: "function", function: {name: choice.name}} - -``` - -### 8.5 Chat 响应 Decoder/Encoder - -``` -// Decoder -mapStopReason(reason): - "stop" → "end_turn" | "length" → "max_tokens" | "tool_calls" → "tool_use" | "content_filter" → "content_filter" | _ → "end_turn" - -decodeResponse(openaiResp): - choice = openaiResp.choices[0] - blocks = [] - if choice.message.content: blocks.append({type: "text", text: choice.message.content}) - if choice.message.refusal: blocks.append({type: "text", text: choice.message.refusal}) - if choice.message.reasoning_content: - blocks.append({type: "thinking", thinking: choice.message.reasoning_content}) - if choice.message.tool_calls: - for tc: blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, - input: JSON.parse(tc.function.arguments)}) - return CanonicalResponse {id, model, content: blocks, stop_reason: mapStopReason(choice.finish_reason), usage: decodeUsage(openaiResp.usage)} - -// Encoder -mapCanonicalToFinishReason(reason): - "end_turn" → "stop" | "max_tokens" → "length" | "tool_use" → "tool_calls" | "content_filter" → "content_filter" | _ → "stop" - -encodeResponse(canonical): - textParts = canonical.content.filter(b => b.type == "text") - toolUses = canonical.content.filter(b => b.type == "tool_use") - message = {} - if textParts.length > 0: message.content = textParts.map(b => b.text).join("") - elif toolUses.length > 0: message.content = null - else: message.content = "" - if toolUses.length > 0: - message.tool_calls = toolUses.map(tu => ({ - id: tu.id, type: "function", - function: {name: tu.name, arguments: JSON.stringify(tu.input)}})) - return {id: canonical.id, object: "chat.completion", model: canonical.model, - choices: [{index: 0, message, finish_reason: mapCanonicalToFinishReason(canonical.stop_reason)}], - usage: encodeUsage(canonical.usage)} -``` - -### 8.6 /models 响应编解码 - -``` -// Decoder: OpenAI → Canonical -decodeModelsResponse(openaiResp): - return CanonicalModelList { - models: openaiResp.data.map(m => CanonicalModel { - id: m.id, name: m.id, created: m.created, owned_by: m.owned_by })} - -// Encoder: Canonical → OpenAI -encodeModelsResponse(canonical): - return {object: "list", - data: canonical.models.map(m => ({id: m.id, object: "model", - created: m.created ?? 0, owned_by: m.owned_by ?? "unknown"}))} -``` - -**跨协议示例（入站 `/openai/v1/models`，目标 Anthropic）**： - -``` -入站: GET /openai/v1/models, Authorization: Bearer sk-xxx - → source=openai, target=anthropic - → URL: /v1/models, Headers: x-api-key: sk-xxx, anthropic-version: ... - -Anthropic 上游响应: {data: [{id: "claude-sonnet-4", display_name: "Claude Sonnet 4", ...}], has_more: false} - → Anthropic.decodeModelsResponse → CanonicalModelList - → OpenAI.encodeModelsResponse - -返回客户端: {object: "list", data: [{id: "claude-sonnet-4", object: "model", created: 0, owned_by: "anthropic"}]} -``` - ---- - -## 9. Anthropic 协议适配器 - -### 9.1 URL 路径映射 - -``` -Anthropic.mapUrl(nativePath, interfaceType): - switch interfaceType: - case CHAT: return "/v1/messages" - case MODELS: return "/v1/models" - case MODEL_INFO: return "/v1/models/{modelId}" - case COUNT_TOKENS: return "/v1/messages/count_tokens" - case EMBEDDINGS: return null // 不支持 - case RERANK: return null - case FILES: return null - default: return nativePath -``` - -### 9.2 请求头构建 - -``` -Anthropic.buildHeaders(provider): - result = {} - result["x-api-key"] = provider.api_key - result["anthropic-version"] = provider.adapter_config["anthropic_version"] ?? "2023-06-01" - if provider.adapter_config["anthropic_beta"]: - result["anthropic-beta"] = provider.adapter_config["anthropic_beta"].join(",") - result["Content-Type"] = "application/json" - return result -``` - -### 9.3 接口能力声明 - -``` -Anthropic.supportsInterface(type): - CHAT: return true - MODELS: return true - COUNT_TOKENS: return true - BATCHES: return true - default: return false -``` - -### 9.4 Chat 请求 Decoder/Encoder - -#### Decoder - -``` -decodeSystem(system): - if system is None: return None - if system is String: return system - return system.map(s => SystemBlock {text: s.text}) - -decodeMessage(msg): - switch msg.role: - case "user": - blocks = decodeContentBlocks(msg.content) - toolResults = blocks.filter(b => b.type == "tool_result") - others = blocks.filter(b => b.type != "tool_result") - if toolResults.length > 0: - return [ - ...(others.length > 0 ? [{role: "user", content: others}] : []), - {role: "tool", content: toolResults}] - return [{role: "user", content: blocks}] - case "assistant": - return [{role: "assistant", content: decodeContentBlocks(msg.content)}] - -decodeContentBlocks(content): - if content is String: return [{type: "text", text: content}] - return content.map(block => { - switch block.type: - "text" → TextBlock{text: block.text} - "tool_use" → ToolUseBlock{id: block.id, name: block.name, input: block.input} - "tool_result" → ToolResultBlock{tool_use_id: block.tool_use_id, ...} - "thinking" → ThinkingBlock{thinking: block.thinking} - "redacted_thinking" → 丢弃 }) // 仅 Anthropic 使用，不在中间层保留 - -// 额外字段提取 -decodeExtras(raw): - user_id = raw.metadata?.user_id - output_format = null // Anthropic 旧模型无 output_format，新模型通过 output_config 提取 - parallel_tool_use = raw.disable_parallel_tool_use == true ? false : null - thinking = raw.thinking ? ThinkingConfig { - type: raw.thinking.type, // "enabled" | "disabled" - budget_tokens: raw.thinking.budget_tokens, - effort: null } : null -``` - -#### Encoder - -``` -encodeRequest(canonical, provider): - result = { - model: provider.model_name, - messages: encodeMessages(canonical), - max_tokens: canonical.parameters.max_tokens, - temperature: canonical.parameters.temperature, - top_p: canonical.parameters.top_p, - stream: canonical.stream - } - if canonical.system: - result.system = encodeSystem(canonical.system) - if canonical.parameters.stop_sequences: - result.stop_sequences = canonical.parameters.stop_sequences - if canonical.user_id: - result.metadata = {user_id: canonical.user_id} - if canonical.output_format: - result.output_format = encodeOutputFormat(canonical.output_format) - if canonical.parallel_tool_use == false: - result.disable_parallel_tool_use = true - if canonical.tools: - result.tools = canonical.tools.map(t => ({ - name: t.name, description: t.description, input_schema: t.input_schema})) - if canonical.tool_choice: - result.tool_choice = encodeToolChoice(canonical.tool_choice) - if canonical.thinking: - result.thinking = {type: canonical.thinking.type} - if canonical.thinking.budget_tokens: - result.thinking.budget_tokens = canonical.thinking.budget_tokens - return result - -encodeSystem(system): - if system is String: return system - return system.map(s => ({text: s.text})) - -encodeToolChoice(choice): - switch choice.type: - "auto" → {type: "auto"} - "none" → {type: "none"} - "any" → {type: "any"} - "tool" → {type: "tool", name: choice.name} -``` - -### 9.5 Chat 响应 Decoder/Encoder - -``` -// Decoder -decodeResponse(anthropicResp): - blocks = [] - for block in anthropicResp.content: - switch block.type: - "text" → blocks.append({type: "text", text: block.text}) - "tool_use" → blocks.append({type: "tool_use", id: block.id, name: block.name, input: block.input}) - "thinking" → blocks.append({type: "thinking", thinking: block.thinking}) - "redacted_thinking" → 丢弃 // 仅 Anthropic 使用，不在中间层保留 - return CanonicalResponse {id, model, content: blocks, stop_reason: anthropicResp.stop_reason, - usage: CanonicalUsage {input_tokens, output_tokens, - cache_read_tokens: anthropicResp.usage.cache_read_input_tokens, - cache_creation_tokens: anthropicResp.usage.cache_creation_input_tokens}} - -// Encoder -encodeResponse(canonical): - blocks = canonical.content.map(block => { - switch block.type: - "text" → {type: "text", text: block.text} - "tool_use" → {type: "tool_use", id: block.id, name: block.name, input: block.input} - "thinking" → {type: "thinking", thinking: block.thinking}}) - return {id: canonical.id, type: "message", role: "assistant", model: canonical.model, - content: blocks, - stop_reason: canonical.stop_reason == "content_filter" ? "end_turn" : canonical.stop_reason, - stop_sequence: None, - usage: {input_tokens: canonical.usage.input_tokens, output_tokens: canonical.usage.output_tokens, - cache_read_input_tokens: canonical.usage.cache_read_tokens, - cache_creation_input_tokens: canonical.usage.cache_creation_tokens}} - -// 错误编码 -encodeError(error): - return {type: "error", error: {type: error.code, message: error.message}} -``` - -### 9.6 /models 响应编解码 - -``` -// Decoder: Anthropic → Canonical -decodeModelsResponse(anthropicResp): - return CanonicalModelList { - models: anthropicResp.data.map(m => CanonicalModel { - id: m.id, name: m.display_name ?? m.id, created: m.created_at, - owned_by: "anthropic"})} - -// Encoder: Canonical → Anthropic -encodeModelsResponse(canonical): - return {data: canonical.models.map(m => ({ - id: m.id, - display_name: m.name ?? m.id, - created_at: m.created ?? 0, type: "model"})), - has_more: false, - first_id: canonical.models[0]?.id, last_id: canonical.models.last?.id} -``` - -### 9.7 /count_tokens 编解码 - -``` -// Decoder -decodeTokenCountRequest(raw): - return CanonicalTokenCountRequest { - model: raw.model, messages: decodeMessages(raw.messages), - system: decodeSystem(raw.system), tools: decodeTools(raw.tools)} - -// Encoder -encodeTokenCountRequest(canonical): - return {model: canonical.model, messages: encodeMessages(canonical), - system: encodeSystem(canonical), tools: encodeTools(canonical.tools)} - -decodeTokenCountResponse(raw): - return CanonicalTokenCountResponse {input_tokens: raw.input_tokens} - -encodeTokenCountResponse(canonical): - return {input_tokens: canonical.input_tokens} -``` - -**跨协议对接策略（入站 `/anthropic/v1/messages/count_tokens`，目标 OpenAI）**： - -OpenAI 不提供 `/count_tokens` 接口。Anthropic Claude Code 启动时会调用此接口。 - -| 策略 | 实现 | -|------|------| -| **透传** | URL+Header 适配后发送到 OpenAI，由上游返回 404 | -| **模拟（推荐）** | 解码请求，用估算器返回近似 token 数 | -| **精确估算** | 解码 messages，调用 OpenAI Chat Completions (max_tokens=1)，从 usage.prompt_tokens 获取 | - -策略选择通过配置或 Middleware 决定。 - ---- - -## 10. 字段映射参考 - -### 10.1 Chat 请求字段映射 - -| Canonical | OpenAI | Anthropic | 说明 | -|---|---|---|---| -| `system` | `messages[0].role="system"` | `system` (顶层) | 位置差异 | -| `user_id` | `user` (顶层) | `metadata.user_id` | 嵌套差异 | -| `output_format` | `response_format` | `output_format` (新模型) | 字段名差异；旧 Anthropic 模型需降级 | -| `parallel_tool_use` | `parallel_tool_calls` (bool) | `disable_parallel_tool_use` (bool, 反转) | 语义反转 | -| `ToolUseBlock` | `tool_calls[{id,function}]` | `content[{type:"tool_use"}]` | OpenAI 在 message 顶层 | -| `ToolResultBlock` | `{role:"tool",tool_call_id}` | `content[{type:"tool_result"}]` in user | 结构性差异 | -| `tools[].input_schema` | `tools[].function.parameters` | `tools[].input_schema` | 字段名不同 | -| `tool_choice: "any"` | `"required"` | `{type:"any"}` | 语义映射 | -| `max_tokens` | `max_tokens` / `max_completion_tokens` | `max_tokens` | o-series 差异 | -| `stop_sequences` | `stop` (String or Array) | `stop_sequences` (Array) | OpenAI Decoder 规范化为 Array | -| `thinking.type` | — | `thinking.type` | Anthropic 特有 | -| `thinking.effort` | `reasoning_effort` | — | OpenAI 参数级 | -| `thinking.budget_tokens` | — | `thinking.budget_tokens` | Anthropic token 级 | - -### 10.2 Chat 响应字段映射 - -| Canonical | OpenAI | Anthropic | -|---|---|---| -| `stop_reason: "end_turn"` | `finish_reason: "stop"` | `stop_reason: "end_turn"` | -| `stop_reason: "max_tokens"` | `finish_reason: "length"` | `stop_reason: "max_tokens"` | -| `stop_reason: "tool_use"` | `finish_reason: "tool_calls"` | `stop_reason: "tool_use"` | -| `ThinkingBlock` | `reasoning_content` (非流式) | `content[{type:"thinking"}]` | -| `usage.input_tokens` | `usage.prompt_tokens` | `usage.input_tokens` | -| `usage.output_tokens` | `usage.completion_tokens` | `usage.output_tokens` | -| `usage.cache_read_tokens` | `usage.prompt_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` | - -### 10.3 HTTP 头映射 - -Headers 由各 Adapter 的 `buildHeaders(provider)` 方法构建，从 `provider.api_key` 和 `provider.adapter_config` 获取信息，无需理解其他协议。 - -| 场景 | OpenAI | Anthropic | -|------|--------|-----------| -| 认证 | `Authorization: Bearer ` | `x-api-key: ` | -| 版本 | — | `anthropic-version`（从 adapter_config 读取） | -| Beta | — | `anthropic-beta`（从 adapter_config 读取） | - -### 10.4 扩展层接口映射 - -#### /models - -| 维度 | OpenAI | Anthropic | -|------|--------|-----------| -| 响应格式 | `{object:"list", data:[{id, object:"model", created, owned_by}]}` | `{data:[{id, display_name, created_at, type}], has_more, first_id, last_id}` | -| 映射 | `id↔id`, `created↔created_at`, `owned_by→"anthropic"`, `display_name→id` | - -#### /count_tokens - -| 维度 | OpenAI | Anthropic | -|------|--------|-----------| -| 存在性 | 不存在 | `POST /v1/messages/count_tokens` | -| 策略 | Anthropic→OpenAI: 模拟/估算 | 原生支持 | - -#### /embeddings - -| 维度 | OpenAI | Anthropic | -|------|--------|-----------| -| 存在性 | `POST /v1/embeddings` | 不存在 | -| 策略 | 原生支持 | OpenAI→Anthropic: 返回不支持错误 | - ---- - -## 11. 扩展点设计 - -### 11.1 新协议接入 +### 8.1 新协议接入 1. 实现 ProtocolAdapter（URL 映射 + Header 映射 + 各接口编解码） 2. 注册到 AdapterRegistry 3. 完成 -### 11.2 多模态扩展 +按附录 D 的清单模板逐项确认，所有项目确认后即可与引擎对接。 + +### 8.2 多模态扩展 Canonical Model 已预留 ImageBlock / AudioBlock / VideoBlock / FileBlock。实现路径： 1. 在各 ProtocolAdapter 中实现多模态块的编解码 2. 在 StreamDecoder/StreamEncoder 中处理多模态增量数据 -### 11.3 有状态特性扩展 +### 8.3 有状态特性扩展 ``` interface StatefulMiddleware extends ConversionMiddleware { @@ -1262,38 +706,37 @@ interface StatefulMiddleware extends ConversionMiddleware { } ``` -适用场景：Gemini thoughtSignature 跨轮次保留。 +适用场景：跨轮次保留协议特有的状态（如 thinking signature）。 -### 11.4 特性降级策略 +### 8.4 特性降级策略 -| 源特性 | 目标协议 | 降级方式 | -|--------|---------|---------| -| `output_format` | Anthropic（旧模型） | 注入合成工具实现 JSON 模式 | -| `thinking.effort` | Anthropic | 转为 `thinking.budget_tokens` | -| `thinking.budget_tokens` | OpenAI | 转为 `reasoning_effort` | -| `count_tokens` | OpenAI | 模拟/估算 | -| `/embeddings` | Anthropic | 返回不支持的错误 | +当 Canonical 公共字段在目标协议中无直接等价物时： +- 有语义等价物 → 自动映射 +- 无等价物 → 丢弃，日志 warn +- 有替代方案 → 降级策略处理（如注入合成工具实现 JSON 模式） -### 11.5 自定义接口支持 +各协议的具体降级规则详见各自的协议适配文档（附录 E）。 + +### 8.5 自定义接口支持 ``` interface CustomInterfaceHandler { interfaceType(): InterfaceType matchUrl(url): Boolean - convertRequest(source, target, raw): raw - convertResponse(source, target, raw): raw + convertRequest(client, provider, raw): raw + convertResponse(client, provider, raw): raw } engine.registerCustomHandler(handler) ``` --- -## 12. 错误处理 +## 9. 错误处理 -### 12.1 错误分类 +### 9.1 错误分类 ``` -ConversionError { code: ErrorCode, message, sourceProtocol?, targetProtocol?, +ConversionError { code: ErrorCode, message, clientProtocol?, providerProtocol?, interfaceType?, details?, cause? } ErrorCode = Enum< @@ -1311,7 +754,7 @@ ErrorCode = Enum< > ``` -### 12.2 错误处理策略 +### 9.2 错误处理策略 ``` ErrorHandler { mode: "strict" | "lenient" } @@ -1334,131 +777,21 @@ lenient: 尽力继续 具体策略通过配置或 Middleware 决定。 -### 12.3 错误响应格式 +### 9.3 错误响应格式 -转换失败时，错误响应用**客户端协议（source protocol）**的格式编码。由 `sourceAdapter.encodeError(error)` 完成： +转换失败时，错误响应用**客户端协议（client protocol）**的格式编码。由 `clientAdapter.encodeError(error)` 完成。各协议的错误响应 JSON 结构和 HTTP 状态码映射详见各自的协议适配文档（附录 E）。 -- OpenAI 格式：`{error: {message, type, code, param}}` -- Anthropic 格式：`{type: "error", error: {type, message}}` - -Middleware 中断转换时同理，引擎调用 sourceAdapter.encodeError 将 ConversionError 编码为客户端可理解的格式。 +Middleware 中断转换时同理，引擎调用 clientAdapter.encodeError 将 ConversionError 编码为客户端可理解的格式。 --- -## 13. 参考实现对比 - -### 13.1 关键差异 - -| 维度 | CC-Switch | LiteLLM | new-api | one-api | 本设计 | -|------|-----------|---------|---------|---------|--------| -| 定位 | 桌面代理 | 完整网关+SDK | 完整网关 | 完整网关 | HTTP 层 SDK | -| 架构 | 直接转换 | 策略+工厂 | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (OpenAI) | Hub-and-Spoke (自定义) | -| 转换方向 | 双向(有限) | 单向→厂商 | 单向→OpenAI | 单向→OpenAI | 双向(任意协议对) | -| Canonical 模型 | 无 | 无 | OpenAI 格式 | OpenAI 格式 | 自定义超集，字段随协议扩展演进 | -| 厂商覆盖 | 2 | 100+ | 50+ | 56 渠道/19 API 类型 | 协议级(当前 2, 可扩展) | -| 管理接口 | /health, /status | 全接口 | 全接口 | 全接口 | /models, /embeddings, /count_tokens, /files, /rerank + 透传层 | -| 同协议透传 | Anthropic 直通 | 无 | 开关控制 | OpenAI 兼容渠道零拷贝 | 自动检测 | -| 协议前缀 | /claude/, /codex/, /gemini/ | 无 | 无 | 无 | /openai/, /anthropic/ | -| 流式处理 | 简单转发 | 简单解析 | Scanner+SSE | Scanner+SSE | StreamDecoder/Encoder 状态机 | -| 错误处理 | 基础 | 基础 | 统一格式归一化 | 多格式归一化 | strict/lenient 模式 + ErrorCode 枚举 | -| 扩展机制 | 硬编码 | 策略模式 | 实现 Adaptor 接口 | 实现 Adaptor 接口 | ProtocolAdapter + Middleware + 自定义接口 | - -### 13.2 设计取舍 - -| 取舍 | 选择 | 理由 | -|------|------|------| -| HTTP 层 SDK vs 纯 chat 库 | HTTP 层 SDK | 编程工具需要管理接口 | -| 自定义 Canonical vs OpenAI | 自定义 | 避免厂商锁定 | -| 接口分层 vs 全部深度转换 | 分层 | 核心深度转换，扩展轻量映射，透传零转换 | -| 尽力转换 vs 严格转换 | 尽力转换 | 最大化覆盖面 | -| 透传 vs 总是 Canonical | 自动透传 + 可选禁用 | 同协议和未知接口的性能优化 | - -### 13.3 关键经验 - -- **CC-Switch**: UTF-8 跨 chunk 截断处理必要；工具调用参数可能乱序到达；同协议直通是最高频路径 -- **LiteLLM**: BaseConfig 抽象 + 编排器不变模式扩展性好；全接口覆盖对用户体验至关重要 -- **new-api**: 多格式输入的 Hub-and-Spoke 已生产验证；/models 的协议感知转换价值最高 -- **one-api**: 以 OpenAI 格式为 Canonical 的 Hub-and-Spoke 架构在 19 种 API 类型、56 个渠道的生产环境验证了可行性；大量厂商(DepSeek/Groq/Mistral/Moonshot 等)采用 OpenAI 兼容格式使得同协议透传成为最高频路径；适配器模式的 ChannelType→APIType→Adaptor 三层映射提供了厂商级精细控制但增加了维护复杂度 - ---- - -## 附录 A：完整转换流程示例 - -``` -客户端发送: -POST /openai/v1/chat/completions HTTP/1.1 ← /openai/ 前缀标识源协议 -Authorization: Bearer sk-xxx -Content-Type: application/json - -{ "model": "gpt-4", - "messages": [ - {"role": "system", "content": "You are a coding assistant"}, - {"role": "user", "content": "Read the file main.py"}, - {"role": "assistant", "content": null, "tool_calls": [{ - "id": "call_abc123", "type": "function", - "function": {"name": "read_file", "arguments": "{\"path\": \"main.py\"}"}}]}, - {"role": "tool", "tool_call_id": "call_abc123", "content": "print('hello')"}, - {"role": "user", "content": "What does this code do?"}], - "tools": [{"type": "function", "function": {"name": "read_file", "parameters": {...}}}], - "max_tokens": 1024, "stream": true } - - │ - ▼ - -engine.convertHttpRequest(request, "openai", "anthropic", provider) - -provider = TargetProvider { - base_url: "https://api.anthropic.com", - api_key: "sk-ant-xxx", - model_name: "claude-sonnet-4-20250514", - adapter_config: { "anthropic_version": "2023-06-01" } -} - -Step 0: 前缀 /openai/ → source=openai, 剥离后 /v1/chat/completions -Step 1: 接口识别 → CHAT -Step 2: URL 映射 → /v1/messages -Step 3: Header 构建 → x-api-key: sk-ant-xxx, anthropic-version: 2023-06-01 -Step 4: Body 转换: - - OpenAI.decodeRequest → CanonicalRequest { - model: "gpt-4", - system: "You are a coding assistant", - messages: [ - {user, [{text, "Read the file main.py"}]}, - {assistant, [{tool_use, id:"call_abc123", name:"read_file", input:{path:"main.py"}}]}, - {tool, [{tool_result, tool_use_id:"call_abc123", content:"print('hello')"}]}, - {user, [{text, "What does this code do?"}]}], - parameters: {max_tokens: 1024}, - stream: true } - - Anthropic.encodeRequest(canonical, provider) → { - "model": "claude-sonnet-4-20250514", ← 使用 provider.model_name - "system": "You are a coding assistant", - "messages": [ - {"role": "user", "content": [{"type": "text", "text": "Read the file main.py"}]}, - {"role": "assistant", "content": [{"type": "tool_use", "id": "call_abc123", ...}]}, - {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_abc123", ...}]}, - {"role": "user", "content": [{"type": "text", "text": "What does this code do?"}]}], - "max_tokens": 1024, "stream": true } - -发往 Anthropic 上游: -POST https://api.anthropic.com/v1/messages HTTP/1.1 ← provider.base_url + 目标路径 -x-api-key: sk-ant-xxx -anthropic-version: 2023-06-01 -``` - ---- - -## 附录 B：模块依赖 +## 附录 A：模块依赖 ``` ┌──────────────────────────────────────────────────┐ │ ConversionEngine │ -│ 门面：HTTP 转换 / 协议路由 / 透传判断 / 流式转换 │ -│ ┌────────────────────────────────────────────┐ │ -│ │ Protocol Prefix Router │ │ -│ │ URL 前缀 → source protocol │ │ -│ └────────────────────────────────────────────┘ │ +│ 门面：HTTP 转换 / 透传判断 / 流式转换 │ +│ 无状态；协议识别见 §2.2 │ ├──────────────────────────────────────────────────┤ │ TargetProvider │ │ base_url / api_key / model_name / adapter_config │ @@ -1467,9 +800,9 @@ anthropic-version: 2023-06-01 ├──────────────────┴───────────────────────────────┤ │ StreamConverter: Passthrough | Canonical │ ├──────────────────────────────────────────────────┤ -│ ProtocolAdapter: OpenAI | Anthropic | Future... │ +│ ProtocolAdapter: 各协议实现 │ │ · buildHeaders(provider) · URL 映射 │ -│ · Chat/Models/Embeddings/Rerank/... 编解码 │ +│ · Chat/Models/ModelInfo/Embeddings/Rerank/... 编解码 │ │ · encodeError · StreamDecoder / StreamEncoder │ ├──────────────────────────────────────────────────┤ │ Canonical Model (Core + Extended) │ @@ -1482,17 +815,17 @@ anthropic-version: 2023-06-01 --- -## 附录 C：接口速查 +## 附录 B：接口速查 ``` // ─── 核心入口 ─── ConversionEngine .registerAdapter(adapter) .use(middleware) - .isPassthrough(source, target): Boolean - .convertHttpRequest(request, sourceProtocol, targetProtocol, provider): HttpRequest - .convertHttpResponse(response, sourceProtocol, targetProtocol, interfaceType): HttpResponse - .createStreamConverter(sourceProtocol, targetProtocol, provider): StreamConverter + .isPassthrough(clientProtocol, providerProtocol): Boolean + .convertHttpRequest(request, clientProtocol, providerProtocol, provider): HttpRequest + .convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType): HttpResponse + .createStreamConverter(clientProtocol, providerProtocol, provider): StreamConverter // ─── 目标上游信息 ─── TargetProvider @@ -1502,22 +835,19 @@ TargetProvider .adapter_config: Map // ─── URL 路由 ─── -// 入站: /{protocol}/{native_path} -// /openai/v1/chat/completions → source=openai -// /anthropic/v1/messages → source=anthropic -// 出站: provider.base_url + 目标协议原生路径（无前缀） +// 协议识别见 §2.2；出站: provider.base_url + 目标协议原生路径 // ─── 协议适配器 ─── ProtocolAdapter .protocolName() / .protocolVersion() / .supportsPassthrough() - .mapUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type) + .buildUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type) .decodeRequest(raw) / .encodeRequest(canonical, provider) .decodeResponse(raw) / .encodeResponse(canonical) .createStreamDecoder() / .createStreamEncoder() .encodeError(error): RawResponse .decodeModelsResponse / .encodeModelsResponse + .decodeModelInfoResponse / .encodeModelInfoResponse .decodeEmbeddingRequest / .encodeEmbeddingRequest(canonical, provider) / ...Response - .decodeTokenCountRequest / .encodeTokenCountRequest(canonical, provider) / ...Response .decodeRerankRequest / .encodeRerankRequest(canonical, provider) / ...Response // ─── 流式处理 ─── @@ -1526,14 +856,12 @@ StreamConverter: .processChunk(raw) / .flush() └─ CanonicalStreamConverter decode → middleware → encode // ─── 接口类型 ─── -InterfaceType = CHAT | MODELS | MODEL_INFO | EMBEDDINGS | FILES | - RERANK | COUNT_TOKENS | BATCHES | - FINE_TUNING | AUDIO | IMAGES | REALTIME | UNKNOWN +InterfaceType = CHAT | MODELS | MODEL_INFO | EMBEDDINGS | RERANK | AUDIO | IMAGES ``` --- -## 附录 D：字段晋升规范 +## 附录 C：字段晋升规范 ### 原则 @@ -1556,71 +884,82 @@ Canonical Model 是**活的公共契约**，不是固定不变的。其字段集 - 否 → 暂不纳入，记录在适配清单中 3. 设计：确定字段名（协议中立）、类型、在 Canonical 中的位置 4. 更新：修改 Canonical Model 定义，所有现有 Adapter 的 Decoder/Encoder 同步更新 -5. 文档：更新 §10 字段映射参考表 +5. 文档：更新本节说明 ``` ### 晋升示例 -| 字段 | 原始位置 | 晋升原因 | -|------|---------|---------| -| `user_id` | OpenAI `user` / Anthropic `metadata.user_id` | 两协议均支持用户标识 | -| `output_format` | OpenAI `response_format` / Anthropic `output_format` | 两协议均支持控制输出格式 | -| `parallel_tool_use` | OpenAI `parallel_tool_calls` / Anthropic `disable_parallel_tool_use` | 两协议均支持并行工具调用控制 | -| `cache_control` | 仅 Anthropic | 不晋升，仅 Anthropic 使用 | -| `reasoning_content` | 仅 OpenAI | 不晋升（但 ThinkingBlock 已覆盖 thinking 语义） | +| 字段 | 晋升原因 | +|------|---------| +| `user_id` | 多协议均支持用户标识，但字段名和嵌套位置不同 | +| `output_format` | 多协议均支持控制输出格式，但字段名不同 | +| `parallel_tool_use` | 多协议均支持并行工具调用控制，但语义方向（允许/禁止）不同 | +| `top_k` | 多协议（Gemini、OpenAI 兼容厂商、Ollama 等）均支持，但字段名和嵌套位置不同 | +| `frequency_penalty` / `presence_penalty` | OpenAI 生态广泛使用，多协议均支持类似概念 | +| `stop_reason: refusal` | OpenAI 和 Gemini 均有安全拒绝/内容过滤场景，语义一致 | ### 降级规则 当公共字段的目标协议不支持时： -- 有语义等价物 → 自动映射（如 `parallel_tool_use` → `disable_parallel_tool_use`） -- 无等价物 → 丢弃，日志 warn（如 `output_format` → Anthropic 旧模型丢弃） -- 有替代方案 → 降级策略处理（如 `output_format` → 注入合成工具） +- 有语义等价物 → 自动映射 +- 无等价物 → 丢弃，日志 warn +- 有替代方案 → 降级策略处理 --- -## 附录 E：协议适配清单模板 +## 附录 D：协议适配清单模板 适配新协议时，按以下清单逐项确认。所有项目确认后即可与引擎对接。 -### E.1 协议基本信息 +**方法调用时机**：理解各方法何时被引擎调用，有助于正确实现： +- `decodeRequest` / `encodeRequest`：引擎在 `convertBody(CHAT)` 中调用（§6.2），对每个 Chat 请求执行 decode → middleware → encode 管道 +- `decodeResponse` / `encodeResponse`：引擎在 `convertResponseBody(CHAT)` 中调用，对每个 Chat 响应执行反向管道 +- `decodeXxxRequest` / `encodeXxxRequest`：扩展层接口仅在 `supportsInterface` 返回 true 时被调用（§6.2 convertBody 分支）；返回 false 时引擎直接透传 body +- `createStreamDecoder` / `createStreamEncoder`：引擎在 `createStreamConverter` 中调用（§6.1），Decoder 来自 provider 协议（解码上游 SSE），Encoder 来自 client 协议（编码给客户端） +- `buildHeaders`：每次请求出站时调用，同协议透传也会调用 +- `encodeError`：转换失败或 Middleware 中断时调用，使用 client 协议格式编码错误响应 + +### D.1 协议基本信息 | 项目 | 说明 | |------|------| -| 协议名称 | 用于 URL 前缀和 Adapter 注册的唯一标识（如 `"openai"`, `"anthropic"`） | -| 协议版本 | 当前适配的 API 版本（如 `"2023-06-01"`） | +| 协议名称 | 用于 URL 前缀和 Adapter 注册的唯一标识 | +| 协议版本 | 当前适配的 API 版本 | | Base URL | API 服务地址 | -| 认证方式 | Header 名称和格式（如 `Authorization: Bearer` / `x-api-key`） | +| 认证方式 | Header 名称和格式 | -### E.2 接口识别 +### D.2 接口识别 | 项目 | 说明 | |------|------| | URL 路径模式 | 列出所有接口的 URL 路径和对应的 InterfaceType | | 接口能力矩阵 | 每种 InterfaceType 的支持状态（`supportsInterface`） | -| URL 映射表 | 每种 InterfaceType 的目标 URL 路径（`mapUrl`） | +| URL 映射表 | 每种 InterfaceType 的目标 URL 路径（`buildUrl`） | -### E.3 请求头构建 +### D.3 请求头构建 | 项目 | 说明 | |------|------| | 认证头 | 如何从 `provider.api_key` 构建认证 Header | | 必需 Header | 协议要求的固定 Header（如 Content-Type） | -| 可选 Header | 根据功能动态添加的 Header（如 anthropic-beta） | +| 可选 Header | 根据功能动态添加的 Header | | adapter_config 契约 | 定义本 Adapter 从 `provider.adapter_config` 读取的 key 列表和默认值 | -### E.4 核心层 — Chat 请求编解码 +### D.4 核心层 — Chat 请求编解码 + +逐字段对照 §4.1 CanonicalRequest 和 §4.2 RequestParameters 确认映射关系。 #### Decoder（协议 → Canonical） | 项目 | 说明 | |------|------| | 系统消息 | 如何提取为 `canonical.system`（顶层字段 / messages 中 / 不支持） | -| 消息角色 | 协议角色与 Canonical 角色（system/user/assistant/tool）的映射 | -| 内容块 | 每种内容类型（text/tool_use/tool_result/thinking）的解码规则 | -| 工具定义 | 如何映射为 `canonical.tools`（字段名差异：input_schema vs parameters） | -| 工具选择 | tool_choice 各变体的映射规则 | -| 参数映射 | max_tokens/temperature/top_p/stop_sequences 等参数的映射 | -| 新增公共字段 | user_id/output_format/parallel_tool_use/thinking 的提取规则 | +| 消息角色 | 协议角色与 Canonical 角色（§4.3：system/user/assistant/tool）的映射 | +| 内容块 | 逐类型对照 §4.3 ContentBlock 联合体，确认每种类型的解码规则 | +| 工具定义 | 对照 §4.4 CanonicalTool，确认字段名映射 | +| 工具选择 | 对照 §4.4 ToolChoice 联合体，确认各变体的映射规则 | +| 参数映射 | 对照 §4.2 RequestParameters，逐字段确认映射和类型转换 | +| 公共字段 | 逐字段对照 §4.1 中 `user_id`、`output_format`、`parallel_tool_use`、`thinking`，确认提取规则 | | 协议特有字段 | 仅本协议使用的字段列表，以及处理方式（忽略/记录） | | 协议约束 | 消息顺序要求、角色交替要求、必填字段等 | @@ -1632,31 +971,48 @@ Canonical Model 是**活的公共契约**，不是固定不变的。其字段集 | 系统消息注入 | 如何将 `canonical.system` 编码为协议格式 | | 消息编码 | 各角色的编码规则（特别注意 role 映射、content 结构差异） | | 角色约束处理 | 是否需要 enforceAlternation？具体策略？ | -| 工具编码 | tools/tool_choice 的编码规则 | -| 参数编码 | Canonical 参数到协议参数的映射 | -| 公共字段编码 | user_id/output_format/parallel_tool_use/thinking 的注入规则 | -| 降级处理 | 目标协议不支持的 Canonical 字段的降级策略 | +| 工具编码 | 对照 §4.4 确认 tools/tool_choice 的编码规则 | +| 参数编码 | 对照 §4.2 确认参数映射 | +| 公共字段编码 | 逐字段确认注入规则 | +| 降级处理 | 对照 §8.4 三级降级策略（自动映射/丢弃/替代方案），确认每个不支持字段的处理方式 | -### E.5 核心层 — Chat 响应编解码 +### D.5 核心层 — Chat 响应编解码 + +逐字段对照 §4.7 CanonicalResponse 确认映射关系。 + +#### Decoder（协议 → Canonical） | 项目 | 说明 | |------|------| | 响应结构 | 协议响应的顶层结构解析 | -| 内容块解码 | 各 content block 类型的解码规则 | -| 停止原因 | stop_reason / finish_reason 的映射表 | -| Token 用量 | usage 各字段的映射（注意命名差异：input_tokens vs prompt_tokens） | -| 推理内容 | reasoning_content / thinking block 的处理 | -| 协议特有内容 | 仅本协议返回的特有字段的处理 | +| 内容块解码 | 逐类型对照 §4.3 ContentBlock 联合体，确认解码规则 | +| 停止原因 | 协议原生值与 §4.7 StopReason 枚举的映射表 | +| Token 用量 | 对照 §4.7 CanonicalUsage，逐字段确认映射和命名差异 | +| 推理内容 | ThinkingBlock 的解码规则 | +| 协议特有内容 | 仅本协议返回的特有字段的处理（忽略/丢弃/记录） | -### E.6 核心层 — 流式编解码 +#### Encoder（Canonical → 协议） + +| 项目 | 说明 | +|------|------| +| 响应结构 | 如何从 CanonicalResponse 构建协议响应的顶层结构 | +| 内容块编码 | 各 ContentBlock 类型到协议格式的编码规则 | +| 停止原因 | §4.7 StopReason 到协议原生值的映射表 | +| Token 用量 | CanonicalUsage 到协议 usage 字段的编码规则 | +| 推理内容 | ThinkingBlock 的编码规则 | +| 降级处理 | Canonical 中协议不支持的 stop_reason 等值的降级映射 | + +### D.6 核心层 — 流式编解码 + +对照 §4.8 CanonicalStreamEvent 和 §7.2 StreamDecoderState 确认映射和状态设计。 #### StreamDecoder（协议 SSE → Canonical 事件） | 项目 | 说明 | |------|------| | SSE 格式 | 协议的 SSE 事件格式（named events vs delta chunks） | -| 事件映射表 | 每种协议 SSE 事件 → CanonicalStreamEvent 的映射规则 | -| 状态机设计 | 需要跟踪的状态（当前 block index、open blocks、tool call 映射等） | +| 事件映射表 | 每种协议 SSE 事件 → §4.8 CanonicalStreamEvent 的映射规则 | +| 状态机设计 | 在 §7.2 通用状态基础上，声明本协议需要的额外状态 | | UTF-8 安全 | 是否需要处理跨 chunk 的 UTF-8 截断 | | 特殊情况 | 工具调用参数乱序、无限空白检测、延迟字段等 | @@ -1664,44 +1020,56 @@ Canonical Model 是**活的公共契约**，不是固定不变的。其字段集 | 项目 | 说明 | |------|------| -| 事件映射表 | 每个 CanonicalStreamEvent → 协议 SSE chunk 的映射规则 | +| 事件映射表 | §4.8 每个 CanonicalStreamEvent → 协议 SSE chunk 的映射规则 | | 缓冲策略 | 哪些事件需要缓冲、何时输出 | | SSE 格式 | event type / data 字段的编码方式 | | 结束标记 | 如何输出流结束信号（如 `[DONE]`） | -### E.7 扩展层接口 +### D.7 扩展层接口 -对每种支持的扩展层接口（/models、/embeddings、/files、/rerank、/count_tokens），确认： +对每种扩展层接口逐项确认。当前扩展层 InterfaceType 见 §5.3 枚举（MODELS、MODEL_INFO、EMBEDDINGS、RERANK），随协议扩展可能增加。 | 项目 | 说明 | |------|------| | 接口是否存在 | 该协议是否原生支持此接口 | | URL 路径 | 接口的 URL 路径 | -| 请求格式 | 请求体的协议特有格式 → Canonical 格式的映射 | -| 响应格式 | 响应体的协议特有格式 ← Canonical 格式的映射 | +| 请求格式 | 对照 §4.9 扩展层 Canonical Models，确认请求体映射 | +| 响应格式 | 对照 §4.9 扩展层 Canonical Models，确认响应体映射 | | 不支持时策略 | 透传 / 返回空响应 / 返回错误 | -### E.8 错误编码 +### D.8 错误编码 | 项目 | 说明 | |------|------| | 错误响应格式 | 协议的错误响应 JSON 结构 | -| encodeError | ConversionError → 协议错误格式的编码规则 | +| encodeError | §9.1 ConversionError → 协议错误格式的编码规则 | | HTTP 状态码 | 协议常用的错误状态码映射 | -### E.9 自检清单 +### D.9 自检清单 -- [ ] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 -- [ ] 所有 InterfaceType 的 `mapUrl` 映射已确定 -- [ ] Chat 请求的 Decoder 和 Encoder 已实现 -- [ ] Chat 响应的 Decoder 和 Encoder 已实现 -- [ ] 流式 StreamDecoder 和 StreamEncoder 已实现 -- [ ] `buildHeaders(provider)` 已实现 -- [ ] `encodeError` 已实现 -- [ ] 扩展层接口的编解码已实现（支持的接口） -- [ ] 角色映射和消息顺序约束已处理 -- [ ] 工具调用（tool_calls / tool_use / tool_result）的编解码已处理 -- [ ] stop_reason / finish_reason 映射表已确认 -- [ ] usage 字段映射已确认 -- [ ] 协议特有字段已识别并确定处理方式（忽略/降级） -- [ ] adapter_config 契约已文档化 +| 章节 | 检查项 | +|------|--------| +| D.2 | [ ] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | +| D.2 | [ ] 所有 InterfaceType 的 `buildUrl` 映射已确定 | +| D.3 | [ ] `buildHeaders(provider)` 已实现，adapter_config 契约已文档化 | +| D.4 | [ ] Chat 请求的 Decoder 和 Encoder 已实现（逐字段对照 §4.1/§4.2） | +| D.4 | [ ] 角色映射和消息顺序约束已处理 | +| D.4 | [ ] 工具调用（tool_use / tool_result）的编解码已处理 | +| D.4 | [ ] 协议特有字段已识别并确定处理方式（忽略/降级） | +| D.5 | [ ] Chat 响应的 Decoder 和 Encoder 已实现（逐字段对照 §4.7） | +| D.5 | [ ] stop_reason 映射表已确认 | +| D.5 | [ ] usage 字段映射已确认 | +| D.6 | [ ] 流式 StreamDecoder 和 StreamEncoder 已实现（对照 §4.8） | +| D.7 | [ ] 扩展层接口的编解码已实现（支持的接口） | +| D.8 | [ ] `encodeError` 已实现 | + +--- + +## 附录 E：协议适配文档索引 + +| 协议 | 适配文档 | +|------|---------| +| OpenAI | [conversion_openai.md](./conversion_openai.md) | +| Anthropic | [conversion_anthropic.md](./conversion_anthropic.md) | + +新增协议时，按附录 D 模板编撰适配文档，并将链接添加到上表。 diff --git a/docs/conversion_openai.md b/docs/conversion_openai.md new file mode 100644 index 0000000..5d715ca --- /dev/null +++ b/docs/conversion_openai.md @@ -0,0 +1,1165 @@ +# OpenAI 协议适配清单 + +> 依据 [conversion_design.md](./conversion_design.md) 附录 D 模板编撰，覆盖 OpenAI API 的全部对接细节。 + +--- + +## 目录 + +1. [协议基本信息](#1-协议基本信息) +2. [接口识别](#2-接口识别) +3. [请求头构建](#3-请求头构建) +4. [核心层 — Chat 请求编解码](#4-核心层--chat-请求编解码) +5. [核心层 — Chat 响应编解码](#5-核心层--chat-响应编解码) +6. [核心层 — 流式编解码](#6-核心层--流式编解码) +7. [扩展层接口](#7-扩展层接口) +8. [错误编码](#8-错误编码) +9. [自检清单](#9-自检清单) + +--- + +## 1. 协议基本信息 + +| 项目 | 说明 | +| -------- | ----------------------------------- | +| 协议名称 | `"openai"` | +| 协议版本 | 无固定版本头，API 持续演进 | +| Base URL | `https://api.openai.com` | +| 认证方式 | `Authorization: Bearer ` | + +--- + +## 2. 接口识别 + +### 2.1 URL 路径模式 + +| URL 路径 | InterfaceType | +| ------------------------ | ------------- | +| `/v1/chat/completions` | CHAT | +| `/v1/models` | MODELS | +| `/v1/models/{model}` | MODEL_INFO | +| `/v1/embeddings` | EMBEDDINGS | +| `/v1/rerank` | RERANK | + +### 2.2 接口能力矩阵 + +``` +OpenAI.supportsInterface(type): + CHAT: return true + MODELS: return true + MODEL_INFO: return true + EMBEDDINGS: return true + RERANK: return true + AUDIO: return true + IMAGES: return true + default: return false +``` + +### 2.3 URL 映射表 + +``` +OpenAI.buildUrl(nativePath, interfaceType): + switch interfaceType: + case CHAT: return "/v1/chat/completions" + case MODELS: return "/v1/models" + case MODEL_INFO: return "/v1/models/{modelId}" + case EMBEDDINGS: return "/v1/embeddings" + case RERANK: return "/v1/rerank" + default: return nativePath +``` + +--- + +## 3. 请求头构建 + +### 3.1 buildHeaders + +``` +OpenAI.buildHeaders(provider): + result = {} + result["Authorization"] = "Bearer " + provider.api_key + if provider.adapter_config["organization"]: + result["OpenAI-Organization"] = provider.adapter_config["organization"] + result["Content-Type"] = "application/json" + return result +``` + +### 3.2 adapter_config 契约 + +| Key | 类型 | 必填 | 默认值 | 说明 | +| ---------------- | ------ | ---- | ------ | ------------------------------------------------------ | +| `organization` | String | 否 | — | OpenAI 组织标识，映射为 `OpenAI-Organization` Header | + +--- + +## 4. 核心层 — Chat 请求编解码 + +### 4.1 Decoder（OpenAI → Canonical） + +#### 系统消息 + +OpenAI 支持两种系统指令角色：`system` 和 `developer`（o1 及更新模型推荐使用 `developer`）。两者均提取为 `canonical.system`。 + +``` +decodeSystemPrompt(messages): + systemMsgs = messages.filter(m => m.role == "system" || m.role == "developer") + remaining = messages.filter(m => m.role != "system" && m.role != "developer") + if systemMsgs.length == 0: return {system: None, messages: remaining} + return {system: systemMsgs.map(m => extractText(m.content)).join("\n\n"), messages: remaining} +``` + +从 `messages` 数组中提取 `role="system"` 和 `role="developer"` 的消息，合并为 `canonical.system`（String），剩余消息作为 `canonical.messages`。 + +#### 消息角色映射 + +| OpenAI role | Canonical role | 说明 | +| ------------- | --------------------------- | ------------------------------------------------------ | +| `system` | 提取为 `canonical.system` | 不进入 messages 数组 | +| `developer` | 提取为 `canonical.system` | 不进入 messages 数组；o1+ 推荐使用 | +| `user` | `user` | 直接映射 | +| `assistant` | `assistant` | 需处理 tool_calls 结构差异 | +| `tool` | `tool` | tool_call_id → tool_use_id | +| `function` | `tool` | **已废弃**，转为 tool 角色（见下方废弃字段处理） | + +#### 内容块解码 + +``` +decodeUserContent(content): + if content is String: return [{type: "text", text: content}] + return content.map(part => { + switch part.type: + "text" → {type: "text", text: part.text} + "image_url" → {type: "image", source: {url: part.image_url.url, detail: part.image_url.detail}} + "input_audio" → {type: "audio", source: {data: part.input_audio.data, format: part.input_audio.format}} + "file" → {type: "file", source: {file_data: part.file.file_data, file_id: part.file.file_id, filename: part.file.filename}} + }) + +decodeMessage(msg): + switch msg.role: + case "user": + return {role: "user", content: decodeUserContent(msg.content)} + case "assistant": + blocks = [] + if msg.content: + if msg.content is String: + blocks.append({type: "text", text: msg.content}) + else: + blocks.append(...msg.content.filter(p => p.type == "text").map(p => ({type: "text", text: p.text}))) + for refusal in msg.content.filter(p => p.type == "refusal"): + blocks.append({type: "text", text: refusal.refusal}) + if msg.refusal: blocks.append({type: "text", text: msg.refusal}) + if msg.tool_calls: + for tc in msg.tool_calls: + switch tc.type: + "function" → blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, + input: JSON.parse(tc.function.arguments)}) + "custom" → blocks.append({type: "tool_use", id: tc.id, name: tc.custom.name, + input: tc.custom.input}) + if msg.function_call: // 已废弃，兼容处理 + blocks.append({type: "tool_use", id: generateId(), name: msg.function_call.name, + input: JSON.parse(msg.function_call.arguments)}) + return {role: "assistant", content: blocks} + case "tool": + return {role: "tool", content: [{ + type: "tool_result", tool_use_id: msg.tool_call_id, + content: msg.content is String ? msg.content : extractText(msg.content), + is_error: false}]} + case "function": // 已废弃，兼容处理 + return {role: "tool", content: [{ + type: "tool_result", tool_use_id: msg.name, + content: msg.content, is_error: false}]} +``` + +**关键差异**： + +- OpenAI 将 `tool_calls` 放在 message 顶层，Canonical 放在 `content` 数组中作为 `ToolUseBlock` +- OpenAI 用 `tool_call_id` 标识工具结果，Canonical 用 `tool_use_id` +- `refusal` 编码为 text block +- `developer` 角色与 `system` 角色同语义，均提取为 canonical.system +- 自定义工具（`type: "custom"`）的 `input` 为字符串，Function 工具的 `arguments` 为 JSON 字符串 + +#### 工具定义 + +OpenAI 有两类工具： + +**Function 工具**（`type: "function"`）： + +| OpenAI | Canonical | 说明 | +| -------------------------------- | ------------------------ | --------------------------- | +| `tools[].type: "function"` | — | OpenAI 多一层 function 包装 | +| `tools[].function.name` | `tools[].name` | 直接映射 | +| `tools[].function.description` | `tools[].description` | 直接映射 | +| `tools[].function.parameters` | `tools[].input_schema` | 字段名不同 | +| `tools[].function.strict` | — | 协议特有，忽略 | + +**Custom 工具**（`type: "custom"`）：无 `input_schema`，使用自定义格式（text/grammar）。不映射为 CanonicalTool，跨协议时丢弃。 + +``` +decodeTools(tools): + result = [] + for tool in (tools ?? []): + if tool.type == "function": + result.append(CanonicalTool { + name: tool.function.name, + description: tool.function.description, + input_schema: tool.function.parameters + }) + // type == "custom": 跨协议时丢弃 + return result.length > 0 ? result : None +``` + +#### 工具选择 + +OpenAI `tool_choice` 有多种形态： + +| OpenAI tool_choice | Canonical ToolChoice | 说明 | +| --------------------------------------------------------- | ------------------------ | ------------------------------------------------------- | +| `"auto"` | `{type: "auto"}` | 直接映射 | +| `"none"` | `{type: "none"}` | 直接映射 | +| `"required"` | `{type: "any"}` | 语义等价 | +| `{type: "function", function: {name}}` | `{type: "tool", name}` | 命名工具 | +| `{type: "custom", custom: {name}}` | `{type: "tool", name}` | 自定义工具 | +| `{type: "allowed_tools", allowed_tools: {mode, tools}}` | — | 协议特有，降级为 mode 映射（auto→auto, required→any） | + +``` +decodeToolChoice(tool_choice): + if tool_choice is String: + switch tool_choice: + "auto" → {type: "auto"} + "none" → {type: "none"} + "required" → {type: "any"} + elif tool_choice.type == "function": + return {type: "tool", name: tool_choice.function.name} + elif tool_choice.type == "custom": + return {type: "tool", name: tool_choice.custom.name} + elif tool_choice.type == "allowed_tools": + mode = tool_choice.allowed_tools.mode // "auto" or "required" + return mode == "required" ? {type: "any"} : {type: "auto"} +``` + +#### 参数映射 + +| OpenAI | Canonical | 说明 | +| -------------------------- | ------------------------------------- | --------------------------- | +| `max_completion_tokens` | `parameters.max_tokens` | 优先使用；o-series 模型专用 | +| `max_tokens` | `parameters.max_tokens` | 已废弃，作为回退 | +| `temperature` | `parameters.temperature` | 直接映射 | +| `top_p` | `parameters.top_p` | 直接映射 | +| `frequency_penalty` | `parameters.frequency_penalty` | 直接映射 | +| `presence_penalty` | `parameters.presence_penalty` | 直接映射 | +| `stop` (String or Array) | `parameters.stop_sequences` (Array) | Decoder 规范化为 Array | +| `stream` | `stream` | 直接映射 | + +``` +decodeParameters(raw): + return RequestParameters { + max_tokens: raw.max_completion_tokens ?? raw.max_tokens, + temperature: raw.temperature, + top_p: raw.top_p, + frequency_penalty: raw.frequency_penalty, + presence_penalty: raw.presence_penalty, + stop_sequences: normalizeStop(raw.stop) + } + +normalizeStop(stop): + if stop is String: return [stop] + if stop is Array: return stop + return None +``` + +#### 公共字段 + +| OpenAI | Canonical | 提取规则 | +| ----------------------- | --------------------- | -------------------- | +| `user` | `user_id` | 顶层字段，直接提取 | +| `response_format` | `output_format` | 按类型解码 | +| `parallel_tool_calls` | `parallel_tool_use` | 布尔值直接映射 | +| `reasoning_effort` | `thinking` | 映射为 thinking 配置 | + +``` +decodeOutputFormat(format): + if format is None: return None + switch format.type: + "json_object" → {type: "json_object"} + "json_schema" → {type: "json_schema", json_schema: format.json_schema} + "text" → null // 默认格式，无需设置 + +decodeThinking(reasoning_effort): + if reasoning_effort is None: return None + if reasoning_effort == "none": return ThinkingConfig {type: "disabled"} + effort = reasoning_effort == "minimal" ? "low" : reasoning_effort + return ThinkingConfig {type: "enabled", effort: effort} +``` + +**`reasoning_effort` 映射说明**： + +- `"none"` → `thinking.type = "disabled"`（不执行推理） +- `"minimal"` → `thinking.effort = "low"`（Canonical 无 minimal 级别，降级为 low） +- `"low"` / `"medium"` / `"high"` / `"xhigh"` → 直接映射 + +#### 废弃字段兼容 + +| 废弃字段 | 替代字段 | Decoder 处理 | +| ----------------- | --------------- | -------------------------------------------------- | +| `functions` | `tools` | 转换为 `tools` 格式（`type: "function"` 包装） | +| `function_call` | `tool_choice` | 转换为 `tool_choice` 格式 | + +``` +decodeDeprecatedFields(raw): + // functions → tools（仅当 tools 未设置时） + if raw.tools is None && raw.functions: + raw.tools = raw.functions.map(f => ({ + type: "function", + function: {name: f.name, description: f.description, parameters: f.parameters}})) + // function_call → tool_choice（仅当 tool_choice 未设置时） + if raw.tool_choice is None && raw.function_call: + if raw.function_call == "none": raw.tool_choice = "none" + elif raw.function_call == "auto": raw.tool_choice = "auto" + else: raw.tool_choice = {type: "function", function: {name: raw.function_call.name}} +``` + +#### 协议特有字段 + +| 字段 | 处理方式 | +| -------------------------------- | ------------------------ | +| `seed` | 忽略（无跨协议等价语义） | +| `logprobs` | 忽略 | +| `top_logprobs` | 忽略 | +| `logit_bias` | 忽略 | +| `n` | 忽略（仅支持单选择） | +| `service_tier` | 忽略 | +| `store` | 忽略 | +| `metadata` | 忽略 | +| `modalities` | 忽略（多模态扩展时启用） | +| `audio` | 忽略（多模态扩展时启用） | +| `prediction` | 忽略 | +| `stream_options` | 忽略 | +| `safety_identifier` | 忽略 | +| `prompt_cache_key` | 忽略 | +| `prompt_cache_retention` | 忽略 | +| `verbosity` | 忽略 | +| `web_search_options` | 忽略 | +| `tools[].function.strict` | 忽略 | +| `tools[].custom` (custom 工具) | 跨协议时丢弃 | + +#### 协议约束 + +- `messages` 中 `tool` 角色必须紧接在对应的 `assistant`（含 tool_calls）之后 +- `tool` 消息的 `tool_call_id` 必须与 assistant 消息中的 `tool_calls[].id` 匹配 +- `stream_options.include_usage` 可选，OpenAI 特有 +- `stop` 参数在 o3/o4-mini 等最新推理模型上不可用 + +### 4.2 Encoder（Canonical → OpenAI） + +#### 模型名称 + +使用 `provider.model_name` 覆盖 `canonical.model`。 + +#### 系统消息注入 + +将 `canonical.system` 编码为 `messages[0].role="system"` 的消息，置于 messages 数组头部。 + +``` +encodeSystemPrompt(canonical): + messages = [] + if canonical.system is String: + messages.append({role: "system", content: canonical.system}) + elif canonical.system is Array: + text = canonical.system.map(s => s.text).join("\n\n") + messages.append({role: "system", content: text}) + return messages + encodeMessages(canonical.messages) +``` + +#### 消息编码 + +``` +encodeUserContent(blocks): + if blocks.length == 1 && blocks[0].type == "text": + return blocks[0].text + return blocks.map(b => { + switch b.type: + "text" → {type: "text", text: b.text} + "image" → {type: "image_url", image_url: {url: b.source.url, detail: b.source.detail}} + "audio" → {type: "input_audio", input_audio: {data: b.source.data, format: b.source.format}} + "file" → {type: "file", file: {file_data: b.source.file_data, file_id: b.source.file_id, filename: b.source.filename}} + }) + +encodeMessage(msg): + switch msg.role: + case "user": + return {role: "user", content: encodeUserContent(msg.content)} + case "assistant": + message = {} + textParts = msg.content.filter(b => b.type == "text") + toolUses = msg.content.filter(b => b.type == "tool_use") + if textParts.length > 0: + message.content = textParts.map(b => b.text).join("") + elif toolUses.length > 0: + message.content = null + else: + message.content = "" + if toolUses.length > 0: + message.tool_calls = toolUses.map(tu => ({ + id: tu.id, type: "function", + function: {name: tu.name, arguments: JSON.stringify(tu.input)}})) + return {role: "assistant", ...message} + case "tool": + results = msg.content.filter(b => b.type == "tool_result") + if results.length > 0: + return {role: "tool", tool_call_id: results[0].tool_use_id, + content: results[0].content} +``` + +#### 角色约束处理 + +OpenAI 要求 assistant 和 user 角色严格交替。当 Canonical 消息序列中存在连续同角色消息时，需合并为单条消息。 + +#### 工具编码 + +``` +encodeTools(canonical): + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + type: "function", + function: {name: t.name, description: t.description, parameters: t.input_schema}})) + if canonical.tool_choice: + result.tool_choice = encodeToolChoice(canonical.tool_choice) + +encodeToolChoice(choice): + switch choice.type: + "auto" → "auto" + "none" → "none" + "any" → "required" + "tool" → {type: "function", function: {name: choice.name}} +``` + +#### 公共字段编码 + +``` +encodeOutputFormat(format): + if format is None: return None + switch format.type: + "json_object" → {type: "json_object"} + "json_schema" → {type: "json_schema", json_schema: format.json_schema} + +encodeRequest(canonical, provider): + result = { + model: provider.model_name, + messages: encodeSystemPrompt(canonical) + canonical.messages.flatMap(encodeMessage), + stream: canonical.stream + } + + // 参数 + if canonical.parameters.max_tokens: + result.max_completion_tokens = canonical.parameters.max_tokens + if canonical.parameters.temperature is not None: + result.temperature = canonical.parameters.temperature + if canonical.parameters.top_p is not None: + result.top_p = canonical.parameters.top_p + if canonical.parameters.frequency_penalty is not None: + result.frequency_penalty = canonical.parameters.frequency_penalty + if canonical.parameters.presence_penalty is not None: + result.presence_penalty = canonical.parameters.presence_penalty + if canonical.parameters.stop_sequences: + result.stop = canonical.parameters.stop_sequences + + // 工具 + if canonical.tools: + result.tools = canonical.tools.map(t => ({ + type: "function", + function: {name: t.name, description: t.description, parameters: t.input_schema}})) + if canonical.tool_choice: + result.tool_choice = encodeToolChoice(canonical.tool_choice) + + // 公共字段 + if canonical.user_id: + result.user = canonical.user_id + if canonical.output_format: + result.response_format = encodeOutputFormat(canonical.output_format) + if canonical.parallel_tool_use != null: + result.parallel_tool_calls = canonical.parallel_tool_use + if canonical.thinking: + if canonical.thinking.type == "disabled": + result.reasoning_effort = "none" + elif canonical.thinking.effort: + result.reasoning_effort = canonical.thinking.effort + else: + result.reasoning_effort = "medium" + return result +``` + +**编码说明**： + +- 使用 `max_completion_tokens`（非废弃的 `max_tokens`）输出 token 上限 +- `frequency_penalty` 和 `presence_penalty` 仅在非 null 时输出 +- `thinking` 映射为 `reasoning_effort`：disabled → "none"，有 effort 值则直接映射，否则默认 "medium" + +#### 降级处理 + +对照架构文档 §8.4 三级降级策略，确认每个不支持字段的处理： + +| Canonical 字段 | OpenAI 不支持时 | 降级策略 | +| --------------------------------- | -------------------------------------------------- | ---------------------------------- | +| `thinking.budget_tokens` | OpenAI 使用 `reasoning_effort` 而非 token 级控制 | 替代方案：估算映射为 effort 近似值 | +| `stop_reason: "content_filter"` | `finish_reason: "content_filter"` | 自动映射（OpenAI 支持此值） | +| `stop_reason: "stop_sequence"` | OpenAI 无独立值 | 自动映射为 `"stop"` | +| `parameters.top_k` | OpenAI 不支持 `top_k` | 丢弃 | + +--- + +## 5. 核心层 — Chat 响应编解码 + +逐字段对照 §4.7 CanonicalResponse 确认映射关系。 + +### 5.1 响应结构 + +``` +OpenAI 响应顶层结构: +{ + id: String, + object: "chat.completion", + created: Number, + model: String, + choices: [{ + index: 0, + message: { + role: "assistant", + content: String | null, + refusal: String | null, + tool_calls: [{ + id: String, + type: "function", + function: { name: String, arguments: String } + }] | null, + annotations: [{ + type: "url_citation", + url_citation: { start_index, end_index, title, url } + }] | null, + audio: { id, data, expires_at, transcript } | null + }, + finish_reason: String, + logprobs: { content, refusal } | null + }], + usage: { + prompt_tokens: Number, + completion_tokens: Number, + total_tokens: Number, + prompt_tokens_details: { cached_tokens, audio_tokens }, + completion_tokens_details: { reasoning_tokens, audio_tokens, accepted_prediction_tokens, rejected_prediction_tokens } + }, + service_tier: String | null, + system_fingerprint: String | null +} +``` + +**兼容性说明**：部分 OpenAI 兼容提供商（如 DeepSeek）在 response 中返回非标准的 `reasoning_content` 字段。Decoder 会检测并处理此字段，将其解码为 ThinkingBlock。 + +### 5.2 Decoder（OpenAI → Canonical） + +``` +decodeResponse(openaiResp): + choice = openaiResp.choices[0] + blocks = [] + if choice.message.content: blocks.append({type: "text", text: choice.message.content}) + if choice.message.refusal: blocks.append({type: "text", text: choice.message.refusal}) + + // reasoning_content: 非标准字段，来自兼容提供商 + if choice.message.reasoning_content: + blocks.append({type: "thinking", thinking: choice.message.reasoning_content}) + + if choice.message.tool_calls: + for tc in choice.message.tool_calls: + switch tc.type: + "function" → blocks.append({type: "tool_use", id: tc.id, name: tc.function.name, + input: JSON.parse(tc.function.arguments)}) + "custom" → blocks.append({type: "tool_use", id: tc.id, name: tc.custom.name, + input: tc.custom.input}) + return CanonicalResponse { + id: openaiResp.id, + model: openaiResp.model, + content: blocks, + stop_reason: mapFinishReason(choice.finish_reason), + usage: decodeUsage(openaiResp.usage) + } +``` + +**内容块解码**： + +- `content` → TextBlock +- `refusal` → TextBlock +- `reasoning_content` → ThinkingBlock（非标准字段，来自兼容提供商） +- `tool_calls[].type: "function"` → ToolUseBlock（从 message 顶层提取到 content 数组） +- `tool_calls[].type: "custom"` → ToolUseBlock（input 为字符串） + +**停止原因映射**： + +| OpenAI finish_reason | Canonical stop_reason | 说明 | +| -------------------- | --------------------- | ---------------------------- | +| `"stop"` | `"end_turn"` | 自然结束或匹配 stop sequence | +| `"length"` | `"max_tokens"` | 达到 token 上限 | +| `"tool_calls"` | `"tool_use"` | 模型调用工具 | +| `"content_filter"` | `"content_filter"` | 内容过滤 | +| `"function_call"` | `"tool_use"` | 已废弃，等同于 tool_calls | +| 其他 | `"end_turn"` | 兜底 | + +**Token 用量映射**： + +| OpenAI usage | Canonical Usage | +| ---------------------------------------------- | -------------------------------- | +| `prompt_tokens` | `input_tokens` | +| `completion_tokens` | `output_tokens` | +| `prompt_tokens_details.cached_tokens` | `cache_read_tokens` | +| — | `cache_creation_tokens` (null) | +| `completion_tokens_details.reasoning_tokens` | `reasoning_tokens` | + +``` +decodeUsage(usage): + if usage is None: return CanonicalUsage {input_tokens: 0, output_tokens: 0} + return CanonicalUsage { + input_tokens: usage.prompt_tokens, + output_tokens: usage.completion_tokens, + cache_read_tokens: usage.prompt_tokens_details?.cached_tokens, + cache_creation_tokens: null, + reasoning_tokens: usage.completion_tokens_details?.reasoning_tokens + } +``` + +**协议特有内容**： + +| 字段 | 处理方式 | +| ---------------------- | ---------------------------------------------- | +| `refusal` | 解码为 text block | +| `reasoning_content` | 解码为 ThinkingBlock（非标准，来自兼容提供商） | +| `annotations` | 忽略（协议特有，不晋升为公共字段） | +| `audio` | 忽略（多模态扩展时启用） | +| `logprobs` | 忽略 | +| `service_tier` | 忽略 | +| `system_fingerprint` | 忽略 | +| `created` | 忽略 | + +### 5.3 Encoder（Canonical → OpenAI） + +``` +encodeResponse(canonical): + textParts = canonical.content.filter(b => b.type == "text") + thinkingParts = canonical.content.filter(b => b.type == "thinking") + toolUses = canonical.content.filter(b => b.type == "tool_use") + + message = {role: "assistant"} + if textParts.length > 0: + message.content = textParts.map(b => b.text).join("") + elif toolUses.length > 0: + message.content = null + else: + message.content = "" + + // reasoning_content: 非标准字段，输出给兼容提供商 + if thinkingParts.length > 0: + message.reasoning_content = thinkingParts.map(b => b.thinking).join("") + + if toolUses.length > 0: + message.tool_calls = toolUses.map(tu => ({ + id: tu.id, type: "function", + function: {name: tu.name, arguments: JSON.stringify(tu.input)}})) + + return { + id: canonical.id, + object: "chat.completion", + model: canonical.model, + choices: [{ + index: 0, + message: message, + finish_reason: mapCanonicalToFinishReason(canonical.stop_reason) + }], + usage: encodeUsage(canonical.usage) + } + +encodeUsage(usage): + return { + prompt_tokens: usage.input_tokens, + completion_tokens: usage.output_tokens, + total_tokens: usage.input_tokens + usage.output_tokens, + prompt_tokens_details: usage.cache_read_tokens ? {cached_tokens: usage.cache_read_tokens} : null, + completion_tokens_details: usage.reasoning_tokens ? {reasoning_tokens: usage.reasoning_tokens} : null + } +``` + +**内容块编码**： + +- TextBlock → `message.content` +- ToolUseBlock → `message.tool_calls`（从 content 数组提取到 message 顶层） +- ThinkingBlock → `reasoning_content`（非标准字段，兼容提供商使用） + +**停止原因映射**： + +| Canonical stop_reason | OpenAI finish_reason | +| --------------------- | -------------------- | +| `"end_turn"` | `"stop"` | +| `"max_tokens"` | `"length"` | +| `"tool_use"` | `"tool_calls"` | +| `"content_filter"` | `"content_filter"` | +| `"stop_sequence"` | `"stop"` | +| `"refusal"` | `"stop"` | +| 其他 | `"stop"` | + +**降级处理**： + +| Canonical 字段 | OpenAI 不支持时 | 降级策略 | +| -------------------------------- | --------------- | ----------------------------- | +| `stop_reason: "stop_sequence"` | OpenAI 无独立值 | 映射为 `"stop"`（自动映射） | +| `stop_reason: "refusal"` | OpenAI 无独立值 | 映射为 `"stop"`（自动映射） | +| `cache_creation_tokens` | OpenAI 无此字段 | 丢弃 | + +--- + +## 6. 核心层 — 流式编解码 + +### 6.1 SSE 格式 + +OpenAI 使用无命名的 SSE delta chunk： + +``` +data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"gpt-4", + "choices":[{"index":0,"delta":{...},"finish_reason":null}]} + +data: [DONE] +``` + +**delta 结构**： + +``` +delta: { + role?: "assistant" | "user" | "system" | "developer" | "tool", + content?: String, + tool_calls?: [{index: Number, id?: String, function?: {name?: String, arguments?: String}, type?: "function"}], + refusal?: String, + function_call?: {name?: String, arguments?: String} // 已废弃 +} +``` + +**兼容性说明**：部分兼容提供商在 delta 中返回非标准的 `reasoning_content` 字段。StreamDecoder 会检测并处理。 + +### 6.2 StreamDecoder（OpenAI SSE → Canonical 事件） + +| OpenAI chunk | Canonical 事件 | 说明 | +| ------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------- | +| 首个 chunk (id/model) | MessageStartEvent | 从顶层字段提取 id、model | +| `delta.content` 首次出现 | ContentBlockStart(text) + ContentBlockDelta(text_delta) | 新 text block 开始 | +| `delta.content` 后续 | ContentBlockDelta(text_delta) | 追加文本 | +| `delta.tool_calls[i]` 首次出现 | ContentBlockStart(tool_use) | 新 tool block，提取 id、name | +| `delta.tool_calls[i].function.arguments` | ContentBlockDelta(input_json_delta) | 增量 JSON 参数 | +| `delta.reasoning_content` 首次 | ContentBlockStart(thinking) + ContentBlockDelta(thinking_delta) | 新 thinking block（非标准，来自兼容提供商） | +| `delta.reasoning_content` 后续 | ContentBlockDelta(thinking_delta) | 追加思考内容 | +| `delta.refusal` 首次 | ContentBlockStart(text) + ContentBlockDelta(text_delta) | 新 text block | +| `finish_reason` 非空 | ContentBlockStop × N + MessageDeltaEvent + MessageStopEvent | 关闭所有 open blocks | +| usage chunk（choices=[]） | MessageDeltaEvent(usage) | `stream_options.include_usage` 触发的用量 chunk | +| `[DONE]` | flush() | 触发 decoder flush | + +**Decoder 伪代码**： + +``` +StreamDecoder.processChunk(rawChunk): + events = [] + + // 解析 SSE data + if rawChunk == "[DONE]": + // 关闭所有 open blocks + for idx in openBlocks: + events.append(ContentBlockStopEvent {index: idx}) + if messageStarted: + events.append(MessageStopEvent {}) + return events + + data = JSON.parse(rawChunk) + + // 首个 chunk: MessageStart + if !messageStarted: + events.append(MessageStartEvent {message: {id: data.id, model: data.model, usage: null}}) + messageStarted = true + + for choice in data.choices: + delta = choice.delta + + // role 出现时不产生事件（仅用于首个 chunk 标记） + + // text content + if delta.content != null: + if !openBlocks.has(textBlockIndex): + events.append(ContentBlockStartEvent {index: textBlockIndex, content_block: {type: "text", text: ""}}) + openBlocks.add(textBlockIndex) + currentBlockType[textBlockIndex] = "text" + events.append(ContentBlockDeltaEvent {index: textBlockIndex, delta: {type: "text_delta", text: delta.content}}) + + // reasoning_content (非标准，来自兼容提供商) + if delta.reasoning_content != null: + if !openBlocks.has(thinkingBlockIndex): + events.append(ContentBlockStartEvent {index: thinkingBlockIndex, content_block: {type: "thinking", thinking: ""}}) + openBlocks.add(thinkingBlockIndex) + currentBlockType[thinkingBlockIndex] = "thinking" + events.append(ContentBlockDeltaEvent {index: thinkingBlockIndex, delta: {type: "thinking_delta", thinking: delta.reasoning_content}}) + + // refusal + if delta.refusal != null: + if !openBlocks.has(refusalBlockIndex): + events.append(ContentBlockStartEvent {index: refusalBlockIndex, content_block: {type: "text", text: ""}}) + openBlocks.add(refusalBlockIndex) + events.append(ContentBlockDeltaEvent {index: refusalBlockIndex, delta: {type: "text_delta", text: delta.refusal}}) + + // tool calls + if delta.tool_calls: + for tc in delta.tool_calls: + idx = tc.index + if tc.id != null: + // 新 tool call block + toolCallIdMap[idx] = tc.id + toolCallNameMap[idx] = tc.function?.name + toolCallArguments[idx] = "" + blockIndex = allocateBlockIndex(idx) + events.append(ContentBlockStartEvent { + index: blockIndex, + content_block: {type: "tool_use", id: tc.id, name: tc.function?.name, input: {}}}) + openBlocks.add(blockIndex) + currentBlockType[blockIndex] = "tool_use" + currentBlockId[blockIndex] = idx + if tc.function?.arguments: + toolCallArguments[currentBlockId[toolUseBlockIndex]] += tc.function.arguments + events.append(ContentBlockDeltaEvent { + index: toolUseBlockIndex, + delta: {type: "input_json_delta", partial_json: tc.function.arguments}}) + + // finish_reason + if choice.finish_reason != null: + for idx in openBlocks: + events.append(ContentBlockStopEvent {index: idx}) + openBlocks.clear() + events.append(MessageDeltaEvent {delta: {stop_reason: mapFinishReason(choice.finish_reason)}, usage: null}) + events.append(MessageStopEvent {}) + + // usage chunk (choices 为空) + if data.choices.length == 0 && data.usage: + accumulatedUsage = decodeUsage(data.usage) + events.append(MessageDeltaEvent {delta: {stop_reason: null}, usage: accumulatedUsage}) + + return events +``` + +### 6.3 StreamDecoder 状态机 + +``` +StreamDecoderState { + messageStarted: Boolean + openBlocks: Set + currentBlockType: Map + currentBlockId: Map + toolCallIdMap: Map // OpenAI tool_calls 数组索引 → id + toolCallNameMap: Map // OpenAI tool_calls 数组索引 → name + toolCallArguments: Map // OpenAI tool_calls 数组索引 → 累积参数 + textBlockStarted: Boolean // 追踪 text block 生命周期 + thinkingBlockStarted: Boolean // 追踪 thinking block 生命周期（非标准） + utf8Remainder: Option // UTF-8 跨 chunk 安全 + accumulatedUsage: Option +} +``` + +**关键处理**： + +- **工具调用索引映射**：OpenAI `tool_calls[i]` 的 `i` 不一定是连续的，需要用 Map 维护索引到 id/name 的映射 +- **参数累积**：`tool_calls[i].function.arguments` 是增量 JSON 片段，需要累积直到 block 结束 +- **UTF-8 安全**：跨 chunk 截断的 UTF-8 字节需要用 `utf8Remainder` 缓冲 +- **`reasoning_content`**：非标准字段，来自兼容提供商（如 DeepSeek），处理方式与 `content` 类似 +- **usage chunk**：当 `stream_options.include_usage` 启用时，最后一个 chunk 的 `choices` 为空数组，仅含 `usage` + +### 6.4 StreamEncoder（Canonical → OpenAI SSE） + +| Canonical 事件 | OpenAI chunk | 说明 | +| ----------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- | +| MessageStartEvent | `{id, model, object: "chat.completion.chunk", choices:[{delta:{role:"assistant"}, index:0}]}` | 首个 chunk | +| ContentBlockStart(text) | 缓冲，不输出 | 等待首次 delta 时合并输出 | +| ContentBlockDelta(text_delta) | `{choices:[{delta:{content:"..."}}]}` | 首次输出时合并 block_start 信息 | +| ContentBlockStart(tool_use) | 缓冲，不输出 | 等待首次 delta 时合并输出 | +| ContentBlockDelta(input_json_delta) | `{choices:[{delta:{tool_calls:[{index, id?, function:{name?, arguments}}]}}]}` | 首次含 id 和 name，后续仅含 arguments | +| ContentBlockStart(thinking) | 缓冲，不输出 | 等待首次 delta | +| ContentBlockDelta(thinking_delta) | `{choices:[{delta:{reasoning_content:"..."}}]}` | 非标准字段（兼容提供商使用） | +| ContentBlockStop | 不输出 | 静默 | +| MessageDeltaEvent | `{choices:[{delta:{}, finish_reason:"..."}]}` | 包含 stop_reason 映射 | +| MessageDeltaEvent(usage only) | `{choices:[], usage: {...}}` | 用量信息 chunk | +| MessageStopEvent | `data: [DONE]` | 流结束 | +| PingEvent | 丢弃 | 不输出 | +| ErrorEvent | 丢弃 | 不输出（OpenAI 无流式错误事件） | + +**Encoder 伪代码**： + +``` +StreamEncoderState { + bufferedStart: Option // 缓冲的 block start 事件 + toolCallIndexMap: Map // tool_use_id → OpenAI tool_calls 数组索引 + nextToolCallIndex: Integer // 下一个可用索引 +} + +StreamEncoder.encodeEvent(event): + switch event.type: + case "message_start": + return [{id: event.message.id, model: event.message.model, + object: "chat.completion.chunk", created: now(), + choices: [{index: 0, delta: {role: "assistant"}, finish_reason: null}]}] + + case "content_block_start": + bufferedStart = event // 缓冲，不立即输出 + if event.content_block.type == "tool_use": + idx = nextToolCallIndex++ + toolCallIndexMap[event.content_block.id] = idx + return [] + + case "content_block_delta": + chunks = [] + switch event.delta.type: + "text_delta": + delta = {content: event.delta.text} + if bufferedStart: + // 首次 delta，合并 start 信息（OpenAI 不需要额外的 start 信息） + bufferedStart = null + chunks.append({choices: [{index: 0, delta: delta, finish_reason: null}]}) + + "input_json_delta": + tcIdx = toolCallIndexMap[currentBlockId[event.index]] + delta = {} + if bufferedStart: + // 首次 delta，含 id 和 name + start = bufferedStart.content_block + delta.tool_calls = [{index: tcIdx, id: start.id, + function: {name: start.name, arguments: event.delta.partial_json}, + type: "function"}] + bufferedStart = null + else: + delta.tool_calls = [{index: tcIdx, + function: {arguments: event.delta.partial_json}}] + chunks.append({choices: [{index: 0, delta: delta, finish_reason: null}]}) + + "thinking_delta": + delta = {reasoning_content: event.delta.thinking} + if bufferedStart: + bufferedStart = null + chunks.append({choices: [{index: 0, delta: delta, finish_reason: null}]}) + + return chunks + + case "content_block_stop": + return [] + + case "message_delta": + chunks = [] + if event.delta.stop_reason: + finishReason = mapCanonicalToFinishReason(event.delta.stop_reason) + chunks.append({choices: [{index: 0, delta: {}, finish_reason: finishReason}]}) + if event.usage: + chunks.append({choices: [], usage: encodeUsage(event.usage)}) + return chunks + + case "message_stop": + return ["[DONE]"] +``` + +**缓冲策略**： + +- `ContentBlockStart` 不立即输出，等待首次 `ContentBlockDelta` 合并 +- 合并首次 delta 时，将 start 信息（如 tool id/name）一起编码 + +--- + +## 7. 扩展层接口 + +### 7.1 /models & /models/ + +**列表接口** `GET /v1/models`： + +| 项目 | 说明 | +| ------------ | ----------------- | +| 接口是否存在 | 是 | +| 请求格式 | GET 请求，无 body | + +响应 Decoder（OpenAI → Canonical）： + +``` +decodeModelsResponse(openaiResp): + return CanonicalModelList { + models: openaiResp.data.map(m => CanonicalModel { + id: m.id, name: m.id, created: m.created, owned_by: m.owned_by })} +``` + +响应 Encoder（Canonical → OpenAI）： + +``` +encodeModelsResponse(canonical): + return {object: "list", + data: canonical.models.map(m => ({id: m.id, object: "model", + created: m.created ?? 0, owned_by: m.owned_by ?? "unknown"}))} +``` + +**详情接口** `GET /v1/models/{model}`： + +| 项目 | 说明 | +| ------------ | ----------------- | +| 接口是否存在 | 是 | +| 请求格式 | GET 请求，无 body | + +响应 Decoder（OpenAI → Canonical）： + +``` +decodeModelInfoResponse(openaiResp): + return CanonicalModelInfo { + id: openaiResp.id, name: openaiResp.id, + created: openaiResp.created, owned_by: openaiResp.owned_by } +``` + +响应 Encoder（Canonical → OpenAI）： + +``` +encodeModelInfoResponse(canonical): + return {id: canonical.id, object: "model", + created: canonical.created ?? 0, owned_by: canonical.owned_by ?? "unknown"} +``` + +**字段映射**（列表和详情共用）： + +| OpenAI | Canonical | 说明 | +| -------------------------- | --------------------- | ----------- | +| `data[].id` | `models[].id` | 直接映射 | +| `data[].object: "model"` | — | 固定值 | +| `data[].created` | `models[].created` | Unix 时间戳 | +| `data[].owned_by` | `models[].owned_by` | 直接映射 | + +### 7.2 /embeddings + +| 项目 | 说明 | +| ------------ | ----------------------- | +| 接口是否存在 | 是 | +| URL 路径 | `POST /v1/embeddings` | + +**请求 Decoder**（OpenAI → Canonical）： + +``` +decodeEmbeddingRequest(raw): + return CanonicalEmbeddingRequest { + model: raw.model, + input: raw.input, + encoding_format: raw.encoding_format, + dimensions: raw.dimensions + } +``` + +**请求 Encoder**（Canonical → OpenAI）： + +``` +encodeEmbeddingRequest(canonical, provider): + result = {model: provider.model_name, input: canonical.input} + if canonical.encoding_format: result.encoding_format = canonical.encoding_format + if canonical.dimensions: result.dimensions = canonical.dimensions + return result +``` + +**响应 Decoder**（OpenAI → Canonical）： + +``` +decodeEmbeddingResponse(openaiResp): + return CanonicalEmbeddingResponse { + data: openaiResp.data, model: openaiResp.model, usage: openaiResp.usage } +``` + +**响应 Encoder**（Canonical → OpenAI）： + +``` +encodeEmbeddingResponse(canonical): + return {object: "list", data: canonical.data, model: canonical.model, usage: canonical.usage} +``` + +### 7.3 /rerank + +| 项目 | 说明 | +| ------------ | ------------------- | +| 接口是否存在 | 是 | +| URL 路径 | `POST /v1/rerank` | + +**请求/响应编解码**：按 CanonicalRerankRequest / CanonicalRerankResponse 格式映射。 + +--- + +## 8. 错误编码 + +### 8.1 错误响应格式 + +```json +{ + "error": { + "message": "Error message", + "type": "invalid_request_error", + "param": null, + "code": null + } +} +``` + +### 8.2 encodeError + +``` +OpenAI.encodeError(error): + return { + error: { + message: error.message, + type: mapErrorCode(error.code), + param: error.details?.param ?? null, + code: error.code + } + } + +mapErrorCode(code): + switch code: + INVALID_INPUT → "invalid_request_error" + MISSING_REQUIRED_FIELD → "invalid_request_error" + INCOMPATIBLE_FEATURE → "invalid_request_error" + TOOL_CALL_PARSE_ERROR → "invalid_request_error" + JSON_PARSE_ERROR → "invalid_request_error" + RATE_LIMIT → "rate_limit_error" + AUTHENTICATION → "authentication_error" + default → "server_error" +``` + +### 8.3 常用 HTTP 状态码 + +| HTTP Status | 说明 | +| ----------- | -------------- | +| 400 | 请求格式错误 | +| 401 | 认证失败 | +| 403 | 无权限 | +| 404 | 接口不存在 | +| 429 | 速率限制 | +| 500 | 服务器内部错误 | +| 503 | 服务不可用 | + +--- + +## 9. 自检清单 + +| 章节 | 检查项 | +| ---- | -------------------------------------------------------------------------------------------- | +| §2 | [x] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | +| §2 | [x] 所有 InterfaceType 的 `buildUrl` 映射已确定 | +| §3 | [x]`buildHeaders(provider)` 已实现，adapter_config 契约已文档化 | +| §4 | [x] Chat 请求的 Decoder 和 Encoder 已实现（逐字段对照 §4.1/§4.2） | +| §4 | [x] 系统消息提取包含 `system` 和 `developer` 两种角色 | +| §4 | [x] 角色映射和消息顺序约束已处理（assistant/user 交替合并） | +| §4 | [x] 工具调用（tool_calls / tool_use / tool_result）的编解码已处理（含 custom 类型） | +| §4 | [x]`frequency_penalty` 和 `presence_penalty` 已映射到 Canonical（非忽略） | +| §4 | [x]`max_completion_tokens` 和 `max_tokens` 的优先级已处理 | +| §4 | [x]`reasoning_effort` 到 `thinking` 的映射已处理（含 "none" 和 "minimal"） | +| §4 | [x] 废弃字段（functions / function_call）的兼容处理已实现 | +| §4 | [x] 协议特有字段已识别并确定处理方式（logprobs/n/seed/modalities/web_search_options 等忽略） | +| §5 | [x] Chat 响应的 Decoder 和 Encoder 已实现（逐字段对照 §4.7） | +| §5 | [x] stop_reason / finish_reason 映射表已确认 | +| §5 | [x] usage 字段映射已确认（prompt_tokens ↔ input_tokens） | +| §5 | [x]`reasoning_content`（非标准）的编解码已处理 | +| §5 | [x]`annotations` 等协议特有响应字段已识别并确定处理方式 | +| §6 | [x] 流式 StreamDecoder 和 StreamEncoder 已实现（对照 §4.8） | +| §6 | [x] 流式 `reasoning_content`（非标准）的处理已覆盖 | +| §6 | [x] usage chunk（choices 为空）的处理已覆盖 | +| §7 | [x] 扩展层接口的编解码已实现（/models、/models/{model}、/embeddings、/rerank） | +| §8 | [x]`encodeError` 已实现 |