为咏唱引擎 API 请求认证

咏唱引擎 API 有三种认证方式，用哪个取决于接口：用户作用域接口用会话 JWT，网关与模型下载用 API 密钥，浏览器里的下载链接可以用短时效查询令牌。

三种凭证

凭证	Header 或参数	获取来源	用途
会话 JWT	`Authorization: Bearer <jwt>`	`POST /api/auth/login` 或 OAuth 回调	所有 `/api/auth/`、`/api/billing/`、`/api/api-keys` 接口
API 密钥	`Authorization: Bearer YOUR_API_KEY`	`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 密钥是虚拟密钥，可以在控制台或用 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，不会再给出完整值。

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

查询令牌下载

部分文件接口支持 ?token=<jwt>：浏览器里的普通 <a href> 链接没法自定义请求头，所以这些接口也接受 ?token=。用于：

GET /api/billing/invoices/{paymentId}/download?token=...
GET /api/billing/receipts/{paymentId}/download?token=...

这个令牌就是你放在 Authorization 头里的那个会话 JWT。

失败模式

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

会话令牌时效较短。过期后重新调用 POST /api/auth/login 认证。

快速开始

产品

指南

SDK

资源

为咏唱引擎 API 请求认证

三种凭证

获取会话 JWT

创建 API 密钥

查询令牌下载

失败模式

​三种凭证

​获取会话 JWT

​创建 API 密钥

​查询令牌下载

​失败模式

三种凭证

获取会话 JWT

创建 API 密钥

查询令牌下载

失败模式