---
title: "Create a message"
method: POST
path: "/v1/messages"
tags: ["Messages"]
---

# Create a message

`POST /v1/messages`

Creates a response message for the provided conversation. Compatible with the Anthropic Messages API, so the Anthropic SDK works against this endpoint by changing `base_url` and overriding the default `x-api-key` header with `Authorization`. Support is in beta; behavior may change before general availability.

## Request body

- MessagesRequest — Request body for creating a message.
  - `model` string, required — The model slug to use. Find available models at [Model APIs](https://app.baseten.co/model-apis/create).
  - `messages` InputMessage[], required — The conversation history as an ordered list of input messages. Alternating `user` and `assistant` roles are expected; the final message must be from the `user`.
    - `role` 'user' | 'assistant', required — The role of the message author. System prompts are passed via the top-level `system` field, not as a message.
    - `content` union, required — The message content. Pass a string for text-only messages or an array of content blocks for messages that include tool calls or tool results.
      - string
      - union[]
        - union
          - TextBlock — A text content block.
            - `type` 'text', required — The block type, always `text`.
            - `text` string, required — The text content.
          - ToolUseBlock — A tool use content block generated by the model.
            - `type` 'tool_use', required — The block type, always `tool_use`.
            - `id` string, required — A unique identifier for this tool call. Use this as `tool_use_id` in the matching tool result.
            - `name` string, required — The name of the tool being called.
            - `input` object, required — The arguments passed to the tool, matching the tool's `input_schema`.
          - ToolResultBlock — A tool result content block supplied by the user in response to a tool call.
            - `type` 'tool_result', required — The block type, always `tool_result`.
            - `tool_use_id` string, required — The `id` of the `tool_use` block this result responds to.
            - `content` union, required — The tool's output. Pass a string for simple results or an array of text blocks for structured output.
              - …
            - `is_error` boolean — Set to `true` if the tool call raised an error.
  - `max_tokens` integer, required — The maximum number of tokens to generate in the response. Required by the Messages API. The response may be shorter if it finishes naturally or hits a stop sequence.
  - `system` union — A system prompt that sets the model's behavior. Pass either a single string or an array of text content blocks.
    - string
    - TextBlock[]
      - `type` 'text', required — The block type, always `text`.
      - `text` string, required — The text content.
  - `temperature` number — Controls randomness. Lower values are more deterministic. Range: 0 to 1.
  - `top_p` number — Nucleus sampling: only consider tokens with cumulative probability up to this value.
  - `top_k` integer — Limits token selection to the top K most probable tokens at each step.
  - `stop_sequences` string[] — Custom text sequences that will stop generation. When a stop sequence is hit, `stop_reason` is `stop_sequence` and `stop_sequence` contains the matched string.
  - `stream` boolean — If `true`, the response is streamed as server-sent events. Each event has a `type` such as `message_start`, `content_block_delta`, or `message_stop`.
  - `tools` ToolDefinition[] — A list of tools the model may call. Each tool has a `name`, `description`, and `input_schema` (a JSON Schema object).
    - `name` string, required — A unique name for the tool.
    - `description` string — A description of what the tool does. The model uses this to decide when to call it.
    - `input_schema` object, required — A JSON Schema object describing the tool's expected input.
  - `tool_choice` union — Controls which tool (if any) the model calls.
    - object
      - `type` 'auto', required — The model decides whether to call a tool.
      - `disable_parallel_tool_use` boolean — If `true`, restricts the model to calling at most one tool per response.
    - object
      - `type` 'any', required — The model must call a tool but may pick which one.
    - object
      - `type` 'tool', required — The model must call the named tool.
      - `name` string, required — The exact name of the tool to call.
    - object
      - `type` 'none', required — The model must not call any tool.
  - `metadata` object — An object describing metadata about the request. Supports `user_id` for abuse detection.
    - `user_id` string — An external identifier for the end user.

## Response `200`

Successful response

- MessagesResponse — The message response returned by the model.
  - `id` string, required — A unique identifier for this message, such as `msg_abc123`.
  - `type` 'message', required — The object type, always `message`.
  - `role` 'assistant', required — The role of the generated message, always `assistant`.
  - `content` union[], required — An array of content blocks generated by the model. Text responses contain a single `text` block; responses that invoke tools contain `tool_use` blocks.
    - union
      - TextBlock — A text content block.
        - `type` 'text', required — The block type, always `text`.
        - `text` string, required — The text content.
      - ToolUseBlock — A tool use content block generated by the model.
        - `type` 'tool_use', required — The block type, always `tool_use`.
        - `id` string, required — A unique identifier for this tool call. Use this as `tool_use_id` in the matching tool result.
        - `name` string, required — The name of the tool being called.
        - `input` object, required — The arguments passed to the tool, matching the tool's `input_schema`.
  - `model` string, required — The model slug that produced the response.
  - `stop_reason` 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use', required — Why the model stopped generating: `end_turn` (natural stop), `max_tokens` (hit the `max_tokens` limit), `stop_sequence` (matched a `stop_sequences` entry), or `tool_use` (model invoked a tool).
  - `stop_sequence` string, nullable — The stop sequence that was matched, if `stop_reason` is `stop_sequence`. Otherwise `null`.
  - `usage` Usage, required — Token usage statistics.
    - `input_tokens` integer — The number of input tokens processed.
    - `output_tokens` integer — The number of output tokens generated.
    - `cache_read_input_tokens` integer — The number of input tokens served from cache. Counted as a subset of `input_tokens`, not in addition to it (unlike the Anthropic API, where `input_tokens` excludes cached tokens). Caching is automatic; no `cache_control` blocks are required and there is no `cache_creation_input_tokens` field. Some models omit this field.

## Other responses

- `400` — Bad request: invalid parameters.
- `401` — Unauthorized: invalid or missing API key. The Anthropic SDK's default `x-api-key` header is not accepted — pass `Authorization: Bearer <BASETEN_API_KEY>` or `Authorization: Api-Key <BASETEN_API_KEY>`.
- `404` — Model not found or does not support the Messages API.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

---

[API](https://skmtc.net/baseten/apis/baseten-inference-api.md) · [All operations](https://skmtc.net/baseten/apis/baseten-inference-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/baseten/baseten-inference-api/revisions/a55a2f64c3c5/schema)