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

# POST /v1/messages — Anthropic 原生消息接口

> 兼容 Anthropic Messages API 原生格式，支持 Anthropic SDK 直连、系统提示词、视觉输入、流式输出与工具调用。

`POST https://geekapis.com/v1/messages` 是与 Anthropic Messages API 完全兼容的原生接口，支持直接使用 Anthropic 官方 SDK（Python / JavaScript）对接，仅需将 `base_url` 修改为 即刻API 地址。支持流式输出（SSE）、多轮对话、系统提示词、视觉输入和工具调用。

<Note>
  **选择接口的建议**

  * 若您已使用 **OpenAI SDK** 或希望兼容多模型，推荐使用 [Chat Completions 接口](/cn/api-reference/chat/chat)。
  * 若您在使用 **Anthropic SDK** 或 **Claude Code**，推荐使用本接口，可直接接入，无需修改代码结构。
</Note>

## 鉴权

本接口支持两种认证方式，任选其一：

<ParamField header="Authorization" type="string">
  Bearer Token 认证，适用于直接 HTTP 调用：

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

<ParamField header="x-api-key" type="string">
  API Key 认证，与 Anthropic SDK 兼容：

  ```text theme={null}
  x-api-key: YOUR_API_KEY
  ```
</ParamField>

<ParamField header="anthropic-version" default="2023-06-01" type="string">
  Anthropic API 版本号。使用 Anthropic SDK 时会自动传入。推荐值：`2023-06-01`。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型名称，支持所有 Claude 系列模型，例如：

  * `claude-opus-4-6`（旗舰，复杂推理与高质量创作）
  * `claude-sonnet-4-6`（性能与成本最佳平衡）
  * `claude-haiku-4-5`（速度最快、成本最低）
</ParamField>

<ParamField body="messages" type="object[]" required>
  对话消息列表，按时间先后顺序排列。**只支持 `user` 和 `assistant` 角色**，系统提示词请使用顶层 `system` 字段。

  <Expandable title="messages[n] 字段">
    <ParamField body="role" type="string" required>
      消息角色，可选值：`user` 或 `assistant`。
    </ParamField>

    <ParamField body="content" type="string | object[]" required>
      消息内容，支持字符串或内容块数组。

      <Expandable title="内容块（content block）">
        <ParamField body="type" type="string" required>
          内容类型：`text`（文本）或 `image`（图片）。
        </ParamField>

        <ParamField body="text" type="string">
          文本内容，`type` 为 `text` 时必填。
        </ParamField>

        <ParamField body="source" type="object">
          图片来源，`type` 为 `image` 时必填。

          <Expandable title="source 字段">
            <ParamField body="type" type="string" required>
              图片来源类型：`base64`（Base64 编码）或 `url`（图片链接）。
            </ParamField>

            <ParamField body="media_type" type="string">
              MIME 类型，`source.type` 为 `base64` 时必填。例如：`image/jpeg`、`image/png`、`image/gif`、`image/webp`。
            </ParamField>

            <ParamField body="data" type="string">
              Base64 编码的图片数据，`source.type` 为 `base64` 时必填。
            </ParamField>

            <ParamField body="url" type="string">
              图片 URL，`source.type` 为 `url` 时必填。
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  生成内容的最大 token 数量。不同模型上限不同：

  * `claude-sonnet-4-6`：最大 `64000`
  * `claude-opus-4-6`：最大 `32000`
</ParamField>

<ParamField body="system" type="string | object[]">
  系统提示词，在顶层设置（**不要**放在 `messages` 数组中）。支持字符串或内容块数组格式。
</ParamField>

<ParamField body="stream" default="false" type="boolean">
  是否启用流式输出（Server-Sent Events）。

  * `true`：逐 token 流式返回，事件格式遵循 Anthropic SSE 规范
  * `false`：等待完整响应后一次性返回
</ParamField>

<ParamField body="temperature" default="1" type="number">
  采样温度，控制输出随机性。范围：`0` \~ `1`。
</ParamField>

<ParamField body="top_p" type="number">
  核采样概率阈值。范围：`0` \~ `1`。建议不要同时设置 `temperature` 和 `top_p`。
</ParamField>

<ParamField body="stop_sequences" type="string[]">
  停止序列，遇到指定字符串时立即停止生成。
</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="content[n] 字段">
    <ResponseField name="type" type="string">
      内容类型，通常为 `text`。
    </ResponseField>

    <ResponseField name="text" type="string">
      生成的文本内容。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  实际使用的模型名称。
</ResponseField>

<ResponseField name="stop_reason" type="string">
  停止原因：

  * `end_turn`：模型正常结束输出
  * `max_tokens`：达到 `max_tokens` 限制
  * `stop_sequence`：触发了 `stop_sequences` 中的停止序列
</ResponseField>

<ResponseField name="usage" type="object">
  本次请求的 token 消耗统计。

  <Expandable title="usage 字段">
    <ResponseField name="input_tokens" type="integer">
      输入 token 数。
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      输出 token 数。
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/messages \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [
        {
          "role": "user",
          "content": "你好，请介绍一下你自己"
        }
      ]
    }'
  ```

  ```bash cURL（带系统提示词） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/messages \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "system": "你是一个专业的 Python 编程助手，回答简洁直接。",
      "messages": [
        {
          "role": "user",
          "content": "如何反转一个列表？"
        }
      ]
    }'
  ```

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

  client = anthropic.Anthropic(
      api_key="YOUR_API_KEY",
      base_url="https://geekapis.com"
  )

  message = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=1024,
      messages=[
          {"role": "user", "content": "你好，请介绍一下你自己"}
      ]
  )

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

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

  const client = new Anthropic({
    apiKey: "YOUR_API_KEY",
    baseURL: "https://geekapis.com"
  });

  const message = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "你好，请介绍一下你自己" }
    ]
  });

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

## 响应示例

```json 200 - 成功响应 theme={null}
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "你好！我是 Claude，由 Anthropic 开发的 AI 助手。我可以帮助你回答问题、分析信息、编写代码、创作内容等。有什么我可以帮你的吗？"
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 38
  }
}
```

<Note>
  **流式输出（SSE）事件格式**

  当 `stream: true` 时，响应以 Anthropic SSE 规范推送，事件类型包括：`message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta`、`message_stop`。

  使用 Anthropic SDK 的 `stream()` 方法可自动处理所有流式事件，无需手动解析。
</Note>

## 错误码

| HTTP 状态码 | 说明                       | 解决方案                                               |
| -------- | ------------------------ | -------------------------------------------------- |
| `400`    | 请求参数错误（如缺少 `max_tokens`） | 确保 `model`、`messages`、`max_tokens` 均已正确传入          |
| `401`    | 身份验证失败                   | 检查 `Authorization` 头或 `x-api-key` 头中的 API Key 是否有效 |
| `429`    | 请求频率超限                   | 降低并发请求数或实现退避重试策略                                   |