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

# 咏唱引擎 REST API 参考

> 咏唱引擎 REST API 的基础 URL、认证方式、响应结构与错误处理。在浏览各接口分组前从本页开始。

咏唱引擎 REST API 驱动控制台、模型库与营销站点。它以两个完全相同的部署（国际站与中国站）提供，拥有独立的账户、钱包与支付提供方。

## 基础 URL

| 站点  | 基础 URL                        |
| --- | ----------------------------- |
| 国际站 | `https://ariacompute.com/api` |
| 中国站 | `https://ariacompute.cn/api`  |

有两个接口位于域名根而非 `/api`：`GET /healthz` 与 `GET /sitemap.xml`。

## 响应格式

所有 JSON 响应使用 `application/json; charset=utf-8`。时间戳为 UTC 的 ISO 8601 格式（例如 `2026-09-23T10:00:00Z`）。下载接口以 `302` 重定向，或以 `Content-Disposition` 流式返回二进制内容。

## 认证

三种模式覆盖全部接口：

| 接口分类                                                | 认证                                           |
| --------------------------------------------------- | -------------------------------------------- |
| `/api/auth/*`、`/api/billing/*`、`/api/api-keys`      | 会话 JWT，通过 `Authorization: Bearer`            |
| `/api/models/{slug}/download`、网关                    | API 密钥 `bfvk-...`，通过 `Authorization: Bearer` |
| 浏览器中的发票、收据、模型下载链接                                   | 同一 JWT，通过 `?token=` 查询参数                     |
| 公开接口（site、pricing、providers、changelog、downloads/\*） | 无需认证                                         |

详见 [认证概览](/api-reference/authentication)。

## 接口分组

| 分组     | 基础路径                                                 |
| ------ | ---------------------------------------------------- |
| 认证     | `/api/auth`                                          |
| API 密钥 | `/api/api-keys`                                      |
| 模型     | `/api/models`                                        |
| 发布下载   | `/api/download`                                      |
| 计费     | `/api/billing`                                       |
| 站点元数据  | `/api/site`、`/api/pricing`、`/api/payments/providers` |
| 健康检查   | `/healthz`                                           |

## 错误

错误以 HTTP 状态码配合 JSON `{ "error": "..." }` 返回。完整状态码表与重试建议见[错误参考](/resources/errors)。

## 限流

频繁调用者可能收到 `429 Too Many Requests`。请使用指数退避叠加抖动重试。