PLAT-02-014 接口
平台对外提供的三类接口
平台的接口分三类，面向不同的调用方。
| 类型 | 调用方 | 来源 | 状态 |
|---|---|---|---|
| 公共模型 API | 开发者 | 基于 new-api 的正式平台中转 | 按实际发布模型/协议及具名验证开放 |
| 平台业务 API | Console、Admin 前端 | 迁入平台的正式身份、账务及商业接口 | 已有实现，完整范围按T-04～T-13适用任务验收 |
| 产品集成 API | 产品工程后端 | 受限产品委托接口 | 身份、Chat、原操作、记录/摘要及订阅已有正式路由；Studio按切片交接 |
公共模型 API
开发者用 API Key 调用。文本路径和格式与 OpenAI、Anthropic、Gemini 官方一致，沿用对应 SDK；2026-10-07起每个文本模型仅提供一个渠道，暂时搁置同名多版本及协议选择扩展。图片/视频采用平台内部自定义协议，客户端创建、原请求/任务查询和结果读取契约另行定义；内部协议与网关适配协议分开，正式源在平台仓库docs/openapi/，未验收执行入口保持关闭。
| 能力 | 路径（new-api 原有） |
|---|---|
| OpenAI Chat Completions | POST /v1/chat/completions |
| OpenAI Responses | POST /v1/responses |
| Anthropic Messages | POST /v1/messages |
| Gemini 原生 | POST /v1beta/models/{model}:generateContent 及流式版本 |
| 模型列表 | GET /v1/models |
| 视频任务 | 平台内部自定义创建/查询/结果协议，后端适配媒体网关；次/秒/token等适用计量与具体契约待T-06/G-07验证 |
| 图片生成与编辑（候选） | 平台内部自定义协议，支持适用次/张/秒/token计量；/v1/images/generations、/v1/images/edits仅为原生/上游适配候选，供应链路和客户端契约待验证，不代表首发开放 |
| 音频（候选） | POST /v1/audio/speech、POST /v1/audio/transcriptions；其他能力按实际需求审计后确定 |
具体开放路径以实际发布目录、部署版本与具名验证组合为准；最新Responses及历史其他协议范围见证据索引。当前Chat原body工作树调整另行交接，不把已列路径或Responses分项视作其他协议/旧客户端全部开放。
平台业务 API
Console 和 Admin 调用正式 /api/platform/v1/* 平台接口，身份入口沿平台注册的 /api/platform/v1/auth/* 契约；原生兼容路由是否开放由正式模式注册决定，不能据原版端点存在绕过身份或账务。各页面使用的接口见 Console 和 Admin。
平台业务职责包括以下范围，当前交付状态按相应任务及验收证据跟踪：
- 使用记录增加“来源产品”字段和按产品筛选。
- 一期个人标准模型价格、版本与报价预览；企业协议价和客户方案绑定二期。
- 积分换算改为人民币规则（订阅、充值）。
- 平台角色与产品角色的分配和查询。
产品集成 API
供 oceanway-studio 等产品后端调用。身份、受限 Chat、原操作、记录/业务事件及产品订阅已有正式实现；具体动作、字段与错误以平台 docs/openapi/platform.json 和实际注册路由核对。Studio 最新接入顺序见首批改造范围与交接点。
| 接口 | 用途 |
|---|---|
| 身份查询 | 产品转来用户的会话 Cookie，平台返回用户 ID、状态和角色 |
| 权限查询 | 查询用户是否拥有某个产品角色，如 studio:admin |
| 代用户调用模型 | 产品服务凭据＋本人平台Cookie/Origin调用受限产品中转接口，使用记录按可信产品归属；不单凭服务Key调用任意用户 |
| 预留、结算、释放 | 非模型扣费，带幂等键，见钱包与计费 |
| 操作状态与恢复查询 | 按 operation_id 查询授权、资金状态和关联任务；未知结果复用原操作 |
| 客户任务及结果访问 | 校验用户、产品与任务归属后返回客户可用的结果，隐藏供应凭据和内部任务身份 |
正式产品服务凭据为 Header X-Platform-Product-Key: key_id.secret，绑定一个产品、动作及Origin并独立撤销；新调用另核本人平台Cookie/Origin，Worker只按已持久授权的原操作恢复。精确规则见身份与权限的现行产品服务凭据；格式已确定，实际产品配置/部署与各切片联验继续跟踪。
契约必须声明的字段与行为
- 操作身份、可信用户与产品来源、业务任务身份、动作、请求指纹、计量单位与精度；字段名以实现时的 OpenAPI 为准。
- 用户和产品从已验证会话、受限委托或原操作推导，不能任意传入。服务凭据的作用域与后台操作的授权依据分别说明。
- 同键同请求的原结果、同键不同请求的
409、余额不足、无权限、待核对、终态冲突和可恢复错误。 - 预留价格快照、执行开始确认、查询及结算/释放的状态转换，避免执行与到期释放竞态。
- 服务端任务及账务状态可以分别查询；不能把 HTTP 成功、任务成功、媒体已持久保存和资金已结算视为同一状态。
上述契约要求仍有效，不能将已有路由一概列为未实现。当前产品新调用为 /api/platform/v1/relay/chat/completions；真实已验的 Responses 开发者入口不代验产品 Responses 委托。已知原操作的 /operations/:id/relay/result 与后台 reconcile 已有实现；原 operation 全丢定位、新版多协议/流式原结果 OpenAPI/DTO/HTTP 对齐、产品媒体委托等按对应任务交接。原版、中间扩展、正式实现和已部署范围分别记录，见平台集成验证。
文档与规范
接口说明以平台仓库中的 OpenAPI 文件为契约源，并校验与正式源码一致；已发现漂移须具名修正和验收。对外开发者文档按 D-API-DOCS-SEPARATE 由独立接入文档站承接，Console 保留实际接入示例。本页只记录接口分类及产品交接边界。
图片/视频内部任务接口（2026-10-07）
T-06/07/08、PL-006/013/014新增客户内部媒体任务契约，正式源为平台docs/openapi/platform-media.fragment.json，已合入platform.json。文本仍使用标准协议及一个精确模型名、一个渠道。
开发者使用/v1/platform/media/tasks，浏览器使用/api/platform/v1/media/tasks并携带本人Key ID及新鲜会话。POST创建、GET本地状态、按原request_id找回关联、显式POST /{id}/refresh查询原网关任务及恢复原结算、GET /{id}/outputs/{index}读取受控结果。GET状态不提交生成、不执行结算。客户传发布规格及用量预算、当前公开价格版本；实际用量及费用不由客户上报。已创建操作后的错误保留原请求，查询404也不证明可以重新生成；只有服务端明确的request_not_created预检拒绝可回到草稿。
当前完成本地私有夹具协议及资金验证，生产媒体执行仍关闭。现网关OpenAI接口仅按返回的原任务ID查询，其响应时长来自请求规格，尚无可信实际用量/无扣费失败回执，也无按平台操作号找回任务的接口；不能把24小时提交幂等窗口当作未知请求重发许可。图片供给仍待审计。新增客户契约不表示产品委托接口、真实供应计量或生产发布全部通过，分项证据见平台docs/verification/T-06/media-protocol-20261007.md。