模型能力接口实施合同（逐项上线）
本页描述已确认的目标，不代表端点已经上线。 每项功能会经过实现、能力测试、计费与真实渠道验收后单独标记可用。当前可调用范围仍以模型网关 API为准；下表中的「拟新增」路径不能用于现网调用。
要解决的问题
工作流文档选择的是任务和模型，不应要求用户理解服务商协议。只要模型在该任务的可选列表中，平台就必须能把工作流请求翻译为实际渠道的请求，并把结果翻译回来。渠道不支持某项必需能力时，该模型不能作为该任务的可选项；不能选完模型才因协议不匹配失败，也不能静默忽略用户要求的参数。
这里的「兼容」指平台承诺的公共字段和能力，不等于把任意厂商的全部私有能力都包装成通用能力。每个渠道有自己的请求、响应和流式事件适配器；仅在协议语义确实一致时复用通用适配器。模型上架还必须经过真实调用验收，而非仅凭供应商模型列表或协议声明。
八类能力的基准合同
表中路径以现有 /api/model-gateway/v1 为前缀。除已实现的 Chat 和 ASR 外，路径均为拟新增入口；它们不是现网接口。翻译层内部先归一为 task + model + input + requiredCapabilities，再选择渠道与协议，输出归一后的结果及用量。
| 工作流任务 | 基准规范 | 公共请求最小字段 | 公共结果 / 状态 | 平台入口与状态 |
|---|---|---|---|---|
| 文本、多模态理解与函数工具 | OpenAI Chat Completions | model, messages（文本、图片内容块）, 可选 tools, tool_choice, stream | choices[].message / tool_calls, usage；流式为 delta SSE | POST /chat/completions：已实现部分合同；其他模态和能力逐模型验收 |
| 文本向量 | OpenAI Embeddings | model, input（文本或文本数组）；dimensions 仅在模型支持时可选 | data[].embedding, index, usage | 拟新增 POST /embeddings |
| 重排 | Cohere Rerank v2 | model, query, documents（字符串数组）, 可选 top_n | results[] 按相关性排序，保留原文档 index 与 relevance_score | 拟新增 POST /rerank；唯一基准选 Cohere v2 |
| 图片生成 / 编辑 | OpenAI Images | 生成：model, prompt；编辑：再加输入 image，可选 mask；尺寸、张数等按模型能力开放 | data[] 图片内容或平台托管的图片引用；明确格式与有效期 | 拟新增 POST /images/generations、POST /images/edits |
| 音频转写 ASR | OpenAI Audio Transcriptions | multipart/form-data: model, file；可选 language | 至少 { "text": "..." }；首版仅 JSON | POST /audio/transcriptions：已实现首版，现有限制见网关文档 |
| 语音合成 TTS | OpenAI Audio Speech | model, input, voice；response_format 仅在支持时可选 | 音频字节流及确定的媒体类型 | 拟新增 POST /audio/speech |
| 视频生成 | Google Veo 的异步 Operation | model, prompt；参考图、时长、比例按模型能力开放 | 创建返回作业 ID；查询返回进行中 / 成功 / 失败；成功后取视频文件 | 拟新增 POST /video/generations、GET /video/generations/{id}、GET /video/generations/{id}/content、POST /video/generations/{id}/cancel；采用 Google 的异步任务语义，不是照搬其 URL |
| 实时音视频会话 | OpenAI Realtime 的音频/文本事件；Gemini Live 的视频帧能力面 | 建立会话时指定 model 和输入 / 输出模态；事件含文本、音频、视频帧及结束 / 错误 | 双向 WebSocket 事件流；断线、取消、完成均有明确终态；长会话中途计费与额度检查 | 拟新增 POST /realtime/sessions 和 WS /realtime/ws；视频帧用本项目自有事件扩展，实际接入支持音视频的上游后定细节。WebRTC 属后续独立验收 |
选型例外：OpenAI 的 Videos API 已标记弃用，并计划于 2026-09-24 停用，因此视频改用 Google 的异步 Operation 作为基准。OpenAI 的向量接口只定义文本输入；如果以后要上架跨模态向量（图片 / 音频 / 视频），需单独定义并验收 Google 多模态 Embeddings 扩展，不能把它伪装成已支持的文本向量。聊天中的音频 / 视频理解也不能假称为图片输入；它需要以 Google Interactions 的音视频内容块作为能力扩展，按模型实际支持情况单独验收。
文本协议的边界
Chat Completions 是工作流公共最小合同，不代表后端必须用 Chat 调所有模型。现有后端已能按模型路由 openai-chat、openai-responses、anthropic-messages；OpenAI Responses 的 input / output Items、内置工具和跨轮状态与 Chat 的 messages / choices 不同，Claude Messages 的内容块与工具循环也不同。渠道适配器负责双向转换。需要 Responses / Messages 独有语义且无法无损归一时，应作为显式能力验收，不允许悄悄删除字段或假装执行。
新建工作流中，用户不需要手动切换协议。现网生成块的「高级设置」仍允许选择 auto 或模型声明支持的协议；显式选择会锁定协议并限制跨协议回退。草稿 PR #1446将隐藏新节点的协议入口，按模型与能力自动路由；旧文档已保存的显式协议仍执行原协议，并提供主动切换自动选择的操作。该 PR 尚未合并或上线。Agent 工具循环不是必须手动选 Claude Messages 的理由，Chat、Responses、Messages 各有工具调用方式，具体转换应由渠道适配器完成。
只有实测发现某个协议独有能力无法由现有公共能力合同无损表达、且该能力确实属于特定工作流场景时，才在该场景提供显式协议选择。管理员探针、渠道配置仍可指定协议用于排障；这不应成为普通工作流用户的负担。
与现有文档相比
对照基线是现行模型网关 API；后台的模型协议管理 API管理渠道协议元数据，不是用户可调用的模型入口。
| 项目 | 现有文档 / 实现 | 本方案增加或改变 |
|---|---|---|
| 模型列表 | GET /models 仅列已上架、有计费和可用供应链的文本、视觉、ASR | 保留无参响应；拟增加 ?task=<task> 按任务 + 已验收能力列模型；不能因供应商目录中有模型就暴露在工作流 |
| 文本 / 多模态 | POST /chat/completions；文档描述文本、图片输入、工具和 SSE | 保持现有入口与响应；增加逐模型能力门禁及渠道双向翻译的验收要求；Responses / Messages 是内部可选路由，不自动宣称为公开端点 |
| ASR | POST /audio/transcriptions，仅 JSON，25 MiB 平台上限；个别渠道另有更小上限 | 保持兼容，适配器处理渠道差异；可选模型必须满足该模型实际格式和大小限制 |
| 向量、重排、图片、TTS、视频、实时 | 现有公开模型网关文档没有这些调用入口；项目其他内部功能不等于公开支持 | 新定 6 类任务的最小规范与拟议入口；实现、计费、鉴权和真实调用验收完成后，才能从「草案」移入正式 API 文档 |
| 协议选择 | 现网工作流高级设置有 auto / 支持的协议；显式值会锁定路由 | 草稿 PR #1446拟让新节点自动选择；旧文档保留原锁定值，用户可主动迁移。协议专有能力要显式标记，不把协议切换当成修复不兼容的用户操作 |
定向模型映射与停用
映射是独立基础功能：管理员指定公开模型 key A、目标模型 key B 和精确目标渠道变体，命中 A 的请求实际调用 B 的指定渠道。映射可用于普通服务，也可在弃用模型的设置界面使用；启用映射本身不自动停用或弃用 A。目标失效时明确失败，不能悄悄回落 A 或另一个 B 渠道；禁止自指、链式和循环映射。映射前后的模型身份、价格和扣费口径仍在确认中，定稿前不改变现有收费合同。
渠道停用属于单独生命周期操作：停用后从新选择列表隐藏并停止承接请求；已有映射必须在停用目标前提示影响。模型上架、候选、停用和弃用的状态要分开表达。
生成文件与保留期
图片、音频、视频等生成文件默认存入对应项目 Storage；纯文字回复和 ASR 转写继续留在接口响应与工作流记录中，不自动生成文件。项目管理员可将新生成文件的保留期设为 24 小时、7 天或 30 天，默认 7 天。设置更改只影响之后生成的文件；已有上传和回收站保留政策不受影响。到期文件应立即停止读取和签名，再由安全清理任务删除；用户可在到期前将文件保存为长期项目资产。
鉴权与上线门槛
既有 Chat/ASR 的 API Key、OAuth 用法与无参模型列表保持兼容。新任务使用逐项启用的 API Key 权限和独立 OAuth scope，存量权限不自动扩张；项目文件生成还要验证目标项目所有权与配额。媒体、异步任务和长会话必须能准确计量并避免重复扣费。任何没有真实渠道、可核价格和小额端到端证据的任务，不标记为已上线。
开发与验收门槛
- 对每个
任务 × 模型 × 渠道建立能力记录：输入 / 输出模态、文件和尺寸限制、工具 / 流式 / 结构化能力、计费单位、真实探测结果。只暴露通过对应任务端到端验收的组合。 - 工作流调用用任务和能力选路由；请求、响应、流式、错误、取消、用量都经过该渠道的翻译层。供应商能力缺失时在选模型前说明原因；运行时供应商故障则报真实故障，不能混称协议不兼容。
- 验收至少覆盖各已上架渠道的真实小额调用，以及工具循环、流式终态、媒体文件、异步视频轮询、取消和计费。模型目录出现但未通过探测，不算工作流可用。
- 新增端点按上文合同逐项实现；每项独立记录鉴权 scope、计费、额度、文件有效期和真实线上验收结果。代码完成、PR 合并、部署成功与真实渠道可用分别报告。