> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 网关与认证

> XHuoAPI 网关域名、请求头、认证方式与常见错误码说明。

XHuoAPI 所有接口通过 `https://api.xhuoapi.ai/v1` 接入，完全兼容 OpenAI 格式，使用 **Bearer Token** 认证。

## 网关与平台域名

<CardGroup cols={2}>
  <Card title="API 网关" icon="globe">
    `https://api.xhuoapi.ai/v1`

    所有模型调用的入口（OpenAI 兼容）。
  </Card>

  <Card title="开发者控制台" icon="browser">
    `https://api.xhuoapi.ai`

    充值、令牌管理、用量统计。
  </Card>

  <Card title="官方网站" icon="house">
    `https://xhuoapi.ai`

    产品介绍与模型价格。
  </Card>

  <Card title="模型价格" icon="dollar-sign">
    `https://api.xhuoapi.ai/pricing`

    全部模型定价一览。
  </Card>
</CardGroup>

## 获取 API Key

<Steps>
  <Step title="注册账号">
    在 [api.xhuoapi.ai/register](https://api.xhuoapi.ai/register) 注册账号。
  </Step>

  <Step title="充值余额">
    登录控制台，在「充值」页面选择金额充值（支持支付宝）。
  </Step>

  <Step title="创建令牌">
    在「令牌」页面点击「创建令牌」，复制生成的 Key（以 `sk-` 开头）——这就是后续请求的 API Key。
  </Step>
</Steps>

## API Key 说明

* **统一密钥**：一个 API Key 即可调用平台上所有模型（GPT、Claude、Gemini 等），无需为每个模型单独申请
* **按量扣费**：调用时自动从账户余额扣除对应 token 费用

## 请求头

```
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
```

| 字段              | 是否必需      | 说明                           |
| --------------- | --------- | ---------------------------- |
| `Authorization` | 必需        | `Bearer ` 前缀（注意空格）+ 你的 Token |
| `Content-Type`  | POST 请求必需 | `application/json`，UTF-8 编码  |

## 常见认证 / 计费错误

XHuoAPI 兼容 OpenAI 错误格式。响应主体形如 `{"error": {"message": "...", "type": "...", "code": "..."}}`。

### 401 — Token 无效

```json theme={null}
{
  "error": {
    "code": "invalid_token",
    "message": "The specified token is invalid or wrong."
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

可能的 `error.code`：

* `invalid_token`：Token 拼写错误或已撤销
* `token_expired`：Token 已过期
* `token_mismatched`：Token 格式不匹配

### 400 — 请求格式问题

* `bad_request`：JSON payload 不合法
* `no_token`：缺少 `Authorization` 头

### 403 — 余额耗尽或访问受限

```json theme={null}
{
  "error": {
    "code": "used_up",
    "message": "Your balance is not sufficient, please top up at https://api.xhuoapi.ai"
  },
  "trace_id": "..."
}
```

* `used_up`：账户余额不足，请充值
* `disabled`：令牌已被禁用
* `forbidden`：上游内容审核拒绝（敏感词、版权材料等）

### 404 — 接口不存在

* `no_api`：请求路径未注册

### 429 — 触发速率限制

```json theme={null}
{
  "error": {
    "code": "too_many_requests",
    "message": "You have exceeded the rate limit."
  },
  "trace_id": "..."
}
```

请实施指数退避后重试。

### 500 / 504

* `api_error`：网关或上游内部错误
* `timeout`：上游推理超时

## 安全最佳实践

* **永远不要**把 Token 硬编码到浏览器 / 移动端 / 桌面端代码里——一定要走自己的后端中转
* 用环境变量或密钥管理服务保管 Token
* 为开发、预发、生产分别创建独立 Token
* 怀疑泄漏时立刻在控制台撤销并重新生成

## 下一步

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/quickstart">
    跑通你的第一个请求
  </Card>

  <Card title="响应格式" icon="brackets-curly" href="/concepts/responses">
    成功与失败的响应字段
  </Card>

  <Card title="异步任务" icon="arrows-rotate" href="/concepts/async-tasks">
    轮询与 Webhook 回调
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference">
    交互式 API 文档
  </Card>
</CardGroup>