60 lines
8.8 KiB
Markdown
60 lines
8.8 KiB
Markdown
# New API 文档学习与工作台兼容复核
|
||
|
||
2026-11-06容量纠正:已取得Anthropic官方Models overview,claude-opus-5-5同步最大输出128000/上下文1000000公开已知;此前“未取得最大值”仅为当时调查状态,并非官方没有公布。精确型号官方规格已作为目录缺项的后备来源,源码2bd7b24a、独立67/67与网页4组通过,未部署。见[官方容量纠正](QA-CLAUDE-OFFICIAL-CAPACITY.md);下方正式旧程序与原研究状态保留为原时点。
|
||
|
||
来源固定于2026-11-06,中文目录305篇正文及201份嵌入OpenAPI定义已逐项审读;API与Plugins均在覆盖范围。公开文档仓库提交d254f1842dc3d08d60f2269e2c9d4c9876a3dfbc。来源与SHA见[newapi-documentation-sources-2026-11-06.json](newapi-documentation-sources-2026-11-06.json),逐篇阅读批次/笔记见[newapi-documentation-review-2026-11-06.json](newapi-documentation-review-2026-11-06.json),计划见[NEWAPI-DOCUMENTATION-REVIEW-PLAN.md](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 |
|
||
|
||
## 与工作台实现逐项对照
|
||
|
||
下表是源码能力与本机契约的对照,不把网关文档条目当作工作台已经实现的功能,也不认证代理线路的实际模型能力。
|
||
|
||
| 文档主题 | 工作台实现与此次处理 | 仍需保留的边界 |
|
||
|---|---|---|
|
||
| Chat / Responses / Messages | 已有三种请求/响应与流式适配;Messages携带anthropic-version和协议必填max_tokens | 代理的协议转换、物理型号与实际服务稳定性须另验 |
|
||
| 模型获取与多选 | 现有目录预览、多选、共享凭据、手动或自动模型池;此次修复已有连接仅跳过、未刷新upstreamModel的问题 | 只有ID的目录不能补造最大容量或能力;刷新仍由用户显式应用 |
|
||
| 目录容量与名字 | 此次增加displayName、inputTokenLimit、outputTokenLimit声明解析;已有连接只更新目录元数据 | 这不是Gemini原生请求或分页适配;目录声明与已验证能力分开 |
|
||
| 在途请求与凭据 | 刷新替换元数据对象,旧准备快照保持;不改凭据绑定的连接revision,不重加密保存块 | 用户参数、覆盖、启停、名字不由目录刷新覆盖 |
|
||
| 输出截断 | 此次诊断改读实际已序列化请求,分别显示max_tokens / max_completion_tokens / max_output_tokens或确实未携带字段 | 不根据错误自动扩大参数、重试或改写历史请求;截断工具批次不执行 |
|
||
| Responses incomplete | 此次补齐HTTP200 / incomplete / max_output_tokens的截断分类;其它原因保留原意 | 内容过滤、未知原因不能统一归因为输出额度 |
|
||
| 推理参数与内容状态 | 已有品牌参数配置、原生参数、thinking签名/不透明状态与DeepSeek reasoning_content绑定 | 不是所有模型都公布完整能力,不把New API旧枚举当原厂完整范围 |
|
||
| 工具与图像输入 | 已有工具定义/参数/返回关联、图片内容和流末帧完整性核对 | 服务端搜索/执行工具、PDF、全部多模态内容块尚未完整接入 |
|
||
| 缓存与用量 | 保留实际上游缓存/推理用量、原始usage、请求前缀依据;unknown与本地估算分列 | 网关Redis/Session不是prompt cache,缓存命中及Purge收益不能据文档保证 |
|
||
| 错误、网络与重定向 | 保存上游原文/状态/请求ID/物理尝试、实际地址;默认透传不自动重发,重定向不转发凭据 | 网络中断可能已产生上游消费,unknown不补造成功或计费 |
|
||
| Gemini原生与媒体 | 目录可识别部分声明;原生generateContent、音频、视频、Realtime等未完整实现 | 经兼容Chat接口使用某型号,不等于已实现该品牌所有原生能力 |
|
||
| 网关插件 | 已读Wasm ABI、宿主HTTP/认证/持久化/用量、SSE与异步任务约定,版本差异单列 | 未安装或执行网页插件,也未实现New API Wasm插件宿主 |
|
||
| 管理/运营与Skills | 已读权限、渠道、令牌、额度、计费、日志、支付与Skills说明 | 不作为模型Key接口,不复制运营额度为工作台本地默认限制;不执行文中安装命令 |
|
||
|
||
## 未完成的真实验证
|
||
|
||
正式1.25.12 Claude旧声明2048仍被用于Messages必填max_tokens,未取得此型号权威最大值。本次源码刷新修复只在上游确实提供容量、且用户选择应用时使用该声明;缺项仍不能声称同步了最大值,也不能用0表示无限。
|
||
|
||
此次两处修复的本机HTTP、序列化请求、用量与回归结果见[兼容复核验收](QA-NEWAPI-COMPATIBILITY-REVIEW.md)。Gemini原生/媒体、服务端工具和插件宿主是独立功能差距;真实供应商兼容、角色收益、普遍重复读取改善与Purge收益仍需新实验。
|
||
|
||
研究尚未操作正式服务、真实Key或模型请求;原400缺max_tokens、网络异常、重复读取、unknown用量与Purge收益unknown保持。仅学习不自动打包或重启。
|