From 8d6a8420556cd7050b429ca588221ab976f3e1de Mon Sep 17 00:00:00 2001 From: skycurtain Date: Wed, 9 Sep 2026 01:40:03 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20=E6=B3=A8=E6=84=8F=E4=BA=8B?= =?UTF-8?q?=E9=A1=B9=E6=96=87=E6=A1=88=E5=AE=A1=E6=9F=A5=E2=80=94=E2=80=94?= =?UTF-8?q?=E5=8E=BB=E9=99=A4=E5=86=85=E9=83=A8=E8=B0=83=E7=A0=94=E5=8F=99?= =?UTF-8?q?=E4=BA=8B=EF=BC=8C=E6=94=B9=E7=94=A8=E6=88=B7=E8=A7=86=E8=A7=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除「接口①④」「双重验证」等文档编号/调研过程叙事，改写为用户可独立理解的完整因果或操作指引 - 接口指代全部点名完整路径（usage 接口/同 subscription/billing 接口 → 完整路径） - ÷500000 硬编码改为 ÷ quota_per_unit（见 /api/status）——消除与「不要硬编码」自相矛盾 - log/token 的 id desc 排序补关键警示：id 是展示序号跨请求无意义，勿用于去重或游标 - 源码细节泛化溯源（Update() Select/MaxRecentItems/abilities 表 → NewAPI 源码验证/硬编码/内部存储） - 「虚拟滚动的核心场景」改为用户视角「页面已做虚拟滚动优化，可直接流畅浏览」 - 验证：test 64/64 + type-check + lint + build 四绿 --- src/api/endpoints.ts | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/api/endpoints.ts b/src/api/endpoints.ts index 4bc7171..17324b3 100644 --- a/src/api/endpoints.ts +++ b/src/api/endpoints.ts @@ -32,9 +32,9 @@ export const endpointList: readonly EndpointDefinition[] = [ responseSummary: '站点配置与计费参数（含 quota_per_unit）', notes: [ '完全公开：无任何鉴权，不持有 sk-key 也能访问（本工具对接清单中唯一）', - 'quota_per_unit 是 QuotaPerUnit 当前生效值（默认 500000，源码 $0.002 / 1K tokens 锚点）——quota ÷ 该值 = 美元，换算比率的唯一权威来源，管理员可改，不要硬编码', - '接口①④交叉实测吻合验证不了管理员是否改过此值：billing 接口内部就是拿 quota ÷ QuotaPerUnit 换算，同一常量自证', - 'quota_display_type 影响 billing 接口语义：USD 直接是美元；CNY 先 ÷QuotaPerUnit 再 ×usd_exchange_rate；TOKENS 是原始 token 数', + 'quota_per_unit 是 QuotaPerUnit 当前生效值（默认 500000，NewAPI 以 $0.002 / 1K tokens 的基准定价为锚点设计）——quota ÷ 该值 = 美元，换算比率的唯一权威来源，管理员可改，不要硬编码', + '想用 billing 接口（subscription / usage）反推换算比率不可靠：它们内部就是拿 quota ÷ QuotaPerUnit 换算的，站点改了配置它们会跟着变，永远「吻合」——比率唯一权威只有本接口的 quota_per_unit', + 'quota_display_type 影响 /v1/dashboard/billing/subscription 与 /v1/dashboard/billing/usage 的语义：USD 直接是美元；CNY 先 ÷QuotaPerUnit 再 ×usd_exchange_rate；TOKENS 是原始 token 数', '返回 60+ 字段（版本、登录方式、前端模块开关、公告等），解析时只取计费相关字段，其余忽略；字段集合随版本演进，需容忍未知字段', ], sampleResponse: { @@ -63,7 +63,7 @@ export const endpointList: readonly EndpointDefinition[] = [ '受 DisplayTokenStatEnabled 开关影响：开启返回 token 级额度，关闭回退到账号级额度（会暴露整个账号余额）', '无限额度 key 返回 100000000（一亿）占位值，无参考意义', '受 quota_display_type 影响：USD 模式才是美元；CNY 模式会做货币转换；Tokens 模式是原始 token 数', - 'hard_limit_usd（本接口）− total_usage ÷ 100（usage 接口）= 剩余额度（仅有限额 key 有意义）', + 'hard_limit_usd（本接口）− total_usage ÷ 100（/v1/dashboard/billing/usage）= 剩余额度（仅有限额 key 有意义）', ], sampleResponse: { object: 'billing_subscription', @@ -83,8 +83,8 @@ export const endpointList: readonly EndpointDefinition[] = [ notes: [ 'total_usage 单位是美分，换算美元 ÷ 100', '累计值（key 创建至今），非当月用量', - '与 /api/usage/token 的 total_used ÷ 500000 完全吻合（QuotaPerUnit = 500000 的双重验证）', - '受 DisplayTokenStatEnabled 与 quota_display_type 影响（同 subscription 接口）', + '可与 /api/usage/token 的 total_used ÷ quota_per_unit 交叉对账（两接口应一致；若不一致，说明站点改过 quota_per_unit，见 /api/status）', + '受 DisplayTokenStatEnabled 与 quota_display_type 影响（同 /v1/dashboard/billing/subscription）', ], sampleResponse: { object: 'list', total_usage: 134683.8914 }, }, @@ -95,7 +95,7 @@ export const endpointList: readonly EndpointDefinition[] = [ authMiddlewareName: 'TokenAuth', responseSummary: '可用模型列表（OpenAI 格式）', notes: [ - '数据源是数据库 abilities 表，反映渠道实际配置的模型', + '数据源是数据库中渠道实际配置的模型表（NewAPI 内部存储），反映渠道真实配置', '与 /v1/models/:model 单查接口数据源不同（后者查代码内硬编码静态表）', '渠道新配的模型可能出现「列表里有、单查 model_not_found」，不影响实际调用', ], @@ -112,9 +112,9 @@ export const endpointList: readonly EndpointDefinition[] = [ responseSummary: 'token 级用量汇总（原始 quota）', notes: [ 'total_used 是累计值（key 创建至今），非当月用量', - '额度为原始 quota 整数，换算美元 ÷ 500000（QuotaPerUnit）', + '额度为原始 quota 整数，换算美元 ÷ quota_per_unit（见 /api/status，默认 500000）', 'unlimited_quota = true 时 total_granted / total_available 为占位值，无实际意义', - '禁用再解禁不会重置 total_used（源码验证：Update() 的 Select 列表不含 used_quota）', + '禁用再解禁不会重置 total_used（NewAPI 源码验证：token 更新逻辑不覆盖该字段）', '不受 DisplayTokenStatEnabled 开关影响，恒返回 token 级数据', ], sampleResponse: { @@ -140,11 +140,11 @@ export const endpointList: readonly EndpointDefinition[] = [ authMiddlewareName: 'TokenAuthReadOnly', responseSummary: '最近 1000 条调用日志', notes: [ - '硬上限 1000 条（common.MaxRecentItems = 1000）', + '硬上限 1000 条（NewAPI 源码硬编码）', '不支持任何请求参数：分页 / limit / 时间过滤全被忽略', - '固定按 id desc 排序，即最新 1000 条', + '固定最新在前（服务端按内部序号倒序）；响应里的 id 是展示序号，跨请求无意义，勿用于去重或游标', '月调用量超 1000 次时，此接口无法覆盖完整当月', - '大响应：pretty-print 后 2~4MB，约两万行——虚拟滚动的核心场景', + '大响应：pretty-print 后 2~4MB，约两万行——页面已做虚拟滚动优化，可直接流畅浏览', ], sampleResponse: { success: true,