# Grok 系列 API 对接文档

## 基础信息

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

Grok 系列以 OpenAI Chat Completions 协议接入，请求体与响应体字段与标准协议保持一致，未列出的可选参数按原字段透传。

## 鉴权说明

- 所有接口均使用 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） |
| ---- | ---- |
| Grok 4.6 | grok-4.6 |
| Grok 4.5 | grok-4.5 |
| Grok 4.3 | grok-4.3 |
| Grok 4-20 Reasoning | grok-4-20-reasoning |
| Grok 4-20 Non-Reasoning | grok-4-20-non-reasoning |
| Grok 4-1 Fast Reasoning | grok-4-1-fast-reasoning |
| Grok 4-1 Fast Non-Reasoning | grok-4-1-fast-non-reasoning |

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

## 调用方式

文本模型对话接口采用行业通用的 OpenAI 兼容协议，请求体与响应体字段与标准协议保持一致，未列出的可选参数按原字段透传。已有的 OpenAI 客户端代码，只要把请求地址指向本平台域名、把密钥换成本平台 API Key，即可直接调用。

- 接口路径：`POST https://api.apiverse.ai/v1/chat/completions`

### cURL

```bash
curl -X POST "https://api.apiverse.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己。"}
    ]
  }'
```

### 请求体（多轮对话）

```json
{
    "model": "grok-4.6",
    "stream": true,
    "messages": [
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "你是一个乐于助人的助手。"}
            ]
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "用一句话介绍你自己。"}
            ]
        }
    ]
}
```

### Python（OpenAI SDK）

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.apiverse.ai/v1",
    api_key="<API_KEY>",
)

resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

## 请求参数

以下为常用参数，均遵循 OpenAI 兼容协议。未列出的可选参数会按原字段透传。

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| model | string | 是 | 模型参数，取值见上方「支持的模型」。 |
| messages | array | 是 | 对话消息列表，元素含 `role`（`system`/`user`/`assistant`）与 `content`。 |
| stream | boolean | 否 | 是否流式返回，默认 `false`。为 `true` 时以 SSE 分块推送。 |
| temperature | number | 否 | 采样温度。 |
| top_p | number | 否 | 核采样阈值。 |
| max_tokens | int | 否 | 本次生成的最大 token 数。 |
| stop | string / array | 否 | 停止序列。 |

## 流式调用

请求体中 `stream` 设为 `true`，服务端以 **Server-Sent Events（SSE）** 分块推送，每个数据块以 `data: ` 开头，最后以 `data: [DONE]` 结束。

```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"春"},"index":0}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"风"},"index":0}]}

data: [DONE]
```

## 计费说明

- 文本模型按 **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. **协议兼容**：接口遵循 OpenAI 兼容协议，可直接使用 OpenAI 官方或社区 SDK，仅替换 `base_url` 与 `api_key`。
2. **模型名以广场为准**：调用前请在「模型广场」确认当前可用的模型名称，不要硬编码猜测。
3. **密钥能力**：调用前确认所用 API Key 已开通「大模型」能力。
4. **用量与账单**：逐次 token 用量见响应 `usage`；聚合用量与消费金额见控制台「用量」「账单」页面。