历史 · 公共 API 执行架构

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

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 明确的执行授权：

目标允许列表只有上述两项；当前独立 API Edge 只实现 Developer Credential，Playground Execution Grant 尚未实现，且 Public Admission 仍为 disabled。未来 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
authentication =
  { kind=developer_credential; developerAppId; environmentId; serviceAccountId; developerCredentialId }
  | { kind=playground_execution_grant; developerAppId; environmentId; serviceAccountId;
      playgroundExecutionGrantId; playgroundExecutionGrantSchemaVersion;
      playgroundExecutionGrantClaimsDigestAlgorithmVersion; playgroundExecutionGrantClaimsDigest }
tenantKind / tenantId
workspaceId / projectId?
billingAccountId
source = { surface=developer_api|developer_playground; apiVersion; operation }
product = developer_api | developer_playground
authorizationDecisionId / authorizationDecisionSchemaVersion
authorizationDecisionInputDigestAlgorithmVersion / authorizationDecisionInputDigest
authorizationEvidenceEvaluationSetRef / authorizationEvidenceEvaluationSetSchemaVersion
authorizationEvidenceEvaluationSetDigestAlgorithmVersion / authorizationEvidenceEvaluationSetDigest
authorizationEvidenceArchiveCutRevision
authorizationEvidenceEvaluationCount
authorizationEvidenceEvaluations[] = sorted {
  evidenceKind;
  authorizationEvidenceEvaluationRef / authorizationEvidenceEvaluationSchemaVersion;
  authorizationEvidenceEvaluationDigestAlgorithmVersion / authorizationEvidenceEvaluationDigest;
  archiveRevision
}
executionAuthorization = {
  authorizationScopeSnapshotRef / authorizationScopeSnapshotSchemaVersion
  authorizationScopeSnapshotDigestAlgorithmVersion / authorizationScopeSnapshotDigest
  allowedAssetVersionRefs[] / allowedModelOfferingRevisionIds[] / allowedToolVersionRefs[]
  authorizationActionIds[]=sorted
  authorizationActionCount
}
policyBindingRevisionIds[]=sorted

正式 API 请求满足 actorPrincipalId == executionPrincipalId == serviceAccountPrincipalId，三者中的 Principal ID指向该 Service Account的 Principal；它们绝不与资源命名空间中的 authentication.serviceAccountId做字符串相等比较。Playground的 Actor是 Customer User Principal，Execution Principal仍是目标 Service Account Principal，并使用精确字面量 authentication.kind=playground_execution_grant。Core必须通过受信 Identity/Developer Access绑定验证 authentication.serviceAccountId → serviceAccountPrincipalId，错绑即拒绝。authentication是严格嵌套判别联合：App、Environment、Service Account与对应 Credential/Grant证据都在所选分支内，另一分支字段必须拒绝；Playground Grant的 ID/Schema/Claims Digest与 Authorization Decision的 ID/Schema/Input Digest都必须和不可变 Authorization Evidence Archive相等，不能改写成扁平 authenticationType或简称 playground_grant。准入时 Core为同一 Operation一次提交该 Authentication分支的完整期望证据集合，以及 executionAuthorization.authorizationScopeSnapshot* + authorizationActionIds[] + authorizationActionCount；Count必须等于Action数组排序去重后的长度、参与摘要且不能替代成员。Archive在单一可串行化 Revision Fence中用服务端时间和统一 Cut签发内容寻址 AuthorizationEvidenceEvaluationSet@1。正式 API的 Set只有 Authorization Decision，Playground则恰好包含 Authorization Decision与 Playground Grant；Run上下文同时保存 Set四元组、统一 Archive Cut、Scope Snapshot完整四元组、Action Count、排序去重 Action集合和成员四元组。Set、Run上下文、后续 RunAdmissionManifest.executionAuthorization与 run.created@2.0对 Scope/Action Count/Action成员必须逐项相等；缺失/错误Count、重复Action或宽泛 Scope标签都不能隐式替代规范 Action ID。调用方不能传历史评估时间、逐条取得结果后拼接，也不能把不同 Cut的成员组合为 Valid。历史重放以冻结 Set/Scope/Action读取，再读取其成员，不按当前撤销状态重算。source.surface == product，正式 API固定为 developer_api，Playground固定为 developer_playground。tenantKind + tenantId只能取 organization + OrganizationId或 personal_space + PersonalSpaceId；个人调用不得伪造 Organization。客户可以在允许范围内选择 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.surface=developer_playground、product=developer_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. 系统将 modelOfferingRevisionId、pricingSnapshotId、billingPolicyRevisionId、modelRoutingPolicyRevisionId 与准入时的 initial modelDeploymentId 冻结到不可变 RunAdmissionManifest@N。Run 上的 executionManifestRef / executionManifestSchemaVersion 专门指向该准入清单，不指向 Attempt 或网关私有路由快照；历史 Eligibility 只使用这里冻结的 Billing Policy Revision。
4. Offering 的 gatewayPool 决定进入 Text 或 Media Pool。
5. Execution Control 为每个 Attempt 生成独立的 AttemptExecutionManifest@N 并冻结实际 Gateway Deployment；私有网关在任何 Provider Side Effect前以完整 Attempt Manifest四元组调用 Execution Owner的 readAttemptExecutionManifest，验证期望 Run/Step/Attempt、Model/Gateway Deployment、Pool、Run Manifest/Output Contract与精确 Workload Audience。验证通过后才原子创建 GatewayRouteSnapshot@N + AttemptRouteBinding@N，并在创建/查询响应中返回两者完整 Ref/Schema Version/Digest Algorithm Version/Digest四元组。Execution必须先 append-only保存这两个四元组，之后才能消费结果或把 Binding/Route/Evidence完整四元组交给 Metering；Route四元组不写回不可变 Attempt Manifest。重试只能在准入时已冻结的路由策略版本允许时创建新 Attempt并选择新 Deployment，不得改写 RunAdmissionManifest。

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。

幂等与重试

• 所有会创建 Run、Reservation、Gateway Task/Invocation 或其他外部副作用的 Public API Command 都强制携带符合 Contracts 语法的 Idempotency-Key；缺失或非法 Header 必须在产生任何业务副作用前拒绝；
• 当前单认证受控基线的去重范围包含 Organization、Execution Principal、Service Account、Environment、操作类型和规范化请求指纹，且只允许 developer_credential；启用 Playground 或其他多 Actor Surface 前必须使用新的版本化范围，严格加入 Tenant Kind/ID、Authentication Kind、Product、Actor Principal、Execution Principal、App、Environment、Service Account 与操作，不能只按共享 Service Account 去重；
• 相同 Key 与相同指纹返回原 Run 或原结果，不再次调用 Provider，也不重复计费；
• 相同 Key 与不同指纹返回稳定冲突错误；
• 网络超时、客户端重连和 Webhook 重放不得创建新 Run；
• 同一逻辑请求的网络/客户端/服务端恢复必须复用原 Key；用户在可解释终态后主动“再次执行”使用新的 Key、Operation 与 Execution Attempt；
• 只读 GET 不要求该 Header；其他不会创建 Run 的写命令必须在各自 Contracts 中明确幂等身份，不能据此把创建命令降级为可选；
• unknown/reconciliation_required 未处置前禁止自动换网关或 Supply 重新提交。

OpenAPI 必须把上述创建端点的 Header 标为 required: true，Contracts 与端到端测试覆盖缺失/空白/非法 Key、同 Key 同指纹重放、同 Key 异指纹冲突，以及超时后复用原 Key不会产生第二个 Run、Reservation 或 Provider 提交。多 Actor 版本还必须覆盖 API↔Playground 和两个不同 Customer Actor 共用同一 Service Account/Key/请求的并发隔离、跨 Tenant/Product/Authentication 隔离，以及 Credential 轮换后同一稳定 Actor 的合法重放。

双网关执行

Text Gateway Pool

UUMI/new-api 负责文本、Embedding、Rerank、物理 Channel、Provider 协议、流式传输，以及供应商响应形成的不可变 ProviderUsageEvidence / ProviderCostEvidence。Gateway Response返回标准状态、Gateway Invocation ID、AttemptRouteBinding/GatewayRouteSnapshot完整四元组、受控结果，以及必填的 usageEvidenceAvailability + costEvidenceAvailability严格判别联合；只有 state=available分支携带相应 Evidence完整四元组，不返回 Evidence Payload或规范 Fact。OceanWay不读取网关数据库拼装未契约化事实，规范 MeterEvent / ProviderCostFact只由 Metering生成。

Media Gateway Pool

oceanway-media-gateway 负责图像/视频 Provider接入、Supply、Credential Version、Task/Provider Attempt、Dispatcher、Poller、Reconciler和 Result Handling。创建/查询响应返回标准状态、gatewayTaskId、AttemptRouteBinding/GatewayRouteSnapshot完整四元组、受控结果，以及与 Text Pool完全相同的两类严格 Evidence Availability；只有 available分支携带 Evidence完整四元组。OceanWay append-only保存 Task与 Binding/Route四元组，不复制 Provider Attempt细节。

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

结果与 Asset

文本结果可以作为 Run Output 保存必要的客户可见内容；Provider Usage/Cost 只以 Gateway Evidence 引用进入 Metering。媒体结果先进入 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
→ Execution/Output Eligibility + Usage Evidence + Policy
→ eligible canonical MeterEvent + frozen Billing Policy/Price
→ Settlement | Release | Refund | Reconciliation

• 用户价格只来自 OceanWay Rate Card 和合同快照；
• Gateway Provider Usage/Cost 只形成 Evidence；Metering 是规范 MeterEvent / ProviderCostFact 的唯一 Writer，并负责规范化、幂等、更正与对账；
• ProviderCostFact 只用于供应核对、成本归集和毛利分析，Operational Observation 只能引用 Evidence，二者都不能单独驱动客户结算；
• queued/running/output_pending 保持预占，不提前结算；
• 同一 billingReservationId + executionAttemptId + chargeDimensionKey 只允许一笔 Base Settlement，并校验首个 Head 冻结的 chargeType + chargeTypeRegistryVersion + unit；终局后的 MeterEvent 更正必须经每维 BillingSettlementDimensionState 的 From Revision/Head/Amount → 完整、无缺口、无分叉的 Settlement Input Lineage → Current累计Head/Target CAS。若多个中间Head在Billing处理前已被更高Current超越，可以验证完整前驱链后按最新累计Target一次追平；零/负差额才可幂等无账或退款并推进，正差额形成 Billing-owned LateSettlementExposure，再异步关联 Operations Reconciliation Case；不能让并发 Head 从同一已结金额重复退款，也不能重做 Base；
• 异步 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。

遗留 oceanway-vozeb 实现基线

以下能力只描述旧 oceanway-vozeb 单体中的 /v1/[...path]，不是独立 oceanway-api-edge 当前已验收能力，也不能作为 api.oceanway.tech 已上线声明。遗留路由已支持 Developer Key 鉴权、api Surface 检查、逻辑模型改写、幂等相关 Header、同步/流式代理和基础计费；模型查询以及文本、图片、音频、视频创建已有入口。

独立 API Edge 的当前真实基线仅是受控 POST /v1/responses 到 Core 的 Organization-backed Admission、Run 和 credits Reservation，且 PUBLIC_ADMISSION_MODE=disabled；没有 Gateway 执行、输出、Metering、Settlement 或公网开放。下列差距用于迁移遗留实现，不能把旧入口能力叠加到新 Edge 的完成状态。

主要差距：

• /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 没有保持预占；
• 尚未建立 Gateway Evidence → Metering 规范 Fact 的唯一 Writer 链路，旧 Usage/Cost 字段不能被视为已验收的 MeterEvent / ProviderCostFact；
• 图片和视频仍可经本地系统渠道直接调用 Provider，尚未接入 Media Gateway；
• 当前幂等冲突不会稳定返回原 Run/结果；
• 尚无 Playground 专用的短期受限 Grant，现有长期 Key 回显模型不能用于浏览器测试。

目标状态

目标态中，所有机器流量只到 api.oceanway.tech/v1；每个请求都来自 Developer Credential 或受限 Execution Grant，并归属明确 App/Environment、不可变 RunAdmissionManifest 与每次 Attempt 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 后保持预占；只有正式 Output 与账务终态均完成才把 Run 标记为 succeeded。Settlement Eligibility 独立按版本化 Billing Policy、合格 canonical MeterEvent 与冻结价格判定，不能用 Run 成功状态替代计费事实。
6. 客户断线、Worker 重启、重复 Poll 和 Webhook 重放不会造成第二次 Provider 提交。
7. 文本流式走 Text Gateway；图片/视频走 Media Gateway；两个池不级联。
8. 客户响应、Developer Center 和 Console 客户日志不含 Gateway 地址、Provider Credential、Channel、Supply 或上游任务 ID。
9. 确定未提交，或失败/取消且无符合版本化 Billing Policy 的 canonical MeterEvent 时，也只有 BillingFinalizationDecision 证明完整 Attempt×Charge Dimension 集合封闭后才释放；已有合格结算事实的补偿使用追加式退款/调整。未知事实进入 reconciliation_required，ProviderCostFact 不单独触发客户账务。
10. API Run、Usage、Ledger、Asset 和 Audit 能通过内部 ID 完整关联。
11. Customer Session 请求 API Edge 时在执行前被拒绝，不创建 Run 或预占。
12. Playground 网络与浏览器存储中没有长期 Developer Key，Grant 不能调用四层资源管理接口。
13. Gateway 只能写不可变 Provider Evidence；只有 Metering 能追加规范 MeterEvent / ProviderCostFact，Observation、Poll 与 Callback 均不能直接结算。

延伸阅读

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