Anthropic Conversation Format (Messages)

Anthropic Conversation Format (Messages)

This page at a glance

Official documentation

• Anthropic Messages
• Anthropic Streaming Messages

📝 Overview

Given a structured list of input messages containing text and/or image content, the model will generate the next message in the conversation. The Messages API can be used for a single query or for stateless multi-turn conversations.

💡 Request Examples

Basic text conversation ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

Response example:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

Image analysis conversation ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "/9j/4AAQSkZJRg..."
                    }
                },
                {
                    "type": "text",
                    "text": "What’s in this image?"
                }
            ]
        }
    ]
}'

Response example:

{
  "content": [
    {
      "text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松，眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-4-6-sonnet-20251022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

Tool calling ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-4-6-sonnet-20251022",
    "messages": [
        {
            "role": "user",
            "content": "What’s the weather like in Beijing today?"
        }
    ],
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather for a specified location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g. Beijing"
                    }
                },
                "required": ["location"]
            }
        }
    ]
}'

Response example:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "北京" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-4-6-sonnet-20251022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

Streaming response ✅

curl https://4All API地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-4-6-sonnet-20251022",
    "messages": [
        {
            "role": "user",
            "content": "Tell me a story"
        }
    ],
    "stream": true
}'

Response example:

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-4-6-sonnet-20251022",
    "role": "assistant",
    "type": "message"
  }
}
{
  "type": "content_block_start",
  "index": 0,
  "content_block": {
    "type": "text"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "从前"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "有一只"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "小兔子..."
  }
}
{
  "type": "content_block_stop",
  "index": 0
}
{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 2045,
      "output_tokens": 628
    }
  }
}
{
  "type": "message_stop"
}

📮 Request

Endpoint

POST /v1/messages

Authentication

Use API key authentication by including the following in the request headers:

x-api-key: $4All API_API_KEY

Where $4All API_API_KEY is your API key. You can obtain an API key from the console, and each key is limited to a single workspace.

Request header parameters

anthropic-beta

• Type: string
• Required: No

Specifies the beta version to use. Supports a comma-separated list such as beta1,beta2, or the header may be specified multiple times.

anthropic-version

• Type: string
• Required: Yes

Specifies the API version to use.

Request body parameters

max_tokens

• Type: integer
• Required: Yes

The maximum number of tokens to generate. Different models have different limits; see the model documentation for details. Range: x > 1.

messages

• Type: array of objects
• Required: Yes

The list of input messages. The model is trained to alternate between user and assistant turns. When creating a new message, you can use the messages parameter to provide prior turns, and the model will generate the next message in the conversation. Consecutive user or assistant messages will be merged into a single turn.

Each message must include role and content. You can provide a single user message or multiple user and assistant messages. If the last message uses the assistant role, the response content will continue directly from that message’s content, which can be used to constrain the model’s output.

Example of a single user message:

[{"role": "user", "content": "Hello, Claude"}]

Example of a multi-turn conversation:

[
  {"role": "user", "content": "你好。"},
  {"role": "assistant", "content": "你好！我是 Claude。有什么可以帮你的吗？"},
  {"role": "user", "content": "请用简单的话解释什么是 LLM？"}
]

Example of a partially filled response:

[
  {"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "正确答案是 ("}
]

The content of each message can be a string or an array of content blocks. Using a string is shorthand for an array containing a single "text" content block. The following two forms are equivalent:

{"role": "user", "content": "Hello, Claude"}

{
  "role": "user",
  "content": [{"type": "text", "text": "Hello, Claude"}]
}

Starting with Claude 3 models, you can also send image content blocks:

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    },
    {
      "type": "text",
      "text": "What’s in this image?"
    }
  ]
}

Currently supported image formats include: base64, image/jpeg, image/png, image/gif, and image/webp.

messages.role

• Type: enum string
• Required: Yes
• Allowed values: user, assistant

Note: The Messages API does not have a "system" role. If you need system instructions, use the top-level system parameter.

messages.content [

• Type: string or array of objects
• Required: Yes

Message content can be one of the following types:

Text content (Text)

{
  "type": "text",          // Required, enum value: "text"
  "text": "Hello, Claude", // Required, minimum length: 1
  "cache_control": {
    "type": "ephemeral"    // Optional, enum value: "ephemeral"
  }
}

Image content (Image)

{
  "type": "image",         // Required, enum value: "image"
  "source": {              // Required
    "type": "base64",      // Required, enum value: "base64"
    "media_type": "image/jpeg", // Required, supported: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..."  // Required, base64-encoded image data
  },
  "cache_control": {
    "type": "ephemeral"    // Optional, enum value: "ephemeral"
  }
}

Tool use (Tool Use)

{
  "type": "tool_use",      // Required, enum value: "tool_use", default value
  "id": "toolu_xyz...",    // Required, unique identifier for the tool use
  "name": "get_weather",   // Required, tool name, minimum length: 1
  "input": {              // Required, tool input parameter object
    // Tool input parameters; the exact format is defined by the tool's `input_schema`
  },
  "cache_control": {
    "type": "ephemeral"    // Optional, enum value: "ephemeral"
  }
}

Tool result (Tool Result)

{
  "type": "tool_result",   // Required, enum value: "tool_result"
  "tool_use_id": "toolu_xyz...",  // Required
  "content": "Result content",   // Required, can be a string or an array of content blocks
  "is_error": false,      // Optional, boolean
  "cache_control": {
    "type": "ephemeral"    // Optional, enum value: "ephemeral"
  }
}

When content is an array of content blocks, each block can be text or image:

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text",      // Required, enum value: "text"
      "text": "Analysis result",   // Required, minimum length: 1
      "cache_control": {
        "type": "ephemeral" // Optional, enum value: "ephemeral"
      }
    },
    {
      "type": "image",     // Required, enum value: "image"
      "source": {         // Required
        "type": "base64", // Required, enum value: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Document (Document)

{
  "type": "document",      // Required, enum value: "document"
  "source": {             // Required
    // Document source data
  },
  "cache_control": {
    "type": "ephemeral"    // Optional, enum value: "ephemeral"
  }
}

Note:

1. Each type can include an optional cache_control field to control caching behavior.
2. Text content has a minimum length of 1.
3. The type field is required for all types and must be an enum string.
4. The content field of tool results supports either a string or an array of content blocks containing text and/or images.

model

• Type: string
• Required: Yes

The name of the model to use; see the model documentation for details. Length: 1 to 256 characters.

metadata

• Type: object
• Required: No

An object describing request metadata. Contains the following optional field:

• user_id: An external identifier for the user associated with the request. It should be a UUID, hash, or another opaque identifier. Do not include any identifying information such as a name, email address, or phone number. Maximum length: 256.

stop_sequences

• Type: string array
• Required: No

Custom text sequences that stop generation.

stream

• Type: boolean
• Required: No

Whether to use server-sent events (SSE) to stream the response content incrementally.

system

• Type: string
• Required: No

The system prompt, which provides Claude with background and instructions. This is a way to give the model context and specific goals or roles. Note that this is different from the message role; the Messages API does not have a "system" role.

temperature

• Type: number
• Required: No
• Default: 1.0

Controls randomness in generation, from 0.0 to 1.0. Range: 0 < x < 1. Values close to 0.0 are recommended for analytical or multiple-choice tasks, while values close to 1.0 are recommended for creative and generative tasks.

Note: Even when temperature is set to 0.0, the result is not fully deterministic.

🆕 thinking

• Type: object
• Required: No

Configures Claude’s extended thinking feature. When enabled, the response will include content blocks that show Claude’s thought process before it gives the final answer. Requires a budget of at least 1,024 tokens and counts toward your max_tokens limit.

It can be set to one of two modes:

1. Enabled mode

{
  "type": "enabled",
  "budget_tokens": 2048
}

• type: Required, enum value: "enabled"
• budget_tokens: Required, integer. Determines how many tokens Claude can use for its internal reasoning process. A larger budget allows deeper analysis of complex problems and can improve response quality. Must be >= 1024 and less than max_tokens. Range: x > 1024.

2. Disabled mode

{
  "type": "disabled"
}

• type: Required, enum value: "disabled"

tool_choice

• Type: object
• Required: No

Controls how the model uses the provided tools. It can be one of the following three types:

1. Auto mode

{
  "type": "auto",  // Required, enum value: "auto"
  "disable_parallel_tool_use": false  // Optional, default false. If true, the model will use at most one tool
}

2. Any mode

{
  "type": "any",  // Required, enum value: "any"
  "disable_parallel_tool_use": false  // Optional, default false. If true, the model will use exactly one tool
}

3. Tool mode

{
  "type": "tool",  // Required, enum value: "tool"
  "name": "get_weather",  // Required, specifies the tool name to use
  "disable_parallel_tool_use": false  // Optional, default false. If true, the model will use exactly one tool
}

Note:

1. Auto mode: the model can decide whether to use tools on its own.
2. Any mode: the model must use a tool, but may choose any available tool.
3. Tool mode: the model must use the specified tool.

tools

• Type: array of objects
• Required: No

Defines the tools the model may use. Tools can be custom tools or built-in tool types:

1. Custom tools (Tool)

Each custom tool definition includes:

• type: Optional, enum value: "custom"
• name: Tool name, required, 1–64 characters
• description: Tool description; the more detailed, the better
• input_schema: JSON Schema definition for the tool input, required
• cache_control: Optional cache control, with type set to "ephemeral"

Example:

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "Get the current weather for a specified location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name, e.g. Beijing"
        }
      },
      "required": ["location"]
    }
  }
]

2. Computer tool (ComputerUseTool)

{
  "type": "computer_20241022",  // Required
  "name": "computer",           // Required, enum value: "computer"
  "display_width_px": 1024,     // Required, display width in pixels
  "display_height_px": 768,     // Required, display height in pixels
  "display_number": 0,          // Optional, X11 display number
  "cache_control": {
    "type": "ephemeral"         // Optional
  }
}

3. Bash tool (BashTool)

{
  "type": "bash_20241022",      // Required
  "name": "bash",               // Required, enum value: "bash"
  "cache_control": {
    "type": "ephemeral"         // Optional
  }
}

4. Text editor tool (TextEditor)

{
  "type": "text_editor_20241022", // Required
  "name": "str_replace_editor",   // Required, enum value: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral"           // Optional
  }
}

When the model uses a tool, it will return a tool_use content block:

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

You can execute the tool and return the result with a tool_result content block:

[
  {