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

# Claude 消息接口

> 使用 Anthropic Messages 原生格式调用 Claude 模型。

# Claude 消息接口

Claude Messages 接口保留 Anthropic 原生请求结构，适合已有 Claude SDK 或原生提示词结构的业务迁移。可用模型与实际能力以账户配置和模型列表返回为准。

<Info>
  当前站点已验证 `claude-fable-5`、`claude-opus-4-8`、`claude-sonnet-5` 和 `claude-haiku-4-5-20251001` 可以通过该接口调用。生产环境仍建议先请求 [模型列表](./models)，确认当前 API Key 的可用范围。
</Info>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

也可以使用 Claude 原生请求头：

```http theme={null}
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
```

## 请求体

<ParamField body="model" type="string" required>
  Claude 模型名称。
</ParamField>

<ParamField body="messages" type="array<object>" required>
  对话消息数组。Claude 原生格式中消息角色通常为 `user` 或 `assistant`。
</ParamField>

<ParamField body="system" type="string | array<object>">
  系统提示词。Claude 不使用 `system` 角色消息，而是通过该字段传递系统指令。
</ParamField>

<ParamField body="max_tokens" type="integer">
  最大输出 token 数。Anthropic 原生请求通常要求显式传入；当前网关可能提供默认值，但生产请求建议固定传入。
</ParamField>

<ParamField body="stream" type="boolean">
  是否启用 SSE 流式输出。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度。Claude Sonnet 5、Claude Opus 4.8 等新模型官方要求不要设置非默认采样参数；建议省略该字段，用系统提示词控制风格。
</ParamField>

<ParamField body="top_p" type="number">
  核采样参数。Claude Sonnet 5、Claude Opus 4.8 等新模型会拒绝非默认 `top_p`；如果返回参数不支持错误，请删除该字段。
</ParamField>

<ParamField body="top_k" type="integer">
  Top-K 采样参数。Claude Sonnet 5、Claude Opus 4.8 等新模型会拒绝非默认 `top_k`；是否支持取决于模型和上游。
</ParamField>

<ParamField body="stop_sequences" type="array<string>">
  停止序列。
</ParamField>

<ParamField body="tools" type="array<object>">
  Claude 工具列表，通常包含 `name`、`description` 与 `input_schema`。
</ParamField>

<ParamField body="tool_choice" type="object">
  控制工具选择策略，例如 `{ "type": "tool", "name": "get_weather" }`。
</ParamField>

<ParamField body="thinking" type="object">
  思考配置。Claude Sonnet 5 和 Opus 4.8 官方推荐自适应思考；旧式 `{ "type": "enabled", "budget_tokens": ... }` 可能返回 `400`，请优先使用模型支持的 adaptive/effort 写法。
</ParamField>

<ParamField body="effort" type="string">
  部分 Claude 新模型支持的思考强度，常见值为 `low`、`medium`、`high`、`xhigh`。当前站点已验证 `claude-fable-5` 可接受 `xhigh`。
</ParamField>

<ParamField body="metadata" type="object">
  业务侧元数据，例如 `user_id`。
</ParamField>

## 请求示例

<RequestExample>
  ```bash theme={null}
  curl -X POST https://www.geeknow.top/v1/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 512,
      "system": "你是一个严谨的技术顾问。",
      "messages": [
        {
          "role": "user",
          "content": "解释一下 API 网关为什么需要限流。"
        }
      ]
    }'
  ```
</RequestExample>

### 多模态输入

URL 图片需要公网可访问。如果本地图片没有稳定 URL，先上传到图床，再把返回的 URL 放进 `source.url`。base64 图片则使用 `source.type: "base64"`，且 `data` 只放纯 base64 字符串。

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://YOUR_IMAGE_HOST/path/architecture.png"
            }
          },
          { "type": "text", "text": "这张架构图里有哪些风险点？" }
        ]
      }
    ]
  }'
```

base64 写法：

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          },
          { "type": "text", "text": "描述这张图片。" }
        ]
      }
    ]
  }'
```

### 工具调用

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "上海今天适合骑行吗？" }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "查询城市天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

## 响应示例

<ResponseExample>
  ```json 200 - 非流式 theme={null}
  {
    "id": "msg_abc123",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-5",
    "content": [
      {
        "type": "text",
        "text": "API 网关限流可以保护上游服务，避免突发流量耗尽资源，并为不同用户提供稳定的服务质量。"
      }
    ],
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 32,
      "output_tokens": 45
    }
  }
  ```

  ```text 200 - 流式 theme={null}
  event: message_start
  data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[],"model":"claude-sonnet-5"}}

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

  event: message_delta
  data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":45}}

  event: message_stop
  data: {"type":"message_stop"}
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "field model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 相关接口

* [Chat Completions（非流式）](./chat-completions-non-stream)
* [Chat Completions（流式）](./chat-completions-stream)
* [模型列表](./models)