X.AI 对话（OpenAI 兼容） - 数字先锋API文档

# X.AI 对话（OpenAI 兼容） API 文档（Grok 文本模型）

## 1. 接口说明

本平台提供与 OpenAI 协议兼容的聊天补全接口，支持 Grok 系列文本模型调用。

- **Base URL**: `https://api.cxsee.com/v1`
- **Endpoint**: `POST /chat/completions`
- **协议**: OpenAI Compatible

---

## 2. 认证方式

在请求头中传入 API Key：

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

---

## 3. 支持模型（示例）

- `grok-4.1`（请求模型名）
- 响应中可能映射为：`grok-4-1-auto`

> 说明：平台可能根据可用通道自动路由，响应 `model` 字段与请求值存在别名映射属正常现象。

---

## 4. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，如 `grok-4.1` |
| messages | array | 是 | 对话消息数组（OpenAI 标准格式） |
| stream | boolean | 否 | 是否启用流式输出，默认 `false` |
| temperature | number | 否 | 采样温度（如通道支持） |
| max_tokens | number | 否 | 最大输出 token（如通道支持） |

`messages` 格式示例：
```json
[
  {"role": "user", "content": "你好，介绍下自己"}
]
```

---

## 5. cURL 调用示例

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.1",
    "messages": [
      {"role": "user", "content": "你好，介绍下自己"}
    ]
  }'
```

---

## 6. 成功响应示例

```json
{
  "id": "08a3a88e-e9c7-49df-9ddc-273e6b334796",
  "object": "chat.completion",
  "created": 1774066936,
  "model": "grok-4-1-auto",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "你好！我是 Grok 4，由 xAI 打造的..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 217,
    "total_tokens": 227
  }
}
```

---

## 7. 返回字段说明

- `choices[0].message.content`：模型回复正文
- `choices[0].finish_reason`：结束原因（如 `stop`）
- `usage.prompt_tokens`：输入 token
- `usage.completion_tokens`：输出 token
- `usage.total_tokens`：总 token 消耗

---

## 8. 错误响应示例

```json
{
  "error": {
    "message": "账户余额不足",
    "type": "bad_response_status_code",
    "code": "bad_response_status_code"
  }
}
```

常见错误原因：
- API Key 无效或缺失
- 账户余额不足
- 模型权限不足
- 请求频率超限

---

## 9. Python（OpenAI SDK）示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cxsee.com/v1"
)

resp = client.chat.completions.create(
    model="grok-4.1",
    messages=[
        {"role": "user", "content": "你好，介绍下自己"}
    ]
)

print(resp.choices[0].message.content)
```

---

## 10. 使用建议

- 建议在业务侧记录 `id`、`model`、`usage` 便于审计与计费核对
- 对 `error.message` 做统一捕获与重试/降级策略
- 生产环境建议增加超时控制与并发限制

---

上一篇：X.AI 绘画（OpenAI 兼容）下一篇：智谱对话（OpenAI 兼容）