> ## 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.

# 为咏唱引擎 API 请求认证

> 会话 JWT、bfvk API 密钥与查询令牌下载：如何获取各类凭证，以及哪些接口接受它们。

咏唱引擎 API 支持三种认证请求的方式。使用哪一种取决于具体接口：用户作用域接口使用会话 JWT，网关与模型下载使用 API 密钥，浏览器发起的下载链接可使用短时效查询令牌。

## 三种凭证

| 凭证     | Header 或参数                       | 获取来源                              | 用途                                                   |
| ------ | -------------------------------- | --------------------------------- | ---------------------------------------------------- |
| 会话 JWT | `Authorization: Bearer <jwt>`    | `POST /api/auth/login` 或 OAuth 回调 | 所有 `/api/auth/*`、`/api/billing/*`、`/api/api-keys` 接口 |
| API 密钥 | `Authorization: Bearer bfvk-...` | `POST /api/api-keys`              | 模型下载、各站点网关（`gateway.ariacompute.com` / `.cn`）        |
| 查询令牌   | `?token=<jwt>`                   | 同一个 JWT，但置于 URL 中                 | 浏览器发起的文件下载（发票、收据、模型）                                 |

## 获取会话 JWT

使用邮箱、手机号或 OAuth 登录。响应中包含 JWT。

```bash theme={null}
curl -X POST https://ariacompute.cn/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "you@example.com", "password": "..."}'
```

```json theme={null}
{
  "token": "eyJhbGciOi...",
  "user": { "id": "usr_123", "email": "you@example.com" }
}
```

在每次用户作用域请求中，将该令牌作为 `Authorization: Bearer eyJhbGciOi...` 发送。如果账户启用了 2FA，登录响应会指示一个挑战，你必须在收到完整会话前先调用 `POST /api/auth/2fa/verify`。

## 创建 API 密钥

API 密钥是带有 `bfvk-` 前缀的 Bifrost 虚拟密钥。它们从控制台或 API 创建，用于各站点网关与认证下载接口。

```bash theme={null}
curl -X POST https://ariacompute.cn/api/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'
```

完整密钥在响应中仅返回一次，字段名为 `key`。请将其存入密钥管理器。后续 `GET /api/api-keys` 响应只返回 `prefix`，绝不返回完整值。

<Warning>
  切勿将 `bfvk-` 密钥嵌入客户端代码。仅可在服务端或 CLI 中使用。
</Warning>

## 查询令牌下载

部分文件接口支持 `?token=<jwt>`，以便浏览器中的普通 `<a href>` 链接无需设置 Header 即可下载文件。适用于：

* `GET /api/models/{slug}/download?token=...`
* `GET /api/billing/invoices/{paymentId}/download?token=...`
* `GET /api/billing/receipts/{paymentId}/download?token=...`

该令牌即你在 `Authorization` Header 中使用的同一个会话 JWT。

## 失败模式

| 状态                      | 原因                      |
| ----------------------- | ----------------------- |
| `401 Unauthorized`      | 缺失、过期或无效的会话令牌 / API 密钥。 |
| `403 Forbidden`         | 已认证但无权限（例如非管理员调用管理员接口）。 |
| `429 Too Many Requests` | 触发限流。请退避后重试。            |

会话令牌时效较短。当前令牌过期时，通过调用 `POST /api/auth/login` 重新认证。