API Key 配置
API Key 固定归属于团队工作空间，并承载调用权限和 webhook 回调配置。
API Key 仅能在有效的团队工作空间中创建和使用。个人工作空间不支持创建或调用 API Key；团队工作空间的 Owner 或 Admin 可管理该空间的 Key。
Key 创建后，积分、用量、任务、上传资产和 Webhook 都固定归属于该团队工作空间。详情见团队工作空间与 API 使用。
每个 API Key 当前最多配置：
- 一个
webhook_url - 一个
webhook_secret - 一组
webhook_events - 一个
webhook_enabled
权限 Scope
| Scope | 可调用能力 |
|---|---|
v1:read | 模型列表、预估积分、任务查询、余额和用量查询 |
v1:generate | 创建图片/视频任务、上传参考图片；通常同时保留 v1:read 以便报价和轮询 |
生产 Key 建议只授予业务实际需要的 Scope。缺少权限时返回 403 scope_forbidden。
这套配置的意义
不是“只是多一个 URL”。
它的本质是把“这个 key 产生的异步任务，最终通知该发到哪里、怎么验签、哪些事件要推送”都挂在同一个 key 上。
这样做的好处：
- 测试 key 和正式 key 可以走不同回调地址
- 不同客户的 key 可以各自回调到自己的系统
- 一个 key 同时保留轮询能力，不会和 webhook 冲突
推荐拆分方式
建议至少按下面方式拆分：
- 测试环境一个 key
- 正式环境一个 key
- 如果有多租户或多客户，再按客户拆 key
API Key 和会话能力的关系
当前对外 API Key 主要服务于这些能力：
- 图片任务
- 视频任务
- 任务查询
- OpenAI 兼容文本接口
- webhook 回调
当前不建议把“前端内部持久化会话”直接作为外部 API Key 的主承诺能力。
当前建议
- 测试环境单独建 key
- 正式环境单独建 key
- 每个 key 使用独立
webhook_secret - 不同业务线尽量不要共用同一个正式 key