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

# Create message

`POST /messages`

Create conversational messages using the Anthropic-compatible Messages API

## Headers

- `anthropic-version` string, required
- `anthropic-beta` string

## Request body

- MessageRequest
  - `model` string, required — The model that will complete your prompt. See the list of Claude models at https://docs.claude.com/en/docs/about-claude/models
  - `messages` AnthropicMessage[], required — Input messages. Alternating user and assistant conversational turns. The first message must use the user role. Text content is the only format supported for the first user message.
    - `role` 'user' | 'assistant', required — The role of the messages author
    - `content` union, required
      - string — Plain text content
      - AnthropicContentBlock[] — Array of content blocks (text, image, tool_use, tool_result)
        - union
          - object — Text content block
            - `type` 'text', required
            - `text` string, required
            - `cache_control` object
              - …
          - object — Image content block
            - `type` 'image', required
            - `source` object, required
              - …
            - `cache_control` object
              - …
          - object — Tool use content block
            - `type` 'tool_use', required
            - `id` string, required — A unique identifier for this particular tool use block
            - `name` string, required — The name of the tool being used
            - `input` object, required — An object containing the input being passed to the tool
          - object — Tool result content block
            - `type` 'tool_result', required
            - `tool_use_id` string, required — The id of the tool use request this is a result for
            - `content` union, required — The result of the tool use
              - …
            - `is_error` boolean — Set to true if the tool execution resulted in an error
            - `cache_control` object
              - …
  - `max_tokens` integer, required — The maximum number of tokens to generate before stopping. Note that Claude may stop before reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
  - `system` union — System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role.
    - string — System prompt as plain text
    - object[] — Array of system content blocks
      - `type` 'text', required
      - `text` string, required
      - `cache_control` object
        - `type` 'ephemeral'
  - `temperature` 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.
  - `top_p` number — Use nucleus sampling. In nucleus sampling, Claude computes the cumulative distribution over all the options for each subsequent token in decreasing probability order and cuts it off once it reaches a particular probability specified by top_p.
  - `top_k` integer — Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. Recommended for advanced use cases only. You usually only need to use temperature.
  - `stream` boolean — Whether to incrementally stream the response using server-sent events. See streaming documentation for details.
  - `stop_sequences` string[] — Custom text sequences that will cause the model to stop generating. Claude will stop when it encounters any of these strings.
  - `tools` AnthropicTool[] — 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.
    - `name` string, required — The name of the tool. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
    - `description` string — Description of what this tool does. Tool descriptions should be as detailed as possible.
    - `input_schema` object, required — JSON schema for the tool input shape that the model will produce in tool_use output content blocks.
      - `type` 'object', required
      - `properties` object, required
      - `required` string[]
    - `cache_control` object
      - `type` 'ephemeral'
  - `tool_choice` union — How the model should use the provided tools. The model can use a specific tool, any available tool, or decide by itself.
    - object — allows Claude to decide whether to call any provided tools or not
      - `type` 'auto', required
    - object — tells Claude that it must use one of the provided tools
      - `type` 'any', required
    - object — allows Claude to use only the specified tool
      - `type` 'tool', required
      - `name` string, required
  - `thinking` object — Enable extended thinking by Claude. When enabled, Claude will think through the problem before responding.
    - `type` 'enabled'
    - `budget_tokens` integer — Maximum number of tokens to spend on thinking
  - `service_tier` 'auto' | 'standard_only' — The service tier to use for the request. 'auto' lets us choose the tier, 'standard_only' restricts to standard tier.
  - `metadata` object — An object describing metadata about the request
    - `user_id` string — An external identifier for the user who is associated with the request

## Response `200`

Successful response

- MessageResponse
  - `id` string, required — Unique object identifier. The format and length of IDs may change over time.
  - `type` 'message', required — Object type. For Messages, this is always 'message'.
  - `role` 'assistant', required — Conversational role of the generated message. This is always 'assistant'.
  - `content` AnthropicResponseContentBlock[], required — Content generated by the model. This is an array of content blocks, each of which has a type that determines its shape.
    - union
      - object — Text content block in response
        - `type` 'text', required
        - `text` string, required — The text content
      - object — Thinking content block showing Claude's reasoning process
        - `type` 'thinking', required
        - `thinking` string, required — Claude's internal thinking process
      - object — Tool use content block
        - `type` 'tool_use', required
        - `id` string, required — A unique identifier for this particular tool use block
        - `name` string, required — The name of the tool being used
        - `input` object, required — An object containing the input being passed to the tool
  - `model` string, required — The model that handled the request.
  - `stop_reason` 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use', required — The reason that we stopped. This may be one of 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), or tool_use (the model invoked one or more tools).
  - `stop_sequence` string, nullable — 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.
  - `usage` object, required — Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.
    - `input_tokens` integer, required — The number of input tokens which were used.
    - `output_tokens` integer, required — The number of output tokens which were used.
    - `cache_creation_input_tokens` integer — The number of input tokens used to create the cache entry.
    - `cache_read_input_tokens` integer — The number of input tokens read from the cache.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `429` — Rate limit exceeded
- `500` — Internal server error

---

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