@anthropic-ai/sdk/resources/messages/messages.d.ts

The official TypeScript library for the Anthropic API

import { APIPromise } from "../../core/api-promise.js";
import { APIResource } from "../../core/resource.js";
import { Stream } from "../../core/streaming.js";
import { RequestOptions } from "../../internal/request-options.js";
import { MessageStream } from "../../lib/MessageStream.js";
import { type ExtractParsedContentFromParams, type ParseableMessageCreateParams, type ParsedMessage } from "../../lib/parser.js";
import * as BatchesAPI from "./batches.js";
import { BatchCreateParams, BatchListParams, Batches, DeletedMessageBatch, MessageBatch, MessageBatchCanceledResult, MessageBatchErroredResult, MessageBatchExpiredResult, MessageBatchIndividualResponse, MessageBatchRequestCounts, MessageBatchResult, MessageBatchSucceededResult, MessageBatchesPage } from "./batches.js";
import * as MessagesAPI from "./messages.js";
export declare class Messages extends APIResource {
    batches: BatchesAPI.Batches;
    /**
     * 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)
     *
     * @example
     * ```ts
     * const message = await client.messages.create({
     *   max_tokens: 1024,
     *   messages: [{ content: 'Hello, world', role: 'user' }],
     *   model: 'claude-opus-4-6',
     * });
     * ```
     */
    create(body: MessageCreateParamsNonStreaming, options?: RequestOptions): APIPromise<Message>;
    create(body: MessageCreateParamsStreaming, options?: RequestOptions): APIPromise<Stream<RawMessageStreamEvent>>;
    create(body: MessageCreateParamsBase, options?: RequestOptions): APIPromise<Stream<RawMessageStreamEvent> | Message>;
    /**
     * Send a structured list of input messages with text and/or image content, along with an expected `output_config.format` and
     * the response will be automatically parsed and available in the `parsed_output` property of the message.
     *
     * @example
     * ```ts
     * const message = await client.messages.parse({
     *   model: 'claude-sonnet-4-5-20250929',
     *   max_tokens: 1024,
     *   messages: [{ role: 'user', content: 'What is 2+2?' }],
     *   output_config: {
     *     format: zodOutputFormat(z.object({ answer: z.number() })),
     *   },
     * });
     *
     * console.log(message.parsed_output?.answer); // 4
     * ```
     */
    parse<Params extends MessageCreateParamsNonStreaming>(params: Params, options?: RequestOptions): APIPromise<ParsedMessage<ExtractParsedContentFromParams<Params>>>;
    /**
     * Create a Message stream.
     *
     * If `output_config.format` is provided with a parseable format (like `zodOutputFormat()`),
     * the final message will include a `parsed_output` property with the parsed content.
     *
     * @example
     * ```ts
     * const stream = client.messages.stream({
     *   model: 'claude-sonnet-4-5-20250929',
     *   max_tokens: 1024,
     *   messages: [{ role: 'user', content: 'What is 2+2?' }],
     *   output_config: {
     *     format: zodOutputFormat(z.object({ answer: z.number() })),
     *   },
     * });
     *
     * const message = await stream.finalMessage();
     * console.log(message.parsed_output?.answer); // 4
     * ```
     */
    stream<Params extends MessageStreamParams>(body: Params, options?: RequestOptions): MessageStream<ExtractParsedContentFromParams<Params>>;
    /**
     * 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)
     *
     * @example
     * ```ts
     * const messageTokensCount =
     *   await client.messages.countTokens({
     *     messages: [{ content: 'string', role: 'user' }],
     *     model: 'claude-opus-4-6',
     *   });
     * ```
     */
    countTokens(body: MessageCountTokensParams, options?: RequestOptions): APIPromise<MessageTokensCount>;
}
export interface Base64ImageSource {
    data: string;
    media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
    type: 'base64';
}
export interface Base64PDFSource {
    data: string;
    media_type: 'application/pdf';
    type: 'base64';
}
export interface BashCodeExecutionOutputBlock {
    file_id: string;
    type: 'bash_code_execution_output';
}
export interface BashCodeExecutionOutputBlockParam {
    file_id: string;
    type: 'bash_code_execution_output';
}
export interface BashCodeExecutionResultBlock {
    content: Array<BashCodeExecutionOutputBlock>;
    return_code: number;
    stderr: string;
    stdout: string;
    type: 'bash_code_execution_result';
}
export interface BashCodeExecutionResultBlockParam {
    content: Array<BashCodeExecutionOutputBlockParam>;
    return_code: number;
    stderr: string;
    stdout: string;
    type: 'bash_code_execution_result';
}
export interface BashCodeExecutionToolResultBlock {
    content: BashCodeExecutionToolResultError | BashCodeExecutionResultBlock;
    tool_use_id: string;
    type: 'bash_code_execution_tool_result';
}
export interface BashCodeExecutionToolResultBlockParam {
    content: BashCodeExecutionToolResultErrorParam | BashCodeExecutionResultBlockParam;
    tool_use_id: string;
    type: 'bash_code_execution_tool_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
export interface BashCodeExecutionToolResultError {
    error_code: BashCodeExecutionToolResultErrorCode;
    type: 'bash_code_execution_tool_result_error';
}
export type BashCodeExecutionToolResultErrorCode = 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded' | 'output_file_too_large';
export interface BashCodeExecutionToolResultErrorParam {
    error_code: BashCodeExecutionToolResultErrorCode;
    type: 'bash_code_execution_tool_result_error';
}
export interface CacheControlEphemeral {
    type: 'ephemeral';
    /**
     * 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`.
     */
    ttl?: '5m' | '1h';
}
export interface CacheCreation {
    /**
     * The number of input tokens used to create the 1 hour cache entry.
     */
    ephemeral_1h_input_tokens: number;
    /**
     * The number of input tokens used to create the 5 minute cache entry.
     */
    ephemeral_5m_input_tokens: number;
}
export interface CitationCharLocation {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_char_index: number;
    file_id: string | null;
    start_char_index: number;
    type: 'char_location';
}
export interface CitationCharLocationParam {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_char_index: number;
    start_char_index: number;
    type: 'char_location';
}
export interface CitationContentBlockLocation {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_block_index: number;
    file_id: string | null;
    start_block_index: number;
    type: 'content_block_location';
}
export interface CitationContentBlockLocationParam {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_block_index: number;
    start_block_index: number;
    type: 'content_block_location';
}
export interface CitationPageLocation {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_page_number: number;
    file_id: string | null;
    start_page_number: number;
    type: 'page_location';
}
export interface CitationPageLocationParam {
    cited_text: string;
    document_index: number;
    document_title: string | null;
    end_page_number: number;
    start_page_number: number;
    type: 'page_location';
}
export interface CitationSearchResultLocationParam {
    cited_text: string;
    end_block_index: number;
    search_result_index: number;
    source: string;
    start_block_index: number;
    title: string | null;
    type: 'search_result_location';
}
export interface CitationWebSearchResultLocationParam {
    cited_text: string;
    encrypted_index: string;
    title: string | null;
    type: 'web_search_result_location';
    url: string;
}
export interface CitationsConfig {
    enabled: boolean;
}
export interface CitationsConfigParam {
    enabled?: boolean;
}
export interface CitationsDelta {
    citation: CitationCharLocation | CitationPageLocation | CitationContentBlockLocation | CitationsWebSearchResultLocation | CitationsSearchResultLocation;
    type: 'citations_delta';
}
export interface CitationsSearchResultLocation {
    cited_text: string;
    end_block_index: number;
    search_result_index: number;
    source: string;
    start_block_index: number;
    title: string | null;
    type: 'search_result_location';
}
export interface CitationsWebSearchResultLocation {
    cited_text: string;
    encrypted_index: string;
    title: string | null;
    type: 'web_search_result_location';
    url: string;
}
export interface CodeExecutionOutputBlock {
    file_id: string;
    type: 'code_execution_output';
}
export interface CodeExecutionOutputBlockParam {
    file_id: string;
    type: 'code_execution_output';
}
export interface CodeExecutionResultBlock {
    content: Array<CodeExecutionOutputBlock>;
    return_code: number;
    stderr: string;
    stdout: string;
    type: 'code_execution_result';
}
export interface CodeExecutionResultBlockParam {
    content: Array<CodeExecutionOutputBlockParam>;
    return_code: number;
    stderr: string;
    stdout: string;
    type: 'code_execution_result';
}
export interface CodeExecutionTool20250522 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'code_execution';
    type: 'code_execution_20250522';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface CodeExecutionTool20250825 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'code_execution';
    type: 'code_execution_20250825';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
/**
 * Code execution tool with REPL state persistence (daemon mode + gVisor
 * checkpoint).
 */
export interface CodeExecutionTool20260120 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'code_execution';
    type: 'code_execution_20260120';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface CodeExecutionToolResultBlock {
    /**
     * Code execution result with encrypted stdout for PFC + web_search results.
     */
    content: CodeExecutionToolResultBlockContent;
    tool_use_id: string;
    type: 'code_execution_tool_result';
}
/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export type CodeExecutionToolResultBlockContent = CodeExecutionToolResultError | CodeExecutionResultBlock | EncryptedCodeExecutionResultBlock;
export interface CodeExecutionToolResultBlockParam {
    /**
     * Code execution result with encrypted stdout for PFC + web_search results.
     */
    content: CodeExecutionToolResultBlockParamContent;
    tool_use_id: string;
    type: 'code_execution_tool_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export type CodeExecutionToolResultBlockParamContent = CodeExecutionToolResultErrorParam | CodeExecutionResultBlockParam | EncryptedCodeExecutionResultBlockParam;
export interface CodeExecutionToolResultError {
    error_code: CodeExecutionToolResultErrorCode;
    type: 'code_execution_tool_result_error';
}
export type CodeExecutionToolResultErrorCode = 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded';
export interface CodeExecutionToolResultErrorParam {
    error_code: CodeExecutionToolResultErrorCode;
    type: 'code_execution_tool_result_error';
}
/**
 * Information about the container used in the request (for the code execution
 * tool)
 */
export interface Container {
    /**
     * Identifier for the container used in this request
     */
    id: string;
    /**
     * The time at which the container will expire.
     */
    expires_at: string;
}
/**
 * Response model for a file uploaded to the container.
 */
export interface ContainerUploadBlock {
    file_id: string;
    type: 'container_upload';
}
/**
 * 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.
 */
export interface ContainerUploadBlockParam {
    file_id: string;
    type: 'container_upload';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
/**
 * Response model for a file uploaded to the container.
 */
export type ContentBlock = TextBlock | ThinkingBlock | RedactedThinkingBlock | ToolUseBlock | ServerToolUseBlock | WebSearchToolResultBlock | WebFetchToolResultBlock | CodeExecutionToolResultBlock | BashCodeExecutionToolResultBlock | TextEditorCodeExecutionToolResultBlock | ToolSearchToolResultBlock | ContainerUploadBlock;
/**
 * Regular text content.
 */
export type ContentBlockParam = TextBlockParam | ImageBlockParam | DocumentBlockParam | SearchResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | WebFetchToolResultBlockParam | CodeExecutionToolResultBlockParam | BashCodeExecutionToolResultBlockParam | TextEditorCodeExecutionToolResultBlockParam | ToolSearchToolResultBlockParam | ContainerUploadBlockParam;
export interface ContentBlockSource {
    content: string | Array<ContentBlockSourceContent>;
    type: 'content';
}
export type ContentBlockSourceContent = TextBlockParam | ImageBlockParam;
/**
 * Tool invocation directly from the model.
 */
export interface DirectCaller {
    type: 'direct';
}
export interface DocumentBlock {
    /**
     * Citation configuration for the document
     */
    citations: CitationsConfig | null;
    source: Base64PDFSource | PlainTextSource;
    /**
     * The title of the document
     */
    title: string | null;
    type: 'document';
}
export interface DocumentBlockParam {
    source: Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource;
    type: 'document';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    citations?: CitationsConfigParam | null;
    context?: string | null;
    title?: string | null;
}
/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export interface EncryptedCodeExecutionResultBlock {
    content: Array<CodeExecutionOutputBlock>;
    encrypted_stdout: string;
    return_code: number;
    stderr: string;
    type: 'encrypted_code_execution_result';
}
/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export interface EncryptedCodeExecutionResultBlockParam {
    content: Array<CodeExecutionOutputBlockParam>;
    encrypted_stdout: string;
    return_code: number;
    stderr: string;
    type: 'encrypted_code_execution_result';
}
export interface ImageBlockParam {
    source: Base64ImageSource | URLImageSource;
    type: 'image';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
export interface InputJSONDelta {
    partial_json: string;
    type: 'input_json_delta';
}
export interface JSONOutputFormat {
    /**
     * The JSON schema of the format
     */
    schema: {
        [key: string]: unknown;
    };
    type: 'json_schema';
}
export interface MemoryTool20250818 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'memory';
    type: 'memory_20250818';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface Message {
    /**
     * Unique object identifier.
     *
     * The format and length of IDs may change over time.
     */
    id: string;
    /**
     * Information about the container used in the request (for the code execution
     * tool)
     */
    container: Container | null;
    /**
     * 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)" }]
     * ```
     */
    content: Array<ContentBlock>;
    /**
     * The model that will complete your prompt.\n\nSee
     * [models](https://docs.anthropic.com/en/docs/models-overview) for additional
     * details and options.
     */
    model: Model;
    /**
     * Conversational role of the generated message.
     *
     * This will always be `"assistant"`.
     */
    role: 'assistant';
    /**
     * 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.
     */
    stop_reason: StopReason | null;
    /**
     * 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.
     */
    stop_sequence: string | null;
    /**
     * Object type.
     *
     * For Messages, this is always `"message"`.
     */
    type: 'message';
    /**
     * 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`.
     */
    usage: Usage;
}
/**
 * Code execution tool with REPL state persistence (daemon mode + gVisor
 * checkpoint).
 */
export type MessageCountTokensTool = Tool | ToolBash20250124 | CodeExecutionTool20250522 | CodeExecutionTool20250825 | CodeExecutionTool20260120 | MemoryTool20250818 | ToolTextEditor20250124 | ToolTextEditor20250429 | ToolTextEditor20250728 | WebSearchTool20250305 | WebFetchTool20250910 | WebSearchTool20260209 | WebFetchTool20260209 | WebFetchTool20260309 | ToolSearchToolBm25_20251119 | ToolSearchToolRegex20251119;
export interface MessageDeltaUsage {
    /**
     * The cumulative number of input tokens used to create the cache entry.
     */
    cache_creation_input_tokens: number | null;
    /**
     * The cumulative number of input tokens read from the cache.
     */
    cache_read_input_tokens: number | null;
    /**
     * The cumulative number of input tokens which were used.
     */
    input_tokens: number | null;
    /**
     * The cumulative number of output tokens which were used.
     */
    output_tokens: number;
    /**
     * The number of server tool requests.
     */
    server_tool_use: ServerToolUsage | null;
}
export interface MessageParam {
    content: string | Array<ContentBlockParam>;
    role: 'user' | 'assistant';
}
export interface MessageTokensCount {
    /**
     * The total number of tokens across the provided list of messages, system prompt,
     * and tools.
     */
    input_tokens: number;
}
export interface Metadata {
    /**
     * 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.
     */
    user_id?: string | null;
}
/**
 * The model that will complete your prompt.\n\nSee
 * [models](https://docs.anthropic.com/en/docs/models-overview) for additional
 * details and options.
 */
export type Model = 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-haiku-4-5' | 'claude-haiku-4-5-20251001' | 'claude-opus-4-5' | 'claude-opus-4-5-20251101' | 'claude-sonnet-4-5' | 'claude-sonnet-4-5-20250929' | 'claude-opus-4-1' | 'claude-opus-4-1-20250805' | 'claude-opus-4-0' | 'claude-opus-4-20250514' | 'claude-sonnet-4-0' | 'claude-sonnet-4-20250514' | 'claude-3-haiku-20240307' | (string & {});
export interface OutputConfig {
    /**
     * All possible effort levels.
     */
    effort?: 'low' | 'medium' | 'high' | 'max' | null;
    /**
     * A schema to specify Claude's output format in responses. See
     * [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
     */
    format?: JSONOutputFormat | null;
}
export interface PlainTextSource {
    data: string;
    media_type: 'text/plain';
    type: 'text';
}
export type RawContentBlockDelta = TextDelta | InputJSONDelta | CitationsDelta | ThinkingDelta | SignatureDelta;
export interface RawContentBlockDeltaEvent {
    delta: RawContentBlockDelta;
    index: number;
    type: 'content_block_delta';
}
export interface RawContentBlockStartEvent {
    /**
     * Response model for a file uploaded to the container.
     */
    content_block: TextBlock | ThinkingBlock | RedactedThinkingBlock | ToolUseBlock | ServerToolUseBlock | WebSearchToolResultBlock | WebFetchToolResultBlock | CodeExecutionToolResultBlock | BashCodeExecutionToolResultBlock | TextEditorCodeExecutionToolResultBlock | ToolSearchToolResultBlock | ContainerUploadBlock;
    index: number;
    type: 'content_block_start';
}
export interface RawContentBlockStopEvent {
    index: number;
    type: 'content_block_stop';
}
export interface RawMessageDeltaEvent {
    delta: RawMessageDeltaEvent.Delta;
    type: 'message_delta';
    /**
     * 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`.
     */
    usage: MessageDeltaUsage;
}
export declare namespace RawMessageDeltaEvent {
    interface Delta {
        /**
         * Information about the container used in the request (for the code execution
         * tool)
         */
        container: MessagesAPI.Container | null;
        stop_reason: MessagesAPI.StopReason | null;
        stop_sequence: string | null;
    }
}
export interface RawMessageStartEvent {
    message: Message;
    type: 'message_start';
}
export interface RawMessageStopEvent {
    type: 'message_stop';
}
export type RawMessageStreamEvent = RawMessageStartEvent | RawMessageDeltaEvent | RawMessageStopEvent | RawContentBlockStartEvent | RawContentBlockDeltaEvent | RawContentBlockStopEvent;
export interface RedactedThinkingBlock {
    data: string;
    type: 'redacted_thinking';
}
export interface RedactedThinkingBlockParam {
    data: string;
    type: 'redacted_thinking';
}
export interface SearchResultBlockParam {
    content: Array<TextBlockParam>;
    source: string;
    title: string;
    type: 'search_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    citations?: CitationsConfigParam;
}
/**
 * Tool invocation generated by a server-side tool.
 */
export interface ServerToolCaller {
    tool_id: string;
    type: 'code_execution_20250825';
}
export interface ServerToolCaller20260120 {
    tool_id: string;
    type: 'code_execution_20260120';
}
export interface ServerToolUsage {
    /**
     * The number of web fetch tool requests.
     */
    web_fetch_requests: number;
    /**
     * The number of web search tool requests.
     */
    web_search_requests: number;
}
export interface ServerToolUseBlock {
    id: string;
    /**
     * Tool invocation directly from the model.
     */
    caller: DirectCaller | ServerToolCaller | ServerToolCaller20260120;
    input: unknown;
    name: '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';
}
export interface ServerToolUseBlockParam {
    id: string;
    input: unknown;
    name: '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';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * Tool invocation directly from the model.
     */
    caller?: DirectCaller | ServerToolCaller | ServerToolCaller20260120;
}
export interface SignatureDelta {
    signature: string;
    type: 'signature_delta';
}
export type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal';
export interface TextBlock {
    /**
     * 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`.
     */
    citations: Array<TextCitation> | null;
    text: string;
    type: 'text';
}
export interface TextBlockParam {
    text: string;
    type: 'text';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    citations?: Array<TextCitationParam> | null;
}
export type TextCitation = CitationCharLocation | CitationPageLocation | CitationContentBlockLocation | CitationsWebSearchResultLocation | CitationsSearchResultLocation;
export type TextCitationParam = CitationCharLocationParam | CitationPageLocationParam | CitationContentBlockLocationParam | CitationWebSearchResultLocationParam | CitationSearchResultLocationParam;
export interface TextDelta {
    text: string;
    type: 'text_delta';
}
export interface TextEditorCodeExecutionCreateResultBlock {
    is_file_update: boolean;
    type: 'text_editor_code_execution_create_result';
}
export interface TextEditorCodeExecutionCreateResultBlockParam {
    is_file_update: boolean;
    type: 'text_editor_code_execution_create_result';
}
export interface TextEditorCodeExecutionStrReplaceResultBlock {
    lines: Array<string> | null;
    new_lines: number | null;
    new_start: number | null;
    old_lines: number | null;
    old_start: number | null;
    type: 'text_editor_code_execution_str_replace_result';
}
export interface TextEditorCodeExecutionStrReplaceResultBlockParam {
    type: 'text_editor_code_execution_str_replace_result';
    lines?: Array<string> | null;
    new_lines?: number | null;
    new_start?: number | null;
    old_lines?: number | null;
    old_start?: number | null;
}
export interface TextEditorCodeExecutionToolResultBlock {
    content: TextEditorCodeExecutionToolResultError | TextEditorCodeExecutionViewResultBlock | TextEditorCodeExecutionCreateResultBlock | TextEditorCodeExecutionStrReplaceResultBlock;
    tool_use_id: string;
    type: 'text_editor_code_execution_tool_result';
}
export interface TextEditorCodeExecutionToolResultBlockParam {
    content: TextEditorCodeExecutionToolResultErrorParam | TextEditorCodeExecutionViewResultBlockParam | TextEditorCodeExecutionCreateResultBlockParam | TextEditorCodeExecutionStrReplaceResultBlockParam;
    tool_use_id: string;
    type: 'text_editor_code_execution_tool_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
export interface TextEditorCodeExecutionToolResultError {
    error_code: TextEditorCodeExecutionToolResultErrorCode;
    error_message: string | null;
    type: 'text_editor_code_execution_tool_result_error';
}
export type TextEditorCodeExecutionToolResultErrorCode = 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded' | 'file_not_found';
export interface TextEditorCodeExecutionToolResultErrorParam {
    error_code: TextEditorCodeExecutionToolResultErrorCode;
    type: 'text_editor_code_execution_tool_result_error';
    error_message?: string | null;
}
export interface TextEditorCodeExecutionViewResultBlock {
    content: string;
    file_type: 'text' | 'image' | 'pdf';
    num_lines: number | null;
    start_line: number | null;
    total_lines: number | null;
    type: 'text_editor_code_execution_view_result';
}
export interface TextEditorCodeExecutionViewResultBlockParam {
    content: string;
    file_type: 'text' | 'image' | 'pdf';
    type: 'text_editor_code_execution_view_result';
    num_lines?: number | null;
    start_line?: number | null;
    total_lines?: number | null;
}
export interface ThinkingBlock {
    signature: string;
    thinking: string;
    type: 'thinking';
}
export interface ThinkingBlockParam {
    signature: string;
    thinking: string;
    type: 'thinking';
}
export interface ThinkingConfigAdaptive {
    type: 'adaptive';
    /**
     * 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`.
     */
    display?: 'summarized' | 'omitted' | null;
}
export interface ThinkingConfigDisabled {
    type: 'disabled';
}
export interface ThinkingConfigEnabled {
    /**
     * 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.
     */
    budget_tokens: number;
    type: 'enabled';
    /**
     * 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`.
     */
    display?: 'summarized' | 'omitted' | null;
}
/**
 * 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.
 */
export type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled | ThinkingConfigAdaptive;
export interface ThinkingDelta {
    thinking: string;
    type: 'thinking_delta';
}
export interface Tool {
    /**
     * [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.
     */
    input_schema: Tool.InputSchema;
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: string;
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * 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.
     */
    description?: string;
    /**
     * 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.
     */
    eager_input_streaming?: boolean | null;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
    type?: 'custom' | null;
}
export declare namespace Tool {
    /**
     * [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.
     */
    interface InputSchema {
        type: 'object';
        properties?: unknown | null;
        required?: Array<string> | null;
        [k: string]: unknown;
    }
}
export interface ToolBash20250124 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'bash';
    type: 'bash_20250124';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
/**
 * 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.
 */
export type ToolChoice = ToolChoiceAuto | ToolChoiceAny | ToolChoiceTool | ToolChoiceNone;
/**
 * The model will use any available tools.
 */
export interface ToolChoiceAny {
    type: 'any';
    /**
     * Whether to disable parallel tool use.
     *
     * Defaults to `false`. If set to `true`, the model will output exactly one tool
     * use.
     */
    disable_parallel_tool_use?: boolean;
}
/**
 * The model will automatically decide whether to use tools.
 */
export interface ToolChoiceAuto {
    type: 'auto';
    /**
     * Whether to disable parallel tool use.
     *
     * Defaults to `false`. If set to `true`, the model will output at most one tool
     * use.
     */
    disable_parallel_tool_use?: boolean;
}
/**
 * The model will not be allowed to use tools.
 */
export interface ToolChoiceNone {
    type: 'none';
}
/**
 * The model will use the specified tool with `tool_choice.name`.
 */
export interface ToolChoiceTool {
    /**
     * The name of the tool to use.
     */
    name: string;
    type: 'tool';
    /**
     * Whether to disable parallel tool use.
     *
     * Defaults to `false`. If set to `true`, the model will output exactly one tool
     * use.
     */
    disable_parallel_tool_use?: boolean;
}
export interface ToolReferenceBlock {
    tool_name: string;
    type: 'tool_reference';
}
/**
 * Tool reference block that can be included in tool_result content.
 */
export interface ToolReferenceBlockParam {
    tool_name: string;
    type: 'tool_reference';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
export interface ToolResultBlockParam {
    tool_use_id: string;
    type: 'tool_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    content?: string | Array<TextBlockParam | ImageBlockParam | SearchResultBlockParam | DocumentBlockParam | ToolReferenceBlockParam>;
    is_error?: boolean;
}
export interface ToolSearchToolBm25_20251119 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'tool_search_tool_bm25';
    type: 'tool_search_tool_bm25_20251119' | 'tool_search_tool_bm25';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface ToolSearchToolRegex20251119 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'tool_search_tool_regex';
    type: 'tool_search_tool_regex_20251119' | 'tool_search_tool_regex';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface ToolSearchToolResultBlock {
    content: ToolSearchToolResultError | ToolSearchToolSearchResultBlock;
    tool_use_id: string;
    type: 'tool_search_tool_result';
}
export interface ToolSearchToolResultBlockParam {
    content: ToolSearchToolResultErrorParam | ToolSearchToolSearchResultBlockParam;
    tool_use_id: string;
    type: 'tool_search_tool_result';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
}
export interface ToolSearchToolResultError {
    error_code: ToolSearchToolResultErrorCode;
    error_message: string | null;
    type: 'tool_search_tool_result_error';
}
export type ToolSearchToolResultErrorCode = 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded';
export interface ToolSearchToolResultErrorParam {
    error_code: ToolSearchToolResultErrorCode;
    type: 'tool_search_tool_result_error';
}
export interface ToolSearchToolSearchResultBlock {
    tool_references: Array<ToolReferenceBlock>;
    type: 'tool_search_tool_search_result';
}
export interface ToolSearchToolSearchResultBlockParam {
    tool_references: Array<ToolReferenceBlockParam>;
    type: 'tool_search_tool_search_result';
}
export interface ToolTextEditor20250124 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'str_replace_editor';
    type: 'text_editor_20250124';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface ToolTextEditor20250429 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'str_replace_based_edit_tool';
    type: 'text_editor_20250429';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
export interface ToolTextEditor20250728 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'str_replace_based_edit_tool';
    type: 'text_editor_20250728';
    allowed_callers?: Array<'direct' | 'code_execution_20250825' | 'code_execution_20260120'>;
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * If true, tool will not be included in initial system prompt. Only loaded when
     * returned via tool_reference from tool search.
     */
    defer_loading?: boolean;
    input_examples?: Array<{
        [key: string]: unknown;
    }>;
    /**
     * Maximum number of characters to display when viewing a file. If not specified,
     * defaults to displaying the full file.
     */
    max_characters?: number | null;
    /**
     * When true, guarantees schema validation on tool names and inputs
     */
    strict?: boolean;
}
/**
 * Code execution tool with REPL state persistence (daemon mode + gVisor
 * checkpoint).
 */
export type ToolUnion = Tool | ToolBash20250124 | CodeExecutionTool20250522 | CodeExecutionTool20250825 | CodeExecutionTool20260120 | MemoryTool20250818 | ToolTextEditor20250124 | ToolTextEditor20250429 | ToolTextEditor20250728 | WebSearchTool20250305 | WebFetchTool20250910 | WebSearchTool20260209 | WebFetchTool20260209 | WebFetchTool20260309 | ToolSearchToolBm25_20251119 | ToolSearchToolRegex20251119;
export interface ToolUseBlock {
    id: string;
    /**
     * Tool invocation directly from the model.
     */
    caller: DirectCaller | ServerToolCaller | ServerToolCaller20260120;
    input: unknown;
    name: string;
    type: 'tool_use';
}
export interface ToolUseBlockParam {
    id: string;
    input: unknown;
    name: string;
    type: 'tool_use';
    /**
     * Create a cache control breakpoint at this content block.
     */
    cache_control?: CacheControlEphemeral | null;
    /**
     * Tool invocation directly from the model.
     */
    caller?: DirectCaller | ServerToolCaller | ServerToolCaller20260120;
}
export interface URLImageSource {
    type: 'url';
    url: string;
}
export interface URLPDFSource {
    type: 'url';
    url: string;
}
export interface Usage {
    /**
     * Breakdown of cached tokens by TTL
     */
    cache_creation: CacheCreation | null;
    /**
     * The number of input tokens used to create the cache entry.
     */
    cache_creation_input_tokens: number | null;
    /**
     * The number of input tokens read from the cache.
     */
    cache_read_input_tokens: number | null;
    /**
     * The geographic region where inference was performed for this request.
     */
    inference_geo: string | null;
    /**
     * The number of input tokens which were used.
     */
    input_tokens: number;
    /**
     * The number of output tokens which were used.
     */
    output_tokens: number;
    /**
     * The number of server tool requests.
     */
    server_tool_use: ServerToolUsage | null;
    /**
     * If the request used the priority, standard, or batch tier.
     */
    service_tier: 'standard' | 'priority' | 'batch' | null;
}
export interface UserLocation {
    type: 'approximate';
    /**
     * The city of the user.
     */
    city?: string | null;
    /**
     * The two letter
     * [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the
     * user.
     */
    country?: string | null;
    /**
     * The region of the user.
     */
    region?: string | null;
    /**
     * The [IANA timezone](https://nodatime.org/TimeZones) of the user.
     */
    timezone?: string | null;
}
export interface WebFetchBlock {
    content: DocumentBlock;
    /**
     * ISO 8601 timestamp when the content was retrieved
     */
    retrieved_at: string | null;
    type: 'web_fetch_result';
    /**
     * Fetched content URL
     */
    url: string;
}
export interface WebFetchBlockParam {
    content: DocumentBlockParam;
    type: 'web_fetch_result';
    /**
     * Fetched content URL
     */
    url: string;
    /**
     * ISO 8601 timestamp when the content was retrieved
     */
    retrieved_at?: string | null;
}
export interface WebFetchTool20250910 {
    /**
     * Name of the tool.
     *
     * This is how the tool will be called by the model and in `tool_use` blocks.
     */
    name: 'web_fetch';
    type: 'web_fetch_2025