本页面向 FrameAI 平台开发、运维与产品负责人，用于把现有用户客户端与服务间调用能力演进为真正可对外发布的 Open API。开放 API 不是把现有 Gateway 路由直接暴露到公网，而是建立独立的公开入口、身份、权限、计量、审计与版本管理层。

规划中

架构边界

第三方服务
  -> Open API Gateway (/open/v1)
  -> 应用认证 / 作用域 / 限流 / 幂等 / 审计
  -> 用户、资产、生成、计费等业务服务
  -> 异步任务与 Webhook 投递器

边界	实施要求
公共路由	仅发布版本化 /open/v1 合同；内部 /api、健康检查、管理和服务间入口不对合作方开放。
身份隔离	Open API Key 与用户登录令牌、运营后台 Token、服务间 X-Service-Token 相互独立，不能复用。
资源隔离	每次请求解析到开发者应用、工作空间和作用域；任务、资产与结果查询必须进行归属校验。
计费隔离	在任务受理前锁定额度并记录应用、工作空间、任务和幂等键；终态再完成结算和对账。
回调隔离	Webhook 投递由受控工作器完成，限制目标域名、超时、重试和响应体，不允许由调用方控制任意内网地址。

分阶段上线

阶段	交付内容	完成标准
0. 合同冻结	OpenAPI 文档、错误码、模型能力矩阵、额度和计费规则。	合作方可基于沙箱合同完成 Mock 联调。
1. 开发者身份	应用、环境、API Key、作用域、IP 允许列表、轮换与撤销。	密钥只展示一次，审计可追溯到应用与操作者。
2. 沙箱任务链路	模型查询、受限上传、视频任务创建、查询与取消。	幂等请求、错误码、资源归属和额度校验覆盖自动化测试。
3. Webhook	事件投递、签名、重试、投递日志与回放。	合作方能验签、去重并通过查询补偿丢失事件。
4. 生产公测	配额、告警、支持流程、变更公告和 SLA 范围。	通过压测、异常演练、计费对账和安全评审。

数据与控制面

开发者控制台至少需要以下对象：

对象	核心字段	关键约束
Developer App	名称、所属工作空间、环境、状态、联系人。	应用停用后立即拒绝新请求。
API Key	前缀、密钥哈希、作用域、过期时间、最后使用时间。	不存储或回显明文；支持轮换与撤销。
Webhook Endpoint	HTTPS 地址、域名状态、签名密钥版本、事件订阅。	拒绝内网地址、重定向绕过和未验证域名。
Usage Record	应用、工作空间、请求 ID、任务 ID、计费项、结果。	支持幂等对账与可审计追溯。
Delivery Log	事件 ID、投递时间、尝试次数、HTTP 结果、终态。	不记录密钥或完整敏感响应体。

网关与服务实现要求

1. 在 Gateway 中建立独立 Open API 路由表和认证中间件，不将外部 Authorization 原样传递给内部服务。
2. 验证 API Key 后生成受控的调用上下文，向下游传递应用 ID、工作空间 ID、作用域、请求 ID 和可审计身份。
3. 为创建型请求持久化 Idempotency-Key 与规范化请求摘要；相同键的同请求返回原结果，不同请求返回 409。
4. 在服务层再次校验工作空间归属、模型授权、资产访问和额度，网关校验不能作为唯一防线。
5. 将上传改为短期受限凭据或代理上传；结果资源使用短期签名 URL，禁止暴露内部文件路径和永久公网地址。
6. Webhook 投递器执行 DNS/IP 风险校验、连接与总耗时限制、重试退避、签名和投递审计。
7. 将限流、并发、日额度、成本预估和余额不足纳入统一响应，返回稳定业务错误码。

发布验收

• OpenAPI 定义与实现、SDK 示例和开发者文档由同一版本流水线生成或校验。
• API Key、用户登录态、运营后台 Token 和服务间令牌相互隔离，渗透与单测均覆盖跨身份访问失败。
• 所有资源查询按应用、工作空间和作用域校验，不能通过猜测 ID 读取其他租户数据。
• 重复请求、网络超时、回调重复、回调失败、余额不足和渠道失败都有稳定结果与审计记录。
• 计费预占、终态结算、退款/返还和 Usage Record 可对账。
• 生产部署具备 TLS、WAF/网关限流、日志脱敏、指标告警、密钥轮换和回滚方案。
• 公测前完成负载测试、故障演练和至少一个合作方的端到端验收。

开放 API 正式发布后，应把本页中“规划中”的端点替换为具体版本、上线日期、变更日志和可下载的 OpenAPI 定义。

上一页Webhook 与安全

下一页案例学习地图