鉴权

每个 API 请求都用 bearer token 带上密钥：

curl https://api.h3.studio/v2/video_generation \
  -H "Authorization: Bearer h3sk-…"

获取密钥

在控制台的 API 密钥 里创建。明文只显示一次。 我们只存 argon2 哈希和一小段前缀 —— 我们无法帮你找回， 把数据库拖走的人也换不出可用的密钥。

按用途命名（production、ci、laptop）。密钥泄漏时， 你希望要吊销的正好只有一把。

吊销

吊销立即生效：下一个请求就是 401，没有缓冲期。 所以轮换的顺序是：先签发新密钥、部署上去、再吊销旧的。

401 长什么样

{
  "type": "error",
  "error": {
    "type": "authorized_error",
    "message": "authentication failed, please carry the API secret key in the 'Authorization' field of the request header (1004)",
    "http_code": "401"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

所有鉴权失败返回同一句话 —— 密钥不存在、已吊销、已过期、账号被停用， 文案完全一致。这是故意的：更具体的报错会告诉猜密钥的人哪次猜得更接近。

密钥只放服务端

一把密钥就是花钱的权限。绝不要把它发到浏览器或 App 里： 任何人打开网络面板就拿到了。请从你自己的后端调用这套 API， 给你的终端用户发你自己的凭据。

如果需要浏览器直传素材，用 文件接口 —— 它签发的是 限定单个对象、短时效的 URL，那才是可以安全交给浏览器的东西。

控制台用的是另一套凭据

登录网站产生的是会话 Cookie，只在 /console/v1/* 上有效。 API key 不能登录控制台，会话 Cookie 也不能调 API。 两类调用方，两套凭据，互不重叠。