公共 API 执行架构

https://api.oceanway.tech/v1 是 OceanWay 唯一面向客户程序的公共 API 根地址。ai.oceanway.tech 只负责公开模型发现、文档、价格和状态；全部登录后管理与 Playground 位于 console.oceanway.tech/ai。API Edge 独立于两类网页入口，并明确拒绝 Customer Session。

正式边界

Text Gateway 与 Media Gateway 同级、互不级联，均为 OceanWay 私有基础设施。客户只能看到公开模型 ID、OceanWay Run、标准状态、用量、输出和脱敏错误。

入口与域名规则

• 正式根地址固定为 https://api.oceanway.tech/v1；
• Developer Center、Console Playground、文档和 SDK 示例只使用该地址；
• ai.oceanway.tech 不接受生产 /v1 调用；
• console.oceanway.tech 不直接承载 /v1，Playground 由 Console BFF 服务端调用 API Edge；
• canvas.oceanway.tech 和 oceanway.tech 不接受 Developer Credential；
• API Edge 不读取 Customer Session Cookie，不进行网页登录，也不返回 HTML 登录跳转；
• 私有网关只在受控网络和服务身份下可达，不配置公网客户 DNS；
• API 版本表示 OceanWay 公共契约版本，不跟随 Provider 或网关内部版本。

目标资源面

具体兼容路径可以按已发布协议增加别名，但所有别名必须归一到同一个 Execution Command，不能建立多套账务或任务事实。

可接受的执行授权

API Edge 只接受机器可验证、Audience 明确的执行授权：

当前允许列表只有上述两项。未来 OAuth 或客户侧短期 Token 必须先由独立 ADR 明确，并作为 DeveloperCredential 的协议类型演进，不能未经决策成为第三类 Edge Principal 或认证分支。

Customer Session、父域 Cookie、浏览器登录态和 Admin Workforce Session 均不是 Public API 执行凭据。API Edge 必须在读取请求 Body 或创建 Run 前拒绝错误 Audience。

Developer Credential 不应嵌入浏览器、公开移动端包或前端仓库。浏览器中的 Playground 也不能要求用户粘贴或读取长期 Key。

请求身份与上下文

Public API Edge 从 Developer Credential 或短期 Grant 解析不可变执行上下文：

actorPrincipalId
executionPrincipalId = serviceAccountId
authenticationType = developer_credential | playground_grant
developerCredentialId? / playgroundExecutionGrantId?（严格二选一）
developerAppId
environmentId
organizationId / personalSpaceId
workspaceId / projectId?
billingAccountId
scopes / policy bindings

正式 API 请求的业务 Actor 与执行主体都是 Service Account，并携带 developerCredentialId；Playground 的业务 Actor 是 Customer User，执行主体仍是目标 Service Account，并携带 playgroundExecutionGrantId。两种认证引用必须严格二选一。客户可以在允许范围内选择 Project 或请求标签，但不能通过 Header 覆盖 Owner、付款方、App 或 Environment。Developer Key 只在 Edge 鉴权，绝不进入 Execution Manifest 的 Secret 字段，也不转发给私有网关。Grant 只授权一次或一组受限执行，不能调用 Developer Access Command；Console BFF 的 Workload Principal 只进入服务调用审计。

标识符

每次请求使用职责明确的稳定标识：

客户响应始终返回 OceanWay requestId；异步创建同时返回 runId。支持团队通过内部运维读模型关联 Gateway Observation，但不能要求客户提供 Provider Task ID。

统一执行链路

执行前必须冻结：业务 Actor、Service Account 执行主体、严格二选一的 Developer Credential 或 Playground Execution Grant、Owner、App、Environment、Workspace/Project、Offering Revision、能力契约、执行池、价格快照、预占、输入 Asset Revision、数据策略和幂等身份。

Provider Credential、物理 Channel、Supply、Provider Model ID、供应商零售价和完整内部 Prompt 不进入客户响应或业务授权对象。

Console Playground 链路

Playground 复用相同 Public API、Offering、Run、Meter 和 Billing 语义，但不向浏览器暴露长期 Credential：

Grant 的有效期、使用次数和请求范围来自正式 Policy，不写死在前端。它只由 Console BFF 服务端持有和使用，不能进入浏览器 JavaScript、URL、本地存储或客户端日志，也不能退化为长期 API Key。

Playground Run 固定 source=playground、Customer User Actor、App、Environment 和目标 Service Account，因此可以进入 API Usage 与 Logs，但不会获得 Developer Access Domain 的管理权限。

模型解析与 Surface

1. Public API 根据公开 model 查找 Model Offering。
2. Offering 必须启用、发布到 api Surface、处于可调用生命周期，并满足当前主体的授权和数据策略。
3. 系统冻结不可变 Offering Revision 与价格快照。
4. Offering 的 executionPool 决定进入 Text 或 Media Pool。
5. Execution Control 选择 Gateway Deployment；私有网关再选择自己的 Channel 或 Supply。

web 和 internal 不是 api 的隐式候选。codex-auto-review 等 internal-only 模型即使存在于网关目录，也必须对 /v1/models 和执行接口返回不可用。

同步、流式与异步

同步

短时请求可以在一个连接中返回终态。同步只是交付方式，不绕过 Run、Attempt、Quote、Reservation、Usage 和审计。

流式

流式文本由 Text Gateway 返回标准事件，Public API 只输出 OceanWay 允许的字段。首个业务字节发送后，不得静默切换模型并重新生成。断流后只有在上游提供可证明安全的恢复语义时才能续传，否则保留已知 Usage 并进入明确终态或对账。

异步

媒体和其他长任务先返回 runId 与稳定状态。关闭页面、客户端超时或查询重试不能触发第二次 Provider 提交。客户查询 OceanWay Run，不直接查询 Media Gateway Task。

POST media request
→ validate and reserve
→ create OceanWay Run / Attempt
→ idempotently create Media Gateway Task
→ return runId
→ Gateway Poller / Reconciler reaches terminal fact
→ import output and register Asset when policy requires
→ settle or release
→ expose terminal OceanWay Run

公共状态机

HTTP 202 Accepted 不是成功终态，不能立即结算。Provider 返回成功也不等于 OceanWay Run 成功；正式输出登记和账务终态完成后才进入 succeeded。

幂等与重试

• 创建类请求要求或强烈建议携带 Idempotency-Key；
• 去重范围至少包含 Service Account、Environment、操作类型和规范化请求指纹；
• 相同 Key 与相同指纹返回原 Run 或原结果，不再次调用 Provider，也不重复计费；
• 相同 Key 与不同指纹返回稳定冲突错误；
• 网络超时、客户端重连和 Webhook 重放不得创建新 Run；
• 用户在可解释终态后显式“再次执行”使用新的幂等身份和新的 Execution Attempt；
• unknown/reconciliation_required 未处置前禁止自动换网关或 Supply 重新提交。

双网关执行

Text Gateway Pool

UUMI/new-api 负责文本、Embedding、Rerank、物理 Channel、Provider 协议、流式传输、Token Usage 和供应成本。OceanWay 只保存 Gateway Invocation 摘要和标准 Usage，不读取网关数据库拼装未契约化事实。

Media Gateway Pool

oceanway-media-gateway 负责图像/视频 Provider 接入、Supply、Credential Version、Task/Provider Attempt、Dispatcher、Poller、Reconciler 和 Result Handling。OceanWay 保存不透明 gatewayTaskId，不复制 Provider Attempt 细节。

两个池不得互相调用，也不得在运行中静默跨池降级。OceanWay 根据已冻结 Offering Revision 选择池；网关内部只根据供应能力、健康、容量和成本执行，不读取客户钱包或零售价。

结果与 Asset

文本结果可以作为 Run Output 保存必要的客户可见内容和 Usage。媒体结果先进入 Gateway 暂存，再由 OceanWay：

1. 使用短期授权读取结果；
2. 校验内容类型、大小、哈希、尺寸/时长和安全策略；
3. 写入 OceanWay 对象存储；
4. 登记 AssetVersion、来源与 generated_by 血缘；
5. 绑定 Run Output；
6. 完成结算后对客户发布稳定结果。

Gateway 临时 URL 不能成为正式 Asset URL。API 媒体是否默认登记 Asset 由产品策略决定，但任一模式都必须保留可解释的 Run、输出保留期和账务证据。

计量与计费

Offering Revision + Customer Contract
→ Quote
→ Reservation
→ Meter Event / valid output
→ Settlement | Release | Refund | Reconciliation

• 用户价格只来自 OceanWay Rate Card 和合同快照；
• Provider Usage 与 Cost Fact 只用于供应核对和毛利分析；
• queued/running/output_pending 保持预占，不提前结算；
• 同一 executionAttemptId + chargeType 只能有一次有效结算；
• 异步 Poll、重复 Gateway Observation 和 Webhook 重放不能重复扣费；
• Developer App、Environment、Service Account、DeveloperCredential 和 Playground Policy 可以设预算或限额，但不拥有独立钱包。

Webhook

客户 Webhook 由 OceanWay Developer Platform 发送，并在 Console AI 专业空间配置，不由 Developer Center 或私有 Gateway 直接发送。事件至少包含稳定事件 ID、schema version、occurred time、App/Environment、runId、公开状态和受控结果引用。

• 每个投递 Attempt 独立记录，事件本身保持不变；
• 使用 Environment 的版本化签名 Secret；
• 重放原事件不创建新 Run 或新结算；
• 投递失败不回退已经确认的 Run 终态；
• Provider Callback 是 Media Gateway 内部实现细节，与客户 Webhook 分离。

错误与隐私

公共错误包含稳定 code、可操作信息、requestId、必要的字段定位和是否可重试提示。以下内容必须移除或映射：Provider Secret、内部 URL、Channel/Supply、上游模型 ID、原始堆栈、完整内部 Prompt、未经审查的 Provider 错误和其他租户信息。

限流、预算不足、权限不足、模型不可用、参数无效、提交不确定和内部故障必须使用不同错误代码；不能把所有问题都返回为普通 gateway_error。

当前实现基线

当前 /v1/[...path] 已支持 Developer Key 鉴权、api Surface 检查、逻辑模型改写、幂等相关 Header、同步/流式代理和基础计费。模型查询以及文本、图片、音频、视频创建已有入口。

主要差距：

• /v1 在多个站点 Host 放行，尚未固定到 api.oceanway.tech；
• 当前网页管理页面位于 Developer Portal，尚未迁入 Console AI；
• Key 仍直接绑定 User，无法解析 App/Environment/Service Account；
• 请求直接解析本地 Channel 和上游模型，没有统一 Run/Attempt/Gateway Binding；
• 公开 GET 只支持 Models，异步 Run 查询、内容读取和取消尚未开放；
• 任意上游成功响应都可能立即结算，202 Accepted 没有保持预占；
• 图片和视频仍可经本地系统渠道直接调用 Provider，尚未接入 Media Gateway；
• 当前幂等冲突不会稳定返回原 Run/结果；
• 尚无 Playground 专用的短期受限 Grant，现有长期 Key 回显模型不能用于浏览器测试。

目标状态

目标态中，所有机器流量只到 api.oceanway.tech/v1；每个请求都来自 Developer Credential 或受限 Execution Grant，并归属明确 App/Environment 和不可变 Execution Manifest；同步、流式和异步共用 Run/Attempt/计费链路；能力明确分发到同级私有 Text/Media Gateway；客户始终只看到 OceanWay 契约。

实施阶段

验收标准

1. api.oceanway.tech/v1 是唯一正式机器入口，Developer Center、Console 和 Canvas Host 不接受生产 /v1。
2. API Key 可唯一解析到 Service Account、Environment、App、Owner 和 Billing Account。
3. web 或 internal 独占模型不能通过 /v1/models 或执行接口访问。
4. 相同幂等键和请求返回同一 Run；不同请求复用同一键返回冲突，均不重复扣费。
5. 202 Accepted 后保持预占，只有输出与账务终态完成才标记成功并结算。
6. 客户断线、Worker 重启、重复 Poll 和 Webhook 重放不会造成第二次 Provider 提交。
7. 文本流式走 Text Gateway；图片/视频走 Media Gateway；两个池不级联。
8. 客户响应、Developer Center 和 Console 客户日志不含 Gateway 地址、Provider Credential、Channel、Supply 或上游任务 ID。
9. 确定失败释放或退款；未知事实进入 reconciliation_required，不得自动重试。
10. API Run、Usage、Ledger、Asset 和 Audit 能通过内部 ID 完整关联。
11. Customer Session 请求 API Edge 时在执行前被拒绝，不创建 Run 或预占。
12. Playground 网络与浏览器存储中没有长期 Developer Key，Grant 不能调用四层资源管理接口。

延伸阅读

• 调度、执行与模型网关池
• 应用、服务身份与凭据
• 钱包与商业系统
• 共享内核与资源图