--- title: "Create a message." method: POST path: "/v1/messages" tags: ["Messages"] --- # Create a message. `POST /v1/messages` Create a message using the Anthropic Messages API format. ## Request body - AnthropicCreateMessageRequest — Request body for POST /v1/messages. - `model` string, required — The model to use for generation. - `messages` AnthropicMessage[], required — The messages in the conversation. - `role` 'user' | 'assistant' | 'system', required - `content` union, required — Message content: a string for simple text, or a list of content blocks. - string - union[] - union - AnthropicTextBlock — A text content block. - `type` 'text' - `text` string, required - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - … - AnthropicImageBlock — An image content block. - `type` 'image' - `source` union, required - … - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - … - AnthropicToolUseBlock — A tool use content block in an assistant message. - `type` 'tool_use' - `id` string, required — Unique ID for this tool invocation. - `name` string, required — Name of the tool being called. - `input` object, required — Tool input arguments. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - … - AnthropicToolResultBlockInput — A tool result content block in a user message. - `type` 'tool_result' - `tool_use_id` string, required — The ID of the tool_use block this result corresponds to. - `content` union — The result content. - … - `is_error` boolean, nullable — Whether the tool call resulted in an error. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - … - AnthropicThinkingBlock — A thinking content block (extended thinking). - `type` 'thinking' - `thinking` string, required — The model's thinking text. - `signature` string, nullable — Signature for the thinking block. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - … - AnthropicRedactedThinkingBlock — A redacted thinking content block. Must be echoed back as-is in multi-turn. - `type` 'redacted_thinking' - `data` string, required — Opaque redacted thinking data. - `max_tokens` integer, required — The maximum number of tokens to generate. - `system` union — System prompt. A string or list of text blocks. - string - AnthropicTextBlock[] - `type` 'text' - `text` string, required - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - `tools` union[] — Tools available to the model. - union - AnthropicCustomToolDef — Definition of a custom (function-calling) tool. - `type` 'custom' - `name` string, required - `description` string, nullable - `input_schema` object, required — JSON Schema for the tool's input. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicWebSearchTool — Built-in web search tool (web_search_20250305). - `type` 'web_search_20250305' - `name` 'web_search' - `max_uses` integer, nullable - `allowed_domains` string[], nullable - `blocked_domains` string[], nullable - `user_location` WebSearchUserLocation - `type` 'approximate' - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicBashTool — Built-in bash tool (bash_20250124). - `type` 'bash_20250124' - `name` 'bash' - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicTextEditorTool — Built-in text editor tool (all versions). - `type` 'text_editor_20250124' | 'text_editor_20250429' | 'text_editor_20250728', required - `name` string, required - `max_characters` integer, nullable - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - `tool_choice` union — How the model should select tools. One of: 'auto', 'any', 'none', or {type: 'tool', name: '...'}. - ToolChoiceAuto - `type` 'auto' - `disable_parallel_tool_use` boolean, nullable - ToolChoiceAny - `type` 'any' - `disable_parallel_tool_use` boolean, nullable - ToolChoiceNone - `type` 'none' - ToolChoiceTool - `type` 'tool' - `name` string, required - `disable_parallel_tool_use` boolean, nullable - `stream` boolean — Whether to stream the response. - `temperature` number — Sampling temperature. - `top_p` number — Nucleus sampling parameter. - `top_k` integer — Top-k sampling parameter. - `stop_sequences` string[] — Custom stop sequences. - `metadata` object — Request metadata. - `thinking` AnthropicThinkingConfig — Configuration for extended thinking. - `type` 'enabled' | 'disabled' | 'adaptive' - `budget_tokens` integer, nullable — Maximum tokens for thinking. - `service_tier` string — Service tier to use. ## Response `200` An AnthropicMessageResponse or a stream of Anthropic SSE events. - AnthropicMessageResponse — Response from POST /v1/messages (non-streaming). - `id` string, required — Unique message ID (msg_ prefix). - `type` 'message' - `role` 'assistant' - `content` union[], required — Response content blocks. - union - AnthropicTextBlock — A text content block. - `type` 'text' - `text` string, required - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicImageBlock — An image content block. - `type` 'image' - `source` union, required - AnthropicBase64ImageSource — Base64-encoded image source. - `type` 'base64' - `media_type` 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp', required — MIME type of the image. - `data` string, required — Base64-encoded image data. - AnthropicURLImageSource — URL image source. - `type` 'url' - `url` string, required — URL of the image. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicToolUseBlock — A tool use content block in an assistant message. - `type` 'tool_use' - `id` string, required — Unique ID for this tool invocation. - `name` string, required — Name of the tool being called. - `input` object, required — Tool input arguments. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicToolResultBlockOutput — A tool result content block in a user message. - `type` 'tool_result' - `tool_use_id` string, required — The ID of the tool_use block this result corresponds to. - `content` union — The result content. - string - union[] - union - … - `is_error` boolean, nullable — Whether the tool call resulted in an error. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicThinkingBlock — A thinking content block (extended thinking). - `type` 'thinking' - `thinking` string, required — The model's thinking text. - `signature` string, nullable — Signature for the thinking block. - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker. - `type` 'ephemeral' - AnthropicRedactedThinkingBlock — A redacted thinking content block. Must be echoed back as-is in multi-turn. - `type` 'redacted_thinking' - `data` string, required — Opaque redacted thinking data. - `model` string, required - `stop_reason` string, nullable — Why the model stopped: end_turn, stop_sequence, tool_use, or max_tokens. - `stop_sequence` string, nullable - `usage` AnthropicUsage — Token usage statistics. - `input_tokens` integer - `output_tokens` integer - `cache_creation_input_tokens` integer, nullable - `cache_read_input_tokens` integer, nullable ## Other responses - `400` — The request was invalid or malformed - `429` — The client has sent too many requests in a given amount of time - `500` — The server encountered an unexpected error - `default` — An error occurred --- [API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/revisions/f3f783962256/schema)