5.2 KiB
5.2 KiB
New API 文档学习与工作台兼容复核
来源固定于2026-11-06,中文目录305篇正文及201份嵌入OpenAPI定义已逐项审读;API与Plugins均在覆盖范围。公开文档仓库提交d254f1842dc3d08d60f2269e2c9d4c9876a3dfbc。来源与SHA见newapi-documentation-sources-2026-11-06.json,逐篇阅读批次/笔记见newapi-documentation-review-2026-11-06.json,计划见NEWAPI-DOCUMENTATION-REVIEW-PLAN.md。抓取和实际审读分别记录;更新日志略去重复下载文件HTML列表、缩短归属链接,保留实质条目;API阅读略去x-apifox编辑器排序扩展,保留全部语义字段。文中图片未逐像素验收,空页和未解析引用不补造内容。
已读理解
- 协议分别处理:Claude Messages要求anthropic-version、model/messages/max_tokens,system独立,工具为tool_use/tool_result内容块。文档中的1024/2000只是例子,不是统一默认或最大值。Chat、Responses、Gemini各有字段、流事件和用量定义。
- 模型目录有多种格式;/v1/models可按认证头切换OpenAI/Anthropic/Gemini,Gemini分页。目录可预览新增/变更/移除;已有连接不能只跳过不刷新。独立模型元数据库不等于具体代理的实测能力。
- 管理Access Token、模型API Key、Session是不同凭据;管理接口可能还要求New-Api-User匹配。账户/分组额度、限流、倍率和预扣是网关运营能力,不成为本工作台的默认本地额度。
- New API负责网关路由/协议转换,不等于自主工程Harness。Redis/Session缓存不等于模型prompt cache。前缀、工具顺序和原生缓存参数应稳定,用实际usage验证,不能保证永不掉缓存。
- 实际usage的0、缺失和unknown分别保留,估算不补造计费;断连/超时不代表未执行,不能盲目重放。请求名、映射名、返回名和物理型号不能混同。
- 插件由宿主负责HTTP/认证/持久化/计费,插件报告用量事实;key/version/SHA/generation与在途兼容相关。Responses sync/stream/background、native、image/video能力分别声明。unknown不能默认in_progress,public task ID与upstream ID分开,fixture不等于真实上游验收。
- Skills的管理凭据与模型Key分开,文档newapi-admin仍未发布。页面安装命令只读,不执行。
- 旧日志与当前日志已读完实质条目(下载资产重复列表不计功能契约)。原生推理参数应按用户请求保持,不因型号后缀误改真实模型ID;显式0、纯缓存请求、工具图片、参数JSON字段顺序和流末帧工具都可能影响兼容。New API的网关估算结算不转作工作台的真实账单。
- 全部模型API正文/定义已读:音频含multipart/二进制、Gemini媒体含URI权限、图片/视频有各自结构和异步状态;Realtime需WebSocket101。文件/微调明确501未实现,有目录条目不代表功能可用。
- 管理API已读:渠道/标签/多Key/模型元数据/供应商/用户/令牌/日志/验证/支付/系统选项分别有User/Admin/Root权限。GET也可能产生测试、轮换、余额更新等副作用;无需登录的回调仍有流程验证。管理接口大量响应仅写200或有Unresolved引用,不能据此生成完整SDK。旧Telegram/Access Token接口与新日志明确迁移,版本差异保持。
文档内部版本差异
| 条目 | 已观察的差异 | 处理 |
|---|---|---|
| 订阅续费 | 订阅页说自动续费,钱包页说当前不支持 | 按实际部署版本核实,不推断已具备 |
| Claude缓存 | 旧特性清单未支持;Messages schema和新日志已有缓存用量/计费修复 | 区分旧清单和当前契约 |
| 分组限流 | 不同说明有时间窗口/总数成功数语义差异 | 不据此新增客户端限流 |
| 插件requestBody | API参考为kind/value联合类型,最小例子直接取prompt | 按实际版本契约,不照抄矛盾例子 |
| 插件大小 | 指南1MiB,rc.40提高至8MiB | 标明版本 |
| 插件网络/能力 | 旧指南不许fetch且要求能力;rc.43新增utils.fetch,json-clone/SSE-delta可不声明 | 标明版本 |
| 任务保存 | 旧页24小时,新rc.47默认72小时 | 不改写旧版行为 |
| API定义完整性 | Messages正文体optional却有必填字段、仅旧thinking枚举;Responses用量示例沿用Chat;部分管理定义直接标Unresolved $ref | 不把该生成schema当穷尽的原厂规范或完整SDK |
已确认的工作台后续差距
- 已有连接目录apply直接跳过,未刷新upstreamModel;应只更新目录来源,保留用户原生参数、名字、覆盖、凭据归属和启停。
- 截断提示通称未附加输出额度,对Messages必填值/用户原生值不准确;应依据实际wire说明。
- 正式1.25.12 Claude旧声明2048仍被用于Messages必填max_tokens,未取得此型号权威最大值;不能声称同步了最大值,不能用0表示无限。
研究尚未操作正式服务、真实Key或模型请求;原400缺max_tokens、网络异常、重复读取、unknown用量与Purge收益unknown保持。仅学习不自动打包或重启。