鉴权

Yeehoo 当前对外 API 主要面向服务端接入，因此默认鉴权方式是 API Key。

Bearer 鉴权

所有对外 API 请求统一使用：

Authorization: Bearer sk_yeehoo_xxx

/v1/* 根据该 API Key 解析所属团队工作空间。不要传递 X-Yeehoo-Workspace-ID 来尝试切换空间：该 Header 不会被 /v1/* 读取，也不会影响积分、任务或资产归属。请先阅读团队工作空间与 API 使用。

两套鉴权要明确分开

• 控制台接口：使用登录态 session，给人操作后台或控制台用
• 对外能力接口：使用 API Key，给你的服务端程序调用用

这也是为什么你直接调某些控制台接口时，如果没有有效 session，会返回：

{
  "error": {
    "code": "unauthenticated",
    "message": "missing or invalid session"
  }
}

为什么不建议把 API Key 放到前端页面里

不建议把正式 API Key 直接放进浏览器前端代码，因为：

• 容易泄露
• 不利于限流和权限控制
• 生产环境不方便做审计和轮换

推荐做法是：

• 浏览器前端调用你的业务服务
• 你的业务服务再调用 Yeehoo 对外 API

幂等键建议

创建型接口建议带上 Idempotency-Key，尤其是：

• 图片生成
• 视频生成

这样当你的服务因为超时或网络波动重试时，可以避免重复创建任务。

相同 Key 和相同请求体会返回首次响应，并带 Idempotency-Replayed: true。相同 Key 配不同请求体会返回 409 idempotency_conflict；首次请求仍在处理时返回 409 idempotency_in_progress 和 Retry-After: 2。等待后使用同一个 Key 和同一个请求体重试。

推荐做法

• 每个环境使用独立 API Key
• 测试与生产分开
• 定期轮换 key
• 如果使用 webhook，每个 key 配置独立 webhook_secret