开发文档
接口设计
公共协议、浏览器业务接口与受限产品操作的契约语义
现有接口清单见平台 API。原版路径先按固定源码 SHA 审计；新增产品接口的 URI、凭据格式和版本尚未确定。本页定义开发必须满足的语义，不宣称原版已经提供这些端点。
接口分组与可信主体
| 分组 | 调用者及鉴权 | 范围 |
|---|---|---|
| 公开目录 | 无会话，限流与配置过滤 | 已上架模型、公开价及文档，不返回内部采购与客户信息 |
| 公共模型协议 | 用户 API Key，或专用受限委托入口 | OpenAI/Claude/Gemini；客户不能伪造可信产品来源 |
| Console | 用户会话、写操作 CSRF/Origin、对象归属 | 本人 Key、价格、钱包、订单、记录与安全设置 |
| Admin | 员工会话、写操作 CSRF/Origin、动作权限 | 平台管理、审计、异常核对；敏感操作重新确认当前权限 |
| 产品集成 | 会话与受限产品凭据，或原已授权操作 | 身份/角色查询、操作创建、开始、查询、结算/释放与结果恢复 |
| 支付通知 | 渠道签名、商户/订单/金额/币种核验 | 可信事实入账；不接受浏览器声称的支付成功 |
建议同步请求采用用户 Cookie + 服务凭据，后台采用服务凭据 + 原操作；凭据形态待 T-04 定稿。产品身份查询只转发指定会话凭据，不把原请求整套 Cookie/Header 发给平台。服务凭据由后端保存，浏览器不得携带。
新增操作语义
模型消费由中转链路统一完成授权、预扣与结算；不能在产品侧为同一次模型调用再申请非模型预留。下面显式的预留、确认开始、补充预留和结算/释放主要面向非模型业务，模型授权与操作关联按审计后的中转契约实现，始终只产生一次冻结/扣费。
| 动作 | 输入 | 平台返回/保证 |
|---|---|---|
| 确认身份与角色 | 会话；查询动作/作用域受限 | 当前用户/状态/授权范围；不返回会话密钥 |
| 创建授权/非模型预留 | 可信用户凭据、产品服务身份、业务任务、收费项/规格、幂等键 | 平台生成 operation_id，价格快照/预留结果；金额由平台核算 |
| 确认开始 | 原操作、允许动作、幂等键 | 原子争取执行资格；已释放/到期拒绝；重复结果可查询 |
| 查询原操作 | 原操作及同产品凭据 | 归属范围内的执行、资金、恢复与结果状态 |
| 补充预留 | 原操作、新增业务上限、原快照和幂等键 | 成功后才能扩展执行；余额不足拒绝，不改写既有快照 |
| 结算 | 原操作、确认业务事实和实际数量、幂等键 | 按原价格结算，非模型不超过已预留上限 |
| 释放/退款 | 原操作、可信未执行/失败事实、原因及幂等键 | 释放冻结或关联原消费退款，两者不混用 |
| 后台登记/恢复 | 原任务/操作、确认事实、受限动作 | 不能指定新用户、跨产品或新建未授权付费执行 |
模型中转自己处理用量和资金，产品不能再为同一次模型调用走非模型扣费。报价预览不冻结余额、不授权执行；创建操作时重新验证价格并保存快照。
契约约定
- 自有接口统一声明时间时区、分页、金额单位与精度、数量单位、请求 ID 和错误码。金额使用整数或定点字符串，最终形式由精度决策确定。
- 幂等键绑定可信主体及动作，保存指纹；同键同输入返回原结果，同键不同输入返回
409。重试查询与超时行为在契约中写明。 - 模型标准协议保持原格式及流式语义，不用自有业务 envelope 包住兼容响应。普通错误和流开始后的错误/未知用量分别规定。
- 用户/产品/角色从验证结果和持久操作读取。跨用户/产品对象访问拒绝；避免错误消息泄露其他用户对象是否存在。
401未登录/无效凭据，403无权限，409幂等或状态冲突，429限流，503暂不可用；余额不足和价格未配置使用明确业务错误码，HTTP 映射在契约定稿。- 执行未知必须提供安全的原请求/操作查询依据；客户端不得把
5xx自动理解为供应没有执行。
契约源与版本
平台仓库 docs/openapi/ 保存自有接口单一契约源，覆盖权限、状态、错误、幂等、单位、示例和兼容性。两前端和产品客户端从该源生成或校验类型。T-01 确定生成方式，T-04/T-05 在编码前确定首版，避免继续引用旧 Contracts/Core 的生成脚本。
标准模型协议用版本化兼容矩阵及夹具验证；OpenAPI 不足以描述完整 SSE 行为。破坏性变更给出版本或迁移窗口，更新客户端和证据后切换，不仅改路径。