Claude Messages（函数调用） - 数字先锋API文档

##  Claude Messages（函数调用）API 文档

## 1. 接口地址

`POST /v1/messages`

示例：
`https://api.cxsee.com/v1/messages`

---

## 2. 认证方式

在请求头中传入 API Key：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

> 如你的网关有特殊配置，可额外要求：`x-api-key: YOUR_API_KEY`。

---

## 3. 请求参数（核心）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名称，如 `claude-opus-4-6` |
| `messages` | array | 是 | 对话消息列表 |
| `max_tokens` | number | 否 | 最大输出 token 数 |
| `tools` | array | 否 | 可调用函数（工具）定义 |
| `tool_choice` | object/string | 否 | 工具调用策略（`auto`/`any`/指定工具） |

### `messages` 说明
常见结构：
```json
[
  {"role":"user","content":"..."}
]
```

---

## 4. 函数（工具）定义格式

```json
{
  "name": "get_weather",
  "description": "查询指定城市的实时天气",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称，例如：北京"
      }
    },
    "required": ["city"]
  }
}
```

---

## 5. 调用流程（两步）

## 第一步：让模型决定是否调用工具

### 请求示例
```bash
curl --location --request POST "https://api.cxsee.com/v1/messages" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "请查询北京今天的天气，并告诉我穿衣建议"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "查询指定城市的实时天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {"type": "auto"}
  }'
```

### 期望响应特征
当模型决定调用工具时，`content` 中会出现 `tool_use` 块，例如：
```json
{
  "type": "tool_use",
  "id": "toolu_123",
  "name": "get_weather",
  "input": {"city": "北京"}
}
```

---

## 第二步：把工具结果回传给模型

你服务端执行 `get_weather(city=北京)` 后，将结果以 `tool_result` 形式回传：

```bash
curl --location --request POST "https://api.cxsee.com/v1/messages" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "请查询北京今天的天气，并告诉我穿衣建议"
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "get_weather",
            "input": {"city": "北京"}
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "tool_result",
            "tool_use_id": "toolu_123",
            "content": "{\"city\":\"北京\",\"weather\":\"晴\",\"temp_c\":26,\"humidity\":35}"
          }
        ]
      }
    ]
  }'
```

模型会输出最终面向用户的自然语言结果（天气总结 + 穿衣建议）。

---

## 6. 错误码建议（对外）

| HTTP状态码 | 含义 |
|---|---|
| 400 | 参数错误（JSON 格式、字段缺失） |
| 401 | 认证失败（API Key 无效） |
| 403 | 无权限访问模型 |
| 429 | 触发限流 |
| 500 | 服务内部错误 |

---

## 7. 最佳实践

1. **不要在前端暴露 API Key**，工具调用应在服务端执行。
2. 若希望更容易触发工具调用，可在用户问题中明确“请调用 get_weather”。
3. `tool_choice:auto` 由模型判断；若要强制调用，可改为指定工具。
4. 生产环境建议记录 `id`、`usage`、耗时、错误码用于审计与计费。

---

上一篇：Claude Messages（思考）下一篇：Claude Chat（OpenAI 兼容）