> ## 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 认证：会话令牌与 API 密钥

> 咏唱引擎 API 三种认证方式的详细说明：会话 JWT、bfvk API 密钥，以及用于文件下载的查询令牌。

咏唱引擎 API 接受三种凭证类型。本页说明每种凭证的来源、发送方式，以及哪些接口需要哪一种。

## 凭证摘要

| 凭证     | 发送方式                                  | 获取来源                                                        | 典型用途       |
| ------ | ------------------------------------- | ----------------------------------------------------------- | ---------- |
| 会话 JWT | `Authorization: Bearer eyJhbGciOi...` | `POST /api/auth/login`、OAuth 回调、`POST /api/auth/2fa/verify` | 控制台作用域调用   |
| API 密钥 | `Authorization: Bearer bfvk-...`      | `POST /api/api-keys`                                        | 网关与模型下载    |
| 查询令牌   | `?token=eyJhbGciOi...`                | 上述同一 JWT                                                    | 浏览器发起的文件下载 |

## 会话 JWT

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

将返回的 `token` 作为 `Authorization: Bearer` 发送在每次用户作用域请求中。会话 JWT 时效较短；请再次调用登录以刷新。

若启用了 2FA，登录响应会指示一个挑战，你必须调用 `POST /api/auth/2fa/verify` 才能收到最终会话。

## API 密钥（bfvk-）

使用会话 JWT 创建密钥：

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

响应包含完整密钥，仅在此返回一次，字段名为 `key`。请存入密钥管理器，并在模型下载与网关调用中作为 `Authorization: Bearer bfvk-...` 发送。

<Warning>
  切勿在客户端 JavaScript、移动 App 或公开代码仓库中暴露 `bfvk-` 密钥。任何读取到密钥的人都可能消耗你的钱包。
</Warning>

## 查询令牌

部分文件接口接受 `?token=<jwt>`，以便浏览器中的锚点标签无需设置 Header 即可触发下载。该令牌即上述同一会话 JWT。

受支持的接口：

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

## 令牌过期与刷新

会话 JWT 会自动过期；请再次调用 `POST /api/auth/login`（或 2FA 验证接口）以获取新令牌。API 密钥在你 `DELETE` 之前始终有效。

## 失败模式

| 状态    | 原因           |
| ----- | ------------ |
| `401` | 缺失、过期或无效的凭证。 |
| `403` | 已认证但无权限。     |
| `429` | 请求过多。退避后重试。  |