> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/messages — Claude 原生格式

> 使用 Anthropic Claude 原生 Messages 格式发送请求。Anyone 支持直接使用 Claude SDK。

`/v1/messages` 端点接受 Anthropic 原生 Claude Messages API 格式的请求。如果你已使用 `anthropic` Python 或 JavaScript SDK，只需修改 base URL 即可将请求指向 Anyone——所有请求和响应字段完全一致。Anyone 使用你控制台中的 token 进行认证，并将请求路由到配置好的 Claude 渠道。你也可以将 Claude 格式的请求发送到非 Claude 上游渠道，Anyone 会自动转换格式。

## 端点

```
POST /v1/messages
```

## 认证

Claude Messages 请求使用两个头（非 `Authorization`）：

| 头字段                 | 是否必需 | 说明                |
| ------------------- | ---- | ----------------- |
| `x-api-key`         | 是    | 你的 Anyone API key |
| `anthropic-version` | 是    | 必须为 `2023-06-01`  |

<Note>
  如果你的客户端不支持 `x-api-key`，也可使用 `Authorization: Bearer YOUR_TOKEN`。Anyone 两种方式都接受。
</Note>

## 请求参数

<ParamField body="model" type="string" required>
  要使用的 Claude 模型，例如 `claude-opus-4-6` 或 `claude-sonnet-4-6`。要启用扩展思考，使用 `-thinking` 模型名后缀：`claude-sonnet-4-6-thinking`。
</ParamField>

<ParamField body="messages" type="object[]" required>
  对话历史。消息在 `user` 和 `assistant` 角色间交替。第一条消息必须是 `user` 角色。

  <Expandable title="消息属性">
    <ParamField body="messages[].role" type="string" required>
      消息作者角色。可选 `"user"` 或 `"assistant"`。
    </ParamField>

    <ParamField body="messages[].content" type="string | object[]" required>
      消息内容。纯文本传字符串，多模态输入传内容块数组。

      每个内容块是一个带 `type` 字段的对象。支持的类型：

      * `"text"` — 文本块，含 `text` 字段
      * `"image"` — 图片块，含 `source` 对象（包含 `type`（`"base64"` 或 `"url"`）、`media_type` 和 `data` 或 `url`）
      * `"tool_use"` — 模型生成的 tool calling，含 `id`、`name` 和 `input`
      * `"tool_result"` — tool calling 的结果，含 `tool_use_id` 和 `content`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  最大生成 token 数。Claude Messages API 要求此字段必填。值不得超过模型的输出 token 限制。
</ParamField>

<ParamField body="system" type="string | object[]">
  系统提示词，为对话设置上下文和指令。传字符串，或传内容块数组用于高级场景（如缓存系统提示词）。
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  设为 `true` 时，响应以 Anthropic 流式格式的 SSE 返回。事件类型包括 `message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta` 和 `message_stop`。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，范围 `0` 到 `1`。值越高输出越多样。
</ParamField>

<ParamField body="top_p" type="number">
  核采样概率质量，取值 `0` 到 `1`。建议在不设 `temperature` 时使用。
</ParamField>

<ParamField body="top_k" type="integer">
  仅从最可能的前 `k` 个 token 中采样。大多数场景不建议使用。
</ParamField>

<ParamField body="stop_sequences" type="string[]">
  自定义停止序列。模型遇到这些序列时停止生成，输出不包含停止序列本身。
</ParamField>

<ParamField body="tools" type="object[]">
  模型可调用的工具。每个工具定义一个可调用的函数。

  <Expandable title="工具属性">
    <ParamField body="tools[].name" type="string" required>
      工具名称。必须匹配 `^[a-zA-Z0-9_-]{1,64}$`。
    </ParamField>

    <ParamField body="tools[].description" type="string">
      工具功能描述。模型根据此描述决定何时调用。
    </ParamField>

    <ParamField body="tools[].input_schema" type="object" required>
      工具的输入参数，JSON Schema 格式。顶层必须为 `type: "object"`，包含 `properties` 映射和可选的 `required` 数组。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="object">
  控制模型如何选择工具。

  <Expandable title="tool_choice 属性">
    <ParamField body="tool_choice.type" type="string" required>
      可选 `"auto"`（模型决定）、`"any"`（必须调用工具）或 `"tool"`（必须调用指定工具）。
    </ParamField>

    <ParamField body="tool_choice.name" type="string">
      当 `type` 为 `"tool"` 时必填。要调用的工具名称。
    </ParamField>

    <ParamField body="tool_choice.disable_parallel_tool_use" type="boolean" default="false">
      设为 `true` 时，模型每次只能调用一个工具。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="thinking" type="object">
  为支持的模型启用扩展思考。也可使用 `-thinking` 模型名后缀作为替代。

  <Expandable title="thinking 属性">
    <ParamField body="thinking.type" type="string" required>
      必须为 `"enabled"`。
    </ParamField>

    <ParamField body="thinking.budget_tokens" type="integer">
      模型在生成响应前可用于内部推理的最大 token 数。
    </ParamField>
  </Expandable>
</ParamField>

## 响应字段

<ResponseField name="id" type="string">
  此消息的唯一标识符，格式为 `msg_...`。
</ResponseField>

<ResponseField name="type" type="string">
  完整响应始终为 `"message"`。
</ResponseField>

<ResponseField name="role" type="string">
  生成消息的角色，始终为 `"assistant"`。
</ResponseField>

<ResponseField name="content" type="object[]">
  响应中的内容块数组。

  <Expandable title="内容块属性">
    <ResponseField name="content[].type" type="string">
      块类型：`"text"` 为文本输出，`"tool_use"` 为模型调用工具，`"thinking"` 为扩展思考内容。
    </ResponseField>

    <ResponseField name="content[].text" type="string">
      文本内容。`type` 为 `"text"` 时出现。
    </ResponseField>

    <ResponseField name="content[].id" type="string">
      tool call ID。`type` 为 `"tool_use"` 时出现。
    </ResponseField>

    <ResponseField name="content[].name" type="string">
      工具名称。`type` 为 `"tool_use"` 时出现。
    </ResponseField>

    <ResponseField name="content[].input" type="object">
      tool calling 参数。`type` 为 `"tool_use"` 时出现。
    </ResponseField>

    <ResponseField name="content[].thinking" type="string">
      模型的推理内容。`type` 为 `"thinking"` 且启用扩展思考时出现。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  生成响应的模型。
</ResponseField>

<ResponseField name="stop_reason" type="string">
  模型停止生成的原因。可选值：`"end_turn"`（自然结束）、`"max_tokens"`（达到 token 限制）、`"stop_sequence"`（匹配自定义停止序列）或 `"tool_use"`（模型调用了工具）。
</ResponseField>

<ResponseField name="usage" type="object">
  此次请求的 token 用量统计。

  <Expandable title="usage 属性">
    <ResponseField name="usage.input_tokens" type="integer">
      输入消息和系统提示词中的 token 数量。
    </ResponseField>

    <ResponseField name="usage.output_tokens" type="integer">
      生成响应中的 token 数量。
    </ResponseField>

    <ResponseField name="usage.cache_creation_input_tokens" type="integer">
      写入提示词缓存的 token 数量（使用缓存时）。
    </ResponseField>

    <ResponseField name="usage.cache_read_input_tokens" type="integer">
      从提示词缓存读取的 token 数量（使用缓存时）。
    </ResponseField>
  </Expandable>
</ResponseField>

## 示例

<Tabs>
  <Tab title="非流式">
    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.anyone.ai/v1/messages \
        -H "x-api-key: YOUR_TOKEN" \
        -H "anthropic-version: 2023-06-01" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "claude-opus-4-6",
          "max_tokens": 1024,
          "system": "You are a concise technical assistant.",
          "messages": [
            {"role": "user", "content": "Explain what a mutex is in one paragraph."}
          ]
        }'
      ```

      ```python Python (anthropic SDK) theme={null}
      import anthropic

      client = anthropic.Anthropic(
          api_key="YOUR_TOKEN",
          base_url="https://api.anyone.ai",
      )

      message = client.messages.create(
          model="claude-opus-4-6",
          max_tokens=1024,
          system="You are a concise technical assistant.",
          messages=[
              {"role": "user", "content": "Explain what a mutex is in one paragraph."}
          ],
      )

      print(message.content[0].text)
      ```

      ```javascript JavaScript (anthropic SDK) theme={null}
      import Anthropic from "@anthropic-ai/sdk";

      const client = new Anthropic({
        apiKey: "YOUR_TOKEN",
        baseURL: "https://api.anyone.ai",
      });

      const message = await client.messages.create({
        model: "claude-opus-4-6",
        max_tokens: 1024,
        system: "You are a concise technical assistant.",
        messages: [
          { role: "user", content: "Explain what a mutex is in one paragraph." },
        ],
      });

      console.log(message.content[0].text);
      ```
    </CodeGroup>

    **响应示例：**

    ```json theme={null}
    {
      "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "A mutex (mutual exclusion lock) is a synchronization primitive that ensures only one thread can access a shared resource at a time..."
        }
      ],
      "model": "claude-opus-4-6",
      "stop_reason": "end_turn",
      "usage": {
        "input_tokens": 28,
        "output_tokens": 87,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0
      }
    }
    ```
  </Tab>

  <Tab title="流式">
    ```bash cURL theme={null}
    curl https://api.anyone.ai/v1/messages \
      -H "x-api-key: YOUR_TOKEN" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "claude-opus-4-6",
        "max_tokens": 512,
        "stream": true,
        "messages": [
          {"role": "user", "content": "Write a haiku about databases."}
        ]
      }'
    ```

    服务端以 Anthropic 流式格式发送事件：

    ```
    event: message_start
    data: {"type":"message_start","message":{"id":"msg_01abc","type":"message","role":"assistant","content":[],"model":"claude-opus-4-6","stop_reason":null,"usage":{"input_tokens":14,"output_tokens":0}}}

    event: content_block_start
    data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

    event: content_block_delta
    data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Rows"}}

    event: message_stop
    data: {"type":"message_stop"}
    ```
  </Tab>

  <Tab title="Tool calling">
    ```bash cURL theme={null}
    curl https://api.anyone.ai/v1/messages \
      -H "x-api-key: YOUR_TOKEN" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "tools": [
          {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "City name, e.g. San Francisco"
                }
              },
              "required": ["location"]
            }
          }
        ],
        "messages": [
          {"role": "user", "content": "What is the weather in Tokyo?"}
        ]
      }'
    ```
  </Tab>
</Tabs>

## 格式转换

你也可以将 Claude 格式请求（`/v1/messages`）路由到非 Claude 上游渠道。Anyone 自动进行格式转换，将 Claude Messages 格式翻译为上游服务商的原生格式。这让你可以用单一客户端格式跨服务商调用。转换为尽力而为；某些 Claude 特有功能（如扩展思考）可能在所有上游渠道中不可用。