--- title: "Create a message" method: POST path: "/messages" tags: ["Messages"] --- # Create a message `POST /messages` Creates a message using the Anthropic-compatible Messages API. The request follows the Anthropic Messages API format with `model`, `max_tokens`, `messages`, optional `system`, `tools`, and streaming support. Not every provider implements the Messages API. Requests routed to a provider that does not support it return `400 Bad Request` with an explanatory error message; use `/chat/completions` for those providers. ## Query parameters - `provider` 'ollama' | 'ollama_cloud' | 'groq' | 'llamacpp' | 'openai' | 'cloudflare' | 'cohere' | 'anthropic' | 'deepseek' | 'google' | 'mistral' | 'minimax' | 'moonshot' | 'nvidia' | 'zai' ## Request body - CreateMessagesRequest — Request body for creating a message via the Anthropic-compatible Messages API. - `model` string, required — The model to use for generating the message. - `max_tokens` integer, required — The maximum number of tokens to generate before stopping. - `system` union — The system prompt. Can be a string or an array of system content blocks (for prompt caching). - string — System prompt as a string. - MessagesTextBlock[] - `type` 'text', required — Content type identifier. Always `text`. - `text` string, required — The text content. - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - `type` 'ephemeral', required — The cache control type. Currently only `ephemeral`. - `messages` MessagesMessage[], required — The messages to generate a response for. Each message has a `role` (user or assistant) and `content`. - `role` 'user' | 'assistant', required — The role of the message sender. - `content` union, required — The content of the message. Can be a string or an array of content blocks. - string — Text content. - MessagesRequestContentBlock[] - union — A content block within a Messages API request message. - object — A text content block in a Messages API request or response. - `type` 'text', required — Content type identifier. Always `text`. - `text` string, required — The text content. - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - … - object — An image content block in a Messages API request. - `type` 'image', required — Content type identifier. Always `image`. - `source` MessagesImageSource, required — The source of an image content block. Can be a base64-encoded image or a URL. - … - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - … - object — A tool use content block in a Messages API request or response. - `type` 'tool_use', required — Content type identifier. Always `tool_use`. - `id` string, required — The unique identifier for this tool use block. - `name` string, required — The name of the tool being called. - `input` object, required — The input parameters for the tool. - object — A tool result content block in a Messages API request. - `type` 'tool_result', required — Content type identifier. Always `tool_result`. - `tool_use_id` string, required — The ID of the tool use this result is for. - `content` union — The result content. Can be a string or an array of content blocks. - … - `is_error` boolean — Whether the tool execution resulted in an error. - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - … - object — A document content block in a Messages API request. - `type` 'document', required — Content type identifier. Always `document`. - `source` MessagesDocumentSource, required — The source of a document content block. Can be a base64-encoded document or a URL. - … - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - … - object — A thinking content block in a Messages API request or response. - `type` 'thinking', required — Content type identifier. Always `thinking`. - `thinking` string, required — The thinking content. - `signature` string, required — The signature for verifying the thinking content. Must be passed back when continuing a conversation with extended thinking. - object — A redacted thinking content block in a Messages API request or response. Emitted when thinking content is encrypted for safety reasons; must be passed back unchanged in multi-turn conversations. - `type` 'redacted_thinking', required — Content type identifier. Always `redacted_thinking`. - `data` string, required — The encrypted thinking content. - `tools` MessagesTool[] — Definitions of tools the model may call. Each tool can include `cache_control` for prompt caching. - `name` string, required — The name of the tool. - `description` string — A description of what the tool does. - `input_schema` FunctionParameters, required — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list. - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - `type` 'ephemeral', required — The cache control type. Currently only `ephemeral`. - `tool_choice` union — Controls which (if any) tool is called by the model. `auto` means the model can decide, `any` means the model must use a tool, and `tool` forces a specific tool. - 'auto' | 'any' — The tool choice mode. - object — Forces the model to use a specific tool. - `type` 'tool', required — Always `tool`. - `name` string, required — The name of the tool to use. - `stream` boolean — Whether to stream the response using server-sent events. - `temperature` number, float — Amount of randomness injected into the response. Ranges from 0.0 to 1.0. Use closer to 0 for analytical / multiple choice, closer to 1 for creative and generative tasks. - `top_p` number, float — Use nucleus sampling. Only consider the tokens with top_p probability mass. - `top_k` integer — Only sample from the top K options for each subsequent token. - `stop_sequences` string[] — Custom text sequences that will cause the model to stop generating. - `metadata` MessagesMetadata — Metadata for a Messages API request. - `user_id` string — An external identifier for the user. - `thinking` object — Configuration for extended thinking. - `type` 'enabled', required — Always `enabled`. - `budget_tokens` integer, required — The maximum number of tokens the model is allowed to use for thinking. - `output_config` MessagesOutputConfig — Output configuration for a Messages API request. - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Constrains how much effort the model spends on reasoning. Lower effort yields faster responses and fewer reasoning tokens. ## Response `200` Successful response - MessagesResponse — A message response from the Anthropic-compatible Messages API. - `id` string, required — Unique identifier for this message. - `type` 'message', required — Always `message`. - `role` 'assistant', required — Always `assistant`. - `content` MessagesResponseContentBlock[], required — The content blocks generated by the model. - union — A content block within a Messages API response. - object — A text content block in a Messages API request or response. - `type` 'text', required — Content type identifier. Always `text`. - `text` string, required — The text content. - `cache_control` CacheControl — Cache control settings for prompt caching. Currently only `ephemeral` caching is supported. - `type` 'ephemeral', required — The cache control type. Currently only `ephemeral`. - object — A tool use content block in a Messages API request or response. - `type` 'tool_use', required — Content type identifier. Always `tool_use`. - `id` string, required — The unique identifier for this tool use block. - `name` string, required — The name of the tool being called. - `input` object, required — The input parameters for the tool. - object — A thinking content block in a Messages API request or response. - `type` 'thinking', required — Content type identifier. Always `thinking`. - `thinking` string, required — The thinking content. - `signature` string, required — The signature for verifying the thinking content. Must be passed back when continuing a conversation with extended thinking. - object — A redacted thinking content block in a Messages API request or response. Emitted when thinking content is encrypted for safety reasons; must be passed back unchanged in multi-turn conversations. - `type` 'redacted_thinking', required — Content type identifier. Always `redacted_thinking`. - `data` string, required — The encrypted thinking content. - `model` string, required — The model used to generate the message. - `stop_reason` 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal', required — The reason the model stopped generating. - `stop_sequence` string, nullable — The stop sequence that caused the model to stop, if any. - `usage` MessagesUsage, required — Token usage statistics for a Messages API response, including cache metrics. - `input_tokens` integer, required — The number of input tokens. - `output_tokens` integer, required — The number of output tokens. - `cache_creation_input_tokens` integer — The number of tokens used for cache creation. - `cache_read_input_tokens` integer — The number of tokens read from the cache. ## Other responses - `400` — The selected provider does not implement the Messages API. The gateway returns this when a request is routed to a provider without Messages support. - `401` — Unauthorized - `500` — Internal server error ## Changes - **2026-07-28** `959ba033bc7d` — 1 info - added the new optional request property `output_config` - **2026-07-21** `8addad90330d` — 1 info - endpoint added [Change history](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/changes/messages/post.md) --- [API](https://skmtc.dev/inference-gateway/apis/inference-gateway-api.md) · [All operations](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inference-gateway/inference-gateway-api/revisions/fccc79b863aa/schema)