# Claude 系列 API 对接文档

## 基础信息

- 基础域名：`https://api.apiverse.ai`
- 接口路径：`POST https://api.apiverse.ai/v1/messages`
- 鉴权方式：`Authorization: Bearer <API_KEY>`
- Content-Type：`application/json`
- 协议：**兼容 Anthropic Messages 标准协议**，可直接复用 Anthropic 官方 SDK，仅需替换 `base_url` 与 `api_key`。

Claude 系列以 Anthropic Messages 协议接入，请求体与响应体字段与标准协议保持一致，未裁剪可选参数。如需以 OpenAI 协议调用 Claude 模型（或反向跨协议转发），请自行部署协议转写服务。

## 鉴权说明

- 所有接口均使用 Bearer Token（API Key）鉴权，请在请求头携带：

  ```
  Authorization: Bearer <API_KEY>
  ```

- API Key 在控制台「API 密钥」页面创建，需在创建时开通「大模型」能力后方可调用本组接口。
- 若使用未开通大模型能力的 Key 调用，会返回 `403`：

  ```json
  {
    "error": {
      "message": "该 API Key 尚未开通 LLM 能力，请在控制台重新创建 API Key 完成开通",
      "type": "permission_error"
    }
  }
  ```

## 支持的模型

把请求体中的 `model` 字段替换为下表「模型参数」列的取值，即可切换模型。

| 模型 | 模型参数（model） | 别名（Cursor 模式） |
| ---- | ---- | ---- |
| Claude Opus 5 | global.anthropic.claude-opus-5 | fc-cc-opus5 |
| Claude Sonnet 5 | global.anthropic.claude-sonnet-5 | fc-cc-sonnet5 |
| Claude Fable 5 | global.anthropic.claude-fable-5 | fc-cc-fable5 |
| Claude Opus 4.8 | global.anthropic.claude-opus-4-8 | fc-cc-opus48 |
| Claude Opus 4.7 | global.anthropic.claude-opus-4-7 | fc-cc-opus47 |
| Claude Sonnet 4.6 | global.anthropic.claude-sonnet-4-6 | fc-cc-sonnet46 |
| Claude Opus 4.6 | global.anthropic.claude-opus-4-6-v1 | fc-cc-opus46 |
| Claude Opus 4.5 | global.anthropic.claude-opus-4-5-20251101-v1:0 | fc-cc-opus45 |
| Claude Sonnet 4.5 | us.anthropic.claude-sonnet-4-5-20250929-v1:0 | fc-cc-sonnet45 |
| Claude Haiku 4.5 | global.anthropic.claude-haiku-4-5-20251001-v1:0 | fc-cc-haiku45 |

> 「别名」列用于 Cursor 等只接受简短模型名的客户端，详见「客户端接入」文档。

> 实际可调用的模型以你的账户已开通的资源为准。完整模型清单、上下文长度与单价请以控制台「模型广场」「定价」页面展示为准，请勿硬编码猜测模型名。

## 调用方式

### cURL

```bash
curl -X POST "https://api.apiverse.ai/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "global.anthropic.claude-sonnet-5",
    "max_tokens": 8192,
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "大哥你好？"}]}
    ]
  }'
```

### 请求体（含 system 与多轮对话）

```json
{
    "model": "global.anthropic.claude-sonnet-5",
    "stream": true,
    "max_tokens": 8192,
    "system": [
        {
            "type": "text",
            "text": "你是一只猫娘，回答问题要尽量用 喵~ 的语气"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "你好，哥们"}
            ]
        },
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "嘿，哥们！你好啊！有什么可以帮你的吗？"}
            ]
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "写个笑话"}
            ]
        }
    ]
}
```

### token 预估

- 接口路径：`POST https://api.apiverse.ai/v1/messages/count_tokens`
- 请求体与 `/v1/messages` 一致（无需 `max_tokens`），返回本次消息的输入 token 估算值。

## 可选特性

可选特性以 query 参数形式拼在请求 URL 后，可叠加，例如 `?claude_beta=true&sse_event=true`。

### 1. Beta 模式

```
https://api.apiverse.ai/v1/messages?claude_beta=true
```

> 注意：Beta 模式下 `content` 只能为**数组**，字符串写法会报 `400 Bad Request`。

错误写法（会报 `400`，提示 `messages.0.content: Field required`）：

```json
{
    "max_tokens": 8000,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}
```

正确写法：

```json
{
    "max_tokens": 8000,
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Hello, world"}
            ]
        }
    ]
}
```

### 2. 提示词缓存

在 content 块上加 `cache_control` 可强制缓存该段前缀，命中缓存的部分按缓存价计费：

```json
{
    "model": "global.anthropic.claude-sonnet-5",
    "max_tokens": 8000,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, world",
                    "cache_control": { "type": "ephemeral" }
                }
            ]
        }
    ]
}
```

### 3. SSE event 模式（默认开启）

```
https://api.apiverse.ai/v1/messages?sse_event=true
```

流式返回在 `data:` 之外额外携带 `event:` 字段：

```
event: message_start
data: {"type":"message_start","message":{"model":"claude-sonnet-5","id":"msg_xxx","type":"message","role":"assistant","content":[],"usage":{"input_tokens":10,"output_tokens":3}}}
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":"Hello! How"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" can I help you today?"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
event: message_stop
data: {"type":"message_stop"}
```

## 计费说明

- 文本模型按 **token 用量**计费，通常区分输入 / 输出，部分模型另有缓存读写、思考（thinking）、多模态图片等维度，不同模型单价不同。
- **各模型的具体单价与计价维度，请以控制台「定价」页面展示为准。**
- 每次调用的 token 用量以响应中的 `usage` 字段为准；账户维度的用量、账单与消费汇总可在控制台「用量」「账单」页面查看，并支持导出。
- 文本模型消费在账户余额中结算，调用前请确保余额充足（余额可通过「余额查询 API」查询）。

## 错误码说明

| 状态码 | 说明 | 解决方案 |
| ------ | ---- | -------- |
| 401 | 未授权 / API Key 无效 | 检查 `Authorization` 头与 API Key 是否正确 |
| 403 | API Key 未开通大模型能力 | 在控制台重新创建并开通大模型能力的 API Key |
| 429 | 触发限流或上游繁忙 | 退避后重试；持续出现请联系技术支持 |
| 666 | 模型调用相关异常（统一错误码） | 复制响应体中的 `code_reason` 联系技术支持 |
| 5xx | 服务内部异常 | 稍后重试或联系技术支持 |

模型调用类异常统一以 HTTP 状态码 `666` 返回，响应体形如：

```json
{
  "code": 9000,
  "code_msg": "服务器异常",
  "code_reason": "具体原因，排查时请连同该字段一起提供"
}
```

其余错误响应结构遵循所用协议的标准格式，例如 OpenAI 兼容协议：

```json
{
  "error": {
    "message": "invalid api key",
    "type": "invalid_request_error",
    "code": "401"
  }
}
```

## 注意事项

1. **协议一致**：请优先使用 Anthropic 官方 SDK 与官方请求体，跨协议转写存在字段不兼容风险。
2. **模型名以广场为准**：调用前请在「模型广场」确认当前可用的模型名称，不要硬编码猜测。
3. **密钥能力**：调用前确认所用 API Key 已开通「大模型」能力。
4. **在 IDE 中使用**：Claude Code、Cursor 等客户端的接入配置见「客户端接入」文档。