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

# 网关与认证

> Ace Data Cloud API 网关域名、请求头、认证方式与常见错误。

Ace Data Cloud 所有 API 都通过 `https://api.acedata.cloud` 接入，使用 **Bearer Token** 认证。

## 网关与平台域名

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

    所有业务调用的入口。
  </Card>

  <Card title="开发者控制台" icon="browser">
    `https://platform.acedata.cloud`

    订阅、凭证管理、用量统计。
  </Card>

  <Card title="身份认证" icon="key">
    `https://auth.acedata.cloud`

    单点登录与 OAuth2 端点。
  </Card>

  <Card title="状态页" icon="signal">
    `https://status.acedata.cloud`

    服务可用性与故障历史。
  </Card>
</CardGroup>

## 获取 API Token

<Steps>
  <Step title="注册账号">
    在 [platform.acedata.cloud](https://platform.acedata.cloud) 注册账号。
  </Step>

  <Step title="订阅服务">
    打开你想用的服务（Midjourney / Suno / Claude / …）详情页，购买套餐或领取试用额度。
  </Step>

  <Step title="创建凭证">
    在服务的「凭证」页点击「创建凭证」，复制返回的 Token——这就是后续请求要带的 API Key。
  </Step>
</Steps>

## 凭证种类

* **业务凭证**：在 [platform.acedata.cloud](https://platform.acedata.cloud) 各服务页创建，用于调用 `api.acedata.cloud` 上的业务接口。可绑定到具体的「实例应用」从实例余额扣费，或使用「通用应用」从通用余额扣费（取决于创建时的应用作用域）。
* **平台 Token**（前缀 `platform-`）：用于平台管理 API（账号、订阅等），**不要**用于业务调用。

## 请求头

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

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

## 常见认证 / 计费错误

下面列出的 `error.code` 都来自 `PlatformGateway` 的真实异常定义。响应主体形如 `{"error": {"code": "...", "message": "..."}, "trace_id": "..."}`，**没有** `success` 字段。

### 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 for current request, please buy more in Ace Data Cloud https://platform.acedata.cloud"
  },
  "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>