为咏唱引擎 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。

curl -X POST https://ariacompute.cn/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "[email protected]", "password": "..."}'

{
  "token": "eyJhbGciOi...",
  "user": { "id": "usr_123", "email": "[email protected]" }
}

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

创建 API 密钥

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

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，绝不返回完整值。

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

查询令牌下载

部分文件接口支持 ?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 重新认证。

快速开始

核心概念

指南

SDK

资源

为咏唱引擎 API 请求认证

三种凭证

获取会话 JWT

创建 API 密钥

查询令牌下载

失败模式

​三种凭证

​获取会话 JWT

​创建 API 密钥

​查询令牌下载

​失败模式

三种凭证

获取会话 JWT

创建 API 密钥

查询令牌下载

失败模式