接口
平台对外提供的三类接口
平台的接口分三类，面向不同的调用方。
| 类型 | 调用方 | 来源 | 状态 |
|---|---|---|---|
| 公共模型 API | 开发者、产品工程 | new-api 原有 | 可直接使用，第 1 阶段验证 |
| 平台业务 API | Console、Admin 前端 | new-api 原有，少量新增 | 大部分可直接使用 |
| 产品集成 API | 产品工程后端 | 新增 | 第 2 阶段设计 |
公共模型 API
开发者用 API Key 调用，路径和格式与 OpenAI、Anthropic、Gemini 官方一致，现有 SDK 可以直接使用。
| 能力 | 路径（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 |
| 视频任务 | 提交、查询任务的接口，按媒体网关对接方式在第 1 阶段确定 |
| 图片生成与编辑（候选） | POST /v1/images/generations、POST /v1/images/edits；供应链路及格式待验证，不代表首发开放 |
| 音频（候选） | POST /v1/audio/speech、POST /v1/audio/transcriptions；其他能力按实际需求审计后确定 |
具体开放哪些路径，以第 1 阶段验证通过的组合为准；未验证的路径不对外开放。
平台业务 API
Console 和 Admin 前端调用的接口，以 new-api 原有的 /api/* 为主，例如 /api/user/*、/api/token/*、/api/log/*、/api/pricing。各页面使用的接口见 Console 和 Admin。
需要新增或修改的：
- 使用记录增加“来源产品”字段和按产品筛选。
- 企业协议价、价格版本与报价预览。
- 积分换算改为人民币规则（订阅、充值）。
- 平台角色与产品角色的分配和查询。
产品集成 API
供 oceanway-studio 等产品后端调用，全部需要新增，在第 2 阶段设计：
| 接口 | 用途 |
|---|---|
| 身份查询 | 产品转来用户的会话 Cookie，平台返回用户 ID、状态和角色 |
| 权限查询 | 查询用户是否拥有某个产品角色，如 studio:admin |
| 代用户调用模型 | 产品以服务凭据代表用户调用公共模型 API，使用记录标注来源产品 |
| 预留、结算、释放 | 非模型扣费，带幂等键，见钱包与计费 |
| 操作状态与恢复查询 | 按 operation_id 查询授权、资金状态和关联任务；未知结果复用原操作 |
| 客户任务及结果访问 | 校验用户、产品与任务归属后返回客户可用的结果，隐藏供应凭据和内部任务身份 |
凭据形式见身份与权限中的“产品服务凭据”。
契约必须声明的字段与行为
- 操作身份、可信用户与产品来源、业务任务身份、动作、请求指纹、计量单位与精度；字段名以实现时的 OpenAPI 为准。
- 用户和产品从已验证会话、受限委托或原操作推导，不能任意传入。服务凭据的作用域与后台操作的授权依据分别说明。
- 同键同请求的原结果、同键不同请求的
409、余额不足、无权限、待核对、终态冲突和可恢复错误。 - 预留价格快照、执行开始确认、查询及结算/释放的状态转换，避免执行与到期释放竞态。
- 服务端任务及账务状态可以分别查询；不能把 HTTP 成功、任务成功、媒体已持久保存和资金已结算视为同一状态。
上述为接口设计要求，产品集成 API 尚未实现。原版中转和验证性扩展分别记录结果，见平台集成验证。
文档与规范
接口说明以平台仓库中的 OpenAPI 文件为准，对外的开发者文档放在 Console 的文档页。本页只记录接口分类和需要新增的部分。