# 文本模型（LLM）快速开始

## 基础信息

- 基础域名：`https://api.apiverse.ai`
- 鉴权方式：`Authorization: Bearer <API_KEY>`
- Content-Type：`application/json`

本平台的文本模型以**各模型官方协议原生接入**：Claude 系列走 Anthropic Messages 协议，GPT 及国产模型走 OpenAI Chat Completions / Responses 协议，Gemini 系列走 Google Gemini 协议。请求体与响应体按官方标准原样透传，不裁剪可选参数——已有的官方 SDK 代码只要替换 `base_url` 与 `api_key` 即可直接调用。

## 鉴权说明

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

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

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

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

## 接口一览

| 协议 | 方法 | 路径 | 适用系列 |
| ---- | ---- | ---- | -------- |
| OpenAI Chat Completions | POST | `/v1/chat/completions` | GPT、Grok、DeepSeek、Kimi、GLM、MiniMax、Qwen |
| OpenAI Responses | POST | `/v1/responses` | GPT |
| Anthropic Messages | POST | `/v1/messages` | Claude |
| Anthropic token 预估 | POST | `/v1/messages/count_tokens` | Claude |
| Google Gemini | POST | `/v1/gemini/{version}/models/{model}:{streamMode}` | Gemini、Nano Banana |

客户端接入地址（Claude Code / Codex / Cursor 等）见「客户端接入」文档。

## 快速示例

```bash
curl -X POST "https://api.apiverse.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "<模型参数，见各系列文档>",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "用一句话介绍你自己。"}
    ]
  }'
```

成功响应（节选）：

```json
{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "<模型参数>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是一个 AI 助手，可以帮你解答问题、生成内容。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}
```

## 按系列查阅

| 系列 | 协议 | 说明 |
| ---- | ---- | ---- |
| Claude | Anthropic Messages | 支持 Beta 模式、提示词缓存、SSE event 模式 |
| Gemini | Google Gemini | 含 Nano Banana 系列图像生成 |
| GPT | OpenAI Chat Completions / Responses | 部分型号支持 Codex |
| Grok | OpenAI Chat Completions | 含 reasoning / fast 变体 |
| DeepSeek / Kimi / GLM / MiniMax / Qwen | OpenAI Chat Completions | 国产模型系列 |

## 计费说明

- 文本模型按 **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. **模型名以广场为准**：调用前请在「模型广场」确认当前可用的模型名称，不要硬编码猜测。
2. **密钥能力**：调用前确认所用 API Key 已开通「大模型」能力。
3. **跨协议调用**：如需把 Anthropic 协议模型以 OpenAI 协议调用（或反向），请自行部署协议转写服务。
4. **余额**：文本模型消费在账户余额中结算，余额查询见「余额查询 API」。