新网关(源码指南)

新网关账号与 Key

OneAster 新网关部署提交 f09a2d5 与 Go 构建版本 7ba12de+oneaster.0.1.0 的契约与接口指南。

模型目录、展示名称、价格与积分单位(PR #46)

/oneaster/v1 业务接口使用原生登录取得的 access_token(Authorization: Bearer $ONEASTER_ACCESS_TOKEN),不接收推理 API Key。GET /oneaster/v1/model-catalog 列出模型目录,GET /oneaster/v1/model-catalog/detail?model=PUBLIC_NAME 查询单个模型详情(模型名含斜杠时需 URL 编码)。目录项同时返回调用 ID model_name 与管理员可配置的展示名 display_name:前端卡片标题可展示 display_name,但所有推理请求体中的 model 参数必须传 model_name(或 /v1/models 中的 id)。

模型售价由管理员配置。目录项的 pricing.mode 为 tiered_expr(读取 billing_expr 与 billing_usage_schema 等表达式依据)、per_request(读取 model_price)或 ratio(读取 model_ratio、completion_ratio 等倍率)。分组信息 group_ratio、usable_group、auto_groups、supported_endpoint 与 pricing_version 位于目录响应 data 顶层,不是每个模型的分组数组;前端应结合当前用户组和对应计费模式展示,切勿写死售价或从供应商官网推导本站售价。official_price 是可选美元对比基准,未配置时为 null,仅用于展示,不参与实际扣费,为 null 时不得伪造划线原价。

本站账务单位遵循:1 USD = 100 OneAster 积分(credits);接口内部金额字符串保留 4 位小数(如 "12.3450"),前端常规展示保留 2 位小数。原生 quota 与美元/积分换算以响应中的 quota_per_usd(1000000,即 1 OneAster 积分 = 10000 quota)为准,不得混用上游 KIE 积分。

账户、钱包与 API Key 管理

GET /oneaster/v1/account 读取当前账户,GET /oneaster/v1/wallet 读取钱包余额与累计消费。GET /oneaster/v1/keys 支持 page、size、keyword;GET /oneaster/v1/keys/{id} 读取元数据;POST /oneaster/v1/keys 创建推理 Key;PATCH /oneaster/v1/keys/{id} 与 DELETE /oneaster/v1/keys/{id} 更新或删除 Key。仅创建响应返回明文密钥,若创建响应丢失请先核查已有 Key,不要自动重复创建。

统一充值预览与支付渠道(PR #47 / #48)

新网关提供统一的只读充值积分预览接口:

GET /oneaster/v1/billing/preview?provider=stripe&amount_usd_cents=1000
Authorization: Bearer $ONEASTER_ACCESS_TOKEN

统一预览要求原生登录 access_token 或具备 wallet:read 的 PAT,拒绝推理 API Key,返回 Cache-Control: no-store。amount_usd_cents 为原始支付本金的美元分(例如 1000 代表 USD 10,不是充值积分)。

- Stripe:金额必须是当前 Stripe 商品单价的整数倍,且满足购买数量限制(1 至 10000)。Stripe 不支持 pay_currency 与 fee_mode。

- NOWPayments:支持 pay_currency(默认 usdttrc20)与 fee_mode(deduct 从结算额扣费,或 on_top 由付款人额外承担费用;默认 deduct)。支持正整数美元分,金额范围受商户配置约束(默认 USD 15–10000)。

- 返回字段:expected_credits 为预计积分;credits_per_usd 为 100;credit_basis 为 purchased_quota(Stripe 与 NOWPayments on_top)或 net_settlement(NOWPayments deduct);fee_usd_cents 与 estimated_net_credits 均为 null(当前未知,切勿当作 0);promotion_codes_enabled 与 discount_reason(no_discount 或 checkout_promotion_only);final_payment_amount_at_checkout: true 提示最终实付以收银台为准;checkout_request 原样作为后续创建订单的入参。

- 兼容旧接口:GET /oneaster/v1/billing/stripe/preview?amount=10 保持可用(其中 amount 为整数购买数量,非美分)。

- 预览仅作只读报价,不创建订单、不冻结资金、不估计未知手续费,也不保证到账。

创建订单与实际到账:

- Stripe 订单创建:使用登录 access_token 或 wallet:write PAT 调用 POST /api/user/stripe/pay,提交 amount(购买数量)与 payment_method: "stripe",返回包含 pay_link、trade_no 与 preview 实时报价快照。只读报价也可调用 POST /api/user/stripe/preview。创建失败可能仍为 HTTP 200、message=error(data 为错误文本)或 success=false,不能只看 HTTP 状态或自动重复创建。

- Stripe 到账与充值记录:本人查询 GET /api/user/topup/self?p=1&page_size=20(最近 30 天);管理员全平台查询 GET /api/user/topup?p=1&page_size=20。每条记录包含 expected_quota、expected_pay_usd_cents(创建时原价美分,非优惠后实付)、expected_credits、credited_quota、credited_credits 及 credit_status(none 未入账,credited 已有入账证据,unknown 历史成功记录缺少精确额度证据)。credited_credits 仅在钱包入账事务成功提交后出现;未成功订单为 "0.0000",无历史证据的成功订单为 null,绝不补零或重新反算。支付页面回跳不是到账凭证,按订单确认 credit_status=credited 后再刷新 GET /oneaster/v1/wallet。

- NOWPayments 订单与到账:通过 GET /oneaster/v1/billing/nowpayments/capabilities 检查能力,提交 POST /oneaster/v1/billing/nowpayments/orders(每次支付意图必须附带唯一 Idempotency-Key),并通过 GET /oneaster/v1/billing/nowpayments/orders/{id} 核查实际 credited_credits 与 credit_status。

任务账务诊断、提交登记屏障与结算回执(PR #43 / #44)

异步任务生成成功(status = SUCCESS)不等于账务已完成最终结算。新网关在任务提交阶段设立持久化登记屏障(oneaster_task_registrations):若上游已创建任务但本地预扣登记写入失败,网关会尝试退回预扣额度、将该任务隔离为 status = UNKNOWN(reason_code = task_accounting_registration_failed),并返回 422 task_accounting_failed,阻止后台轮询器在无登记依据时执行结算。

普通用户可调用 GET /oneaster/v1/task-diagnostics 和 GET /oneaster/v1/task-diagnostics/{task_id} 查询本人异步任务的资金来源与结算证据。列表允许 page(1..10000)、size(1..100,默认 20)、exception(all、exceptions、unknown、failed、stalled,默认 exceptions)、task_id、stalled_seconds(60..86400,默认 1800)、start_timestamp 与 end_timestamp(秒级时间戳,默认最近 7 天)。管理员(角色 >= 10)的 /oneaster/v1/admin/task-diagnostics 列表额外允许 user_id、channel_id;详情只允许 stalled_seconds,管理员详情额外允许 user_id。任务诊断接口要求实时登录会话 access_token,拒绝 PAT 与推理 API Key;普通用户访问不存在或非本人任务统一返回 404。

列表返回轻量摘要,billing_evaluated=false、current_task_amount 位于摘要顶层。详情返回 funding(source 为 wallet、subscription 或 unknown,credential_type 为 login_session、inference_key 或 unknown)、billing(state 为 unknown、reserved、settled 或 released,finalized、observed_net_charge、original_reserved_amount 与可空 settlement_receipt)、evidence(最多 50 条关联日志、logs_truncated、aggregate_complete)、reason_codes、automatic_retry_allowed=false 与 reconciliation_review_url(仅 Root 角色 >= 100 的 KIE UNKNOWN 任务返回入口,否则为 null)。详情中的 current_task_amount 仍位于顶层,不在 billing 中。未知金额为 null,前端必须展示“待确认”,不能补零,也不能自动重发 UNKNOWN 或执行中任务。

curl --request GET "https://api.oneaster.ai/oneaster/v1/task-diagnostics/task_00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"

请求诊断与只读排障 CLI(PR #50 / #51)

GET /oneaster/v1/request-diagnostics/{request_id} 查询本人,使用原生登录凭据;PAT 需 usage:read,不接受 username。GET /oneaster/v1/admin/request-diagnostics/{request_id} 要求原生管理员角色,PAT 另需 log:read;可用 username 精确筛选原生用户名,非 display_name。username 最多 64 UTF-8 字节,允许中文和内部空格,拒绝首尾空白、控制字符、无效 Unicode、凭据前缀与 %。request_id 为 1–64 位字母、数字、下划线或连字符,拒绝 sk-、oak_、nap_ 前缀、通配符及重复或额外参数。

成功返回 {data: ...},包含 request_id、scope、user_id、observed_at(Unix 秒)、total_records、truncated、records、billing。records 含安全元数据、request_path、funding_source、结构化 http_status/code/type/parameter_constraint;不返回原始错误正文、对话、文件、IP、Other、root/audit 信息、Key 或供应商地址。管理员可见时 routing 展示尝试、渠道、耗时、状态与决策;本人没有管理员路由。routing_available=false 时 routing=[],缺失路由不代表没有调用上游;最多 100 条并由 routing_truncated 标记截断。parameter_constraint 仅解析 max_tokens、max_completion_tokens、max_output_tokens 的特定整数最低值错误;minimum:16、received:1 仅是示例,不是所有模型的统一限制,也不保证解析所有上游错误。

一次最多读取 100 条原生日志,不拼页构造跨时刻快照。billing.consume_count/refund_count 是本次读取的记录数;observed_net_charge 为消费减退款的可观察日志净额,quota 是整数字符串、credits 是四位字符串。无财务日志时金额为 null;本人截断时 aggregate_complete=false、金额未知。int64 范围内负财务额度使聚合未知;缺少必填额度、越界或结构损坏返回 502。null 不代表免费、零扣费或钱包未变。请求诊断始终 billing.finalized=false;它不是结算凭证或钱包余额,任务完成凭证和全量关联财务证据应查看任务诊断详情。详情日志展示截断不等于财务聚合不完整,应分别查看 logs_truncated 与 aggregate_complete。

示例(先将环境变量设为本人获授权的原生凭据;不要将其写入代码或日志):

curl --request GET 'https://api.oneaster.ai/oneaster/v1/request-diagnostics/REQUEST_ID' \
  --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"

无可见记录返回 404 request_diagnostic_not_found;多个可见账号共享请求 ID 或管理员读取截断返回 409 request_diagnostic_ambiguous。精确 username 可缩小范围,但历史用户名可复用,筛选后仍截断仍为 409,不自动合并。

以下命令在 oneaster-gateway 仓库根目录运行,不是 oneaster-doc 或旧 Core 的 oneaster-admin。token 文件须为本人拥有的非符号链接普通文件,禁止组和其他用户权限,推荐 0600;路径和 ID 均为占位符。

export ONEASTER_GATEWAY_URL='https://api.oneaster.ai'
ONEASTER_TOKEN_FILE='/path/to/private/native-token-file'
npm run admin --prefix oneaster -- requests get REQUEST_ID --token-file "$ONEASTER_TOKEN_FILE"
npm run admin --prefix oneaster -- requests get REQUEST_ID --admin --username USERNAME --token-file "$ONEASTER_TOKEN_FILE"
npm run admin --prefix oneaster -- task-diagnostics list --admin --exception failed --token-file "$ONEASTER_TOKEN_FILE"
npm run admin --prefix oneaster -- task-diagnostics get TASK_ID --admin --user-id 6 --token-file "$ONEASTER_TOKEN_FILE"
npm run admin --prefix oneaster -- channel-health get --window-seconds 3600 --limit 100 --channel-limit 100 --token-file "$ONEASTER_TOKEN_FILE"

本人日志和请求诊断要求原生身份,PAT 需 usage:read;管理员日志和请求诊断要求原生管理员角色,PAT 需 log:read。本人和管理员任务诊断均须有效原生登录会话,拒绝 PAT。渠道健康要求原生管理员角色,PAT 同时需 channel:read 和 log:read。scope 不提升账号角色,推理 sk- Key 不能作为管理凭据。

logs list/stat 仅 --admin 支持 username/channel;requests get 管理员模式仅支持精确 username。任务 list 支持 page、size、exception(all/exceptions/unknown/failed/stalled,默认 exceptions)、task_id、stalled_seconds、start_timestamp、end_timestamp;管理员另支持 user_id/channel_id。get 仅支持 stalled_seconds,管理员另支持 user_id。任务 ID 为 1–191 位字母数字下划线或连字符,时间窗口最多七天,stalled_seconds 为 60–86400(默认 1800),page 默认 1、size 默认 20。--admin 是独立布尔标志。

channel-health get 调用既有 GET /oneaster/v1/admin/channel-health;window_seconds 60–86400 默认 3600,limit 和 channel_limit 均为 1–100 默认 100;不接受渠道 ID、--admin 或写入参数。保留 channel.status、evidence.state、backup_presence、coverage 及截断和完整性字段各自语义;它是配置与历史 type 2/type 5 日志的被动观察,不是实时供应商探测,历史成功或备份已配置不代表当前可用。投影不返回供应商地址、渠道 Key、原始错误或对话;损坏响应失败,不伪造健康结果。

上述新增诊断命令仅 GET,不接受请求体、--yes、付费测试、修复或自动重试标志,不自动重试、不改渠道或钱包。--dry-run 仅本地校验语法并显示目标 GET 路径,无需凭据和网络,不证明服务器权限或业务验证。退出码:成功 0,本地参数 2,401/403 为 3,409 为 4,404、传输及其他错误为 1;错误不回显原始响应。

管理员被动渠道健康、定价问题检查与多 Key 渠道恢复(PR #40 / #41 / #46)

管理员接口仅面向具备对应权限的后台管理员,不混入公共推理 Key Playground,普通用户界面也不直接暴露 channel_id 或上游密钥。

GET /oneaster/v1/admin/channel-health(参数 window_seconds 60..86400 默认 3600、limit 1..100 默认 100、channel_limit 1..100 默认 100)要求实时管理员角色(>= 10)、渠道读取权限以及(使用 PAT 时)channel:read 与 log:read 权限。该接口是只读被动诊断:仅聚合当前渠道配置、模型路由与时间窗口内的消费日志(type=2)和错误日志(type=5,需开启 ERROR_LOG_ENABLED=true 才会记录新错误),绝不向上游发起真实收费探测请求,channel.status 为 enabled、manually_disabled 或 auto_disabled,evidence.state 为 unknown、observed_success、observed_failure 或 mixed,模型组 backup_presence 为 configured、not_configured 或 unknown;这些证据不构成实时可用性承诺或自动故障转移保证。单次响应严格限制在 1 MiB 以内,截断标记位于 coverage(包括 channels/success/failure.truncated、models_truncated、output_truncated 等),应同时检查 route_counts_complete 与 evidence_complete。

GET /oneaster/v1/admin/pricing/issues 仅限 Root 管理员(角色 >= 100)调用,基于已启用渠道关联的模型与 model_name_mapping 别名,检查并返回未配置(unconfigured)、计费表达式不兼容(incompatible)与已脱离启用渠道(stale)的定价问题列表。此外,PR #46 修复了多 Key 渠道生命周期:管理员执行 enable_key 或 enable_all_keys 时在数据库事务内更新密钥状态,且仅当渠道因 all_keys_disabled 被自动禁用时才自动恢复启用,不会覆盖管理员手动禁用的渠道。

Playground 生成历史与能力绑定

GET /pg/generations 列出当前用户的 Playground 生成历史;GET /pg/generations/{generation_id} 读取详情;GET 或 HEAD /pg/generations/{generation_id}/assets/{asset_key}/content 读取产物。三者都要求有效原生登录会话,以 Authorization: Bearer <登录会话令牌> 显式授权;PAT、推理 Key 和其他用户的会话不能替代。浏览器请求带 Origin 时必须通过 /pg 的来源校验;无 Origin 的原生 HTTP 客户端也可调用。缺失和非本人记录均返回 404,管理员会话也不能读取其他人的历史。

列表、详情和文件均须各提供一次 model、kind、source:model 是当次请求实际使用的公开模型 ID,kind 为 image、video 或 audio,source 固定 playground。model 须为有效 UTF-8、1–255 字节,无首尾空白、控制字符或 ? # [ ] \,斜杠分段不能空、为 . 或 ..;查询值应 URL 编码。列表额外支持 limit(规范十进制整数 1–50,默认 20)和 cursor;cursor 与账号、model 和 kind 绑定,应原样用于同范围下一页。详情和文件不接受 limit 或 cursor;所有接口拒绝重复或额外查询参数。generation_id 为 1–64 位 ASCII 字母、数字、下划线或连字符。

GET /pg/generations?model=<URL编码的公开模型ID>&kind=image&source=playground&limit=20
Authorization: Bearer <登录会话令牌>

列表返回 items 和可空 next_cursor。记录包括 id、request_id、model、kind、source、operation、status、created_at、updated_at、可空 task_id、artifacts 和可空 failure;详情还返回 input。当前没有输入档案:input_available=false,input 和 prompt_excerpt 为 null,不能据此重建提示词、上传素材或重放生成。读取历史不重新预扣或调用供应商。同步任务的 task.data 已清理时,若原意图仍保留完整且未过期的响应,图片仍可能可读;文件保留也受任务和供应商到期限制。

参数错误返回 400 invalid_generation_query;存储或产物投影故障返回 503,不能当成空列表。文件未就绪返回 409 generation_not_ready,过期返回 410 generation_asset_expired,缺失或无权访问返回 404。图片产物可能包含 delivery: {url, hosts}:这是供客户端 BFF 使用的受约束读取声明,仅限执行插件声明的 HTTPS CDN,且不带端口、用户信息、fragment、请求凭据或请求体。BFF 应从浏览器元数据剥离 delivery;它不是允许匿名下载或代理任意 URL 的接口。受保护的 content_url 才是历史文件入口。

GET /api/oneaster/generation-bindings 返回按可用组过滤的公开模型与生成绑定,供展示和接入参考。它遵循原生 pricing 导航模块权限:启用且无需登录时可匿名访问;配置要求登录时须通过用户认证;模块禁用时普通访问被拒,带认证的 Root 可按原生规则访问。实际配置需以部署为准。公开调用 model ID、插件 key、上游 model 与 display_name 各有不同用途;绑定只描述元数据,不保证插件执行成功,也不证明模型已启用、已定价或有可用路由。

从请求日志读取生成资源

GET /oneaster/v1/logs 与 GET /oneaster/v1/admin/logs 的条目包含可空 task_id 和 resource_lookup。使用 request_id 关联资源,日志显示序号不是请求 ID;同一任务的扣费、退款与差额日志可以指向同一产物,不能计作多个生成。task_id 是当前已知的单一任务,多任务时可为 null,完整集合查看详情 task_ids。resource_lookup.state 的 resolvable 表示有可查询线索,unknown 表示尚未确认,not_applicable 表示明确不适用;这些都不证明生成已完成或文件永久可用。href 可为 null。

用户详情 GET /oneaster/v1/logs/requests/{request_id}/resources;用户文件 GET 或 HEAD /oneaster/v1/logs/requests/{request_id}/resources/{resource_id}/content。管理员分别使用 /oneaster/v1/admin/logs/requests/{request_id}/resources 和其 /{resource_id}/content 子路径,两者均必须且只能带一次 user_id=<日志所属用户ID>,不是当前管理员 ID。本人路径不接受任何查询参数;管理员路径不接受重复或额外参数。user_id 为安全整数范围内的正十进制数、最多 16 位且无前导零。request_id 为 1–64 位 ASCII 字母、数字、下划线或连字符,不能以 sk-、oak_、nap_ 开头(不区分大小写);resource_id 为 64 位小写十六进制。格式错误返回 400 invalid_resource_query。

GET /oneaster/v1/admin/logs/requests/<请求ID>/resources?user_id=<日志所属用户ID>
Authorization: Bearer <管理员登录会话令牌>

详情 data 包含 request_id、task_ids、state、reason 和 items 数组;state 为 ready、pending、failed 或 unavailable。reason 可为 expired、not_retained、unsupported_source、plugin_unavailable、missing_evidence、snapshot_lookup_unconfigured 或 generation_failed;保留实际值,不自动补档或重新生成。items 包含 resource_id、可空 task_id、source、type、mime_type、filename、size_bytes、expires_at 与相对 content_url;未知大小或到期时间为 null,多文件以数组处理。content_url 受保护,不是匿名 capability 或供应商 URL。

详情和文件只接受有效原生登录会话;管理员还需启用账号及实际管理员角色(10 或 100),PAT 和推理 Key 不可替代。资源不存在或不属于所选用户返回 404,关联证据不完整或有歧义返回 409;存储故障不能伪装为空结果。读取前会重新鉴权。文件完整读取为 200,单段 Range 可返回 206,越界为 416,未完成为 409,过期为 410,下载并发繁忙为 429;无效或多段 Range 返回 400。保留实际 MIME、Content-Length、Content-Range、Accept-Ranges、安全的 Content-Disposition、Cache-Control: private, no-store 与 X-Content-Type-Options: nosniff。

浏览器应通过同源 BFF 转发本人 Authorization: Bearer <登录会话令牌>,不要把令牌放在 URL。跨域 img/video 地址不会自动携带 Bearer;图片可授权 fetch 后使用 Blob URL,视频和音频宜由 BFF 流式转发 GET、HEAD、Range 与 If-Range。下载上限为 512 MiB、120 秒,每进程最多 8 个并发、每操作者最多 2 个;网关和反向代理可能更严格。

支持原生任务产物及保留的 Playground 同步图片、非流式音频和转录/翻译文本;同步快照最多保留 24 小时、4 MiB。本人 URL 型同步图片经原生归属检查读取,跨用户管理员不支持该来源。未保存的普通 /v1 同步响应、仅有旧外部地址的部分产物、过期或未保留快照无法据此恢复。可选只读视图及 ONEASTER_LOG_RESOURCES_POSTGRES_DSN 未配置时,公开日志中已有 task_id 的任务仍可能查询,同步快照及仅有私有关联的任务可能不可用;列表存储故障可降级为 unknown,主动详情的存储故障返回脱敏 503。配置与正式环境可用性尚需核实,不代表已启用永久归档。

安全渠道配置与模型更新

渠道 Facade 使用调用者自己的原生 Bearer 身份,逐次执行原生管理员角色和权限检查,不使用共享 Root 凭据。权限与 PAT scope 是不同的约束:PAT 不能提升账号角色或权限,推理 Key 不能替代管理身份。列表、详情、类型和配置读取需要 channel.read;创建需要 channel.sensitive_write;普通配置更新和 upstream-apply 需要 channel.write;Key、base_url、override 等敏感变更还需 channel.sensitive_write;测试、状态切换、discover-models 和 upstream-detect 需要 channel.operate;插件选项和插件绑定需要 task_plugin.bind。部分操作先读渠道或写后回读,因此也需要 channel.read。使用 PAT 时,还须具备每个实际原生调用所需 scope,例如 channel:read、channel:write、channel:operate、channel:sensitive_write 或 task_plugin:bind;权限检查不会被 scope 代替。以当前账号实际权限为准。

- GET /oneaster/v1/admin/channels/types 返回本地类型及安全的默认地址(不安全地址为 null),不探测连通性。

- GET /oneaster/v1/admin/channels/plugin-options 返回本地注册项的 key、name、models、new_api;new_api 表示本地插件支持该上游类型,不能证明上游安装了插件。

- GET /oneaster/v1/admin/channels/{id}/config 返回安全投影 channel、setting、settings、header_names、param_override_present,不返回原始凭据、任意原生 JSON 或 header 值;不安全或无法可靠解析的存量配置会失败。原生渠道 Key 明文读取是独立高风险操作,要求 Root 和绑定 channel_id、scope 为 channel.key.read 的一次性安全证明;配置投影不提供此能力。

- PATCH /oneaster/v1/admin/channels/{id}/config 仅接受非空的 channel、setting、settings、headers、params 白名单字段;未提交的字段保留。setting 支持 pass_through_body_enabled、responses_websocket_enabled、task_plugin_key、task_extend_plugin_keys;settings 支持 upstream_model_update_check_enabled、upstream_model_update_auto_sync_enabled。插件绑定仍受原生权限约束。

- headers 与 params 分别使用 {"set":{...},"remove":[...]};header 只允许 accept、content-type、user-agent、x-request-id、x-client-version、anthropic-version、anthropic-beta、openai-beta,值仅写入不回显。params 只接受安全名称和平面标量。未知和复杂存量项保留,但不能直接查看或编辑。已有多 Key 渠道不能通过此接口替换 Key;其他编辑保留其多 Key 信息。models 不能通过更新清空;原生指针字符串字段可传空字符串清空。

- POST /oneaster/v1/admin/channels/{id}/discover-models 请求体为 {},仅在显式调用时联系已保存渠道的上游,返回 models,不保存返回模型。

- POST /oneaster/v1/admin/channels/{id}/upstream-detect 请求体为 {},返回 add_models、remove_models 和 last_check_time;原生处理会持久化检测结果,但不会自动应用。

- POST /oneaster/v1/admin/channels/{id}/upstream-apply 接受可选数组 add_models、remove_models、ignore_models,并修改渠道模型配置。detect/apply 遇到不兼容或未知的已有 settings 会返回 409,避免原生固定结构丢弃配置。

POST /oneaster/v1/admin/channels 创建单个渠道,必填 type、name、key、models、group;类型 61 还需要有效的 setting.task_plugin_key。旧 PATCH /oneaster/v1/admin/channels/{id} 拒绝原始配置字段及 setting/settings,结构化配置应使用 config;状态变更使用 POST /oneaster/v1/admin/channels/{id}/status,输入 status 为 1 或 2。列表带 keyword、model 或 tag 时最多扫描 1000 条:超限返回 422 channel_search_limit,扫描期间列表不一致返回 409 channel_search_changed;keyword 匹配名称或精确 ID,不搜索 Key 或 URL,tag 精确匹配。total 和 type_counts 描述过滤后的扫描结果,并非全库健康指标。

原生读取、合并、写入没有 CAS 或跨实例原子冲突保护;协调并发操作并重新读取。创建、配置、状态、detect 或 apply 的原生 HTTP 200 success=false 可能发生在部分写入之后,Facade 可能返回 409 channel_result_unknown;断线、超时或写后回读失败也不能证明未保存。先重新读取并人工核对,再决定后续操作,不自动重试写入。真实原生 403 保持权限拒绝,业务失败不能仅凭文本推断为 403。

Stripe 风险与安全行为

GET /oneaster/v1/admin/stripe/risks 及后端仓库 CLI 的 stripe-risks list 仅接受有效原生 Root 登录会话;普通管理员、PAT 和推理 Key 均被拒绝。该只读投影最多返回最近 100 条,scope 为 recent_up_to_100;user_id=0 表示未关联,resolved_at=0 表示该条未解除。空列表或单条已解除不能证明全部风险解除。CLI 不查询 Stripe、不解除风险,也不输出 reason、金额或全量总数;--dry-run 不读取凭据或访问网络。

原生 GET /api/stripe/risks 包含 reason;高风险的 POST /api/stripe/risks/{event_id}/resolve 单独要求有效 Root 会话和 X-Security-Proof。先通过 GET /api/verify/methods?scope=stripe.risk.resolve 获取可用方法并按实际 MFA 流程重新认证,证明的 scope 为 stripe.risk.resolve,context 绑定同一个 event_id 和 reason;请求 JSON 的 reason 必须一致、非空且不超过 500 字节。证明与会话绑定且一次性消费;已启用 MFA 不可用密码绕过。锁等待超时或存储失败后先核对状态并重新认证,不能自动重放证明。仍有其他未解除事件时限制仍可能存在。

已关联且未解除的退款或拒付风险可使新的付费推理返回 403 payment_risk_hold;风险存储不可用时返回 503。账号仍可登录、查余额及联系支持;风险检查不直接扣钱包或撤销已有资金证据,已接纳的在途任务继续按原账务规则结算。FreeModel 由原生管理员定价与配置识别,预扣为零不保证整个请求免费。

Webhook 根据 Checkout、发票、订阅和 PaymentIntent 的关联记录处理付款与风险,迟到的付款事件可能补齐未关联风险;初次订阅付款缺少必要关联时保持待处理。合法优惠码不改变购买积分数量,实际实付以收银台为准;不能用原价相等条件拒绝合法折扣。原生预览或创建订单即使 HTTP 200 也须检查业务响应。以上是源码行为,不表示正式 Webhook 配置、真实拒付或供应商联调已验收。

MiniMax 图片和语音任务

固定源码中的插件 key 为 `minimax-image` 和 `minimax-speech`,各自声明上游模型 `MiniMax-H3-Image` 和 `speech-2.8-hd`。这只是插件声明,并不证明生产目录已启用同名模型或配置渠道和售价。请求的 `model` 使用管理员配置的公开调用 ID;它与插件 key、上游模型名及展示名是不同概念。以下均为占位示例,不代表实际调用已验收。

开发者使用推理 Key 调用 `POST /v1/tasks/minimax-image` 或 `POST /v1/tasks/minimax-speech`;登录钱包入口为 `POST /pg/tasks/minimax-image` 或 `POST /pg/tasks/minimax-speech`,使用本人有效原生登录 access_token,而非 PAT 或推理 Key。`/pg` 浏览器请求还须满足可信 Origin;为新意图生成并保存 `Idempotency-Key`,断线后用原意图查询恢复,不自动重复创建。两种入口都要求可用的模型绑定、渠道与管理员售价。插件元数据中的专用 route 并非据此即可认定为网关公开路由;也不要假定这两个插件等同于所有 OpenAI 同步图片或音频接口。

图片任务 JSON 示例:

{"model":"YOUR_PUBLIC_IMAGE_MODEL_ID","prompt":"A small paper boat","n":1,"resolution":"1K","aspect_ratio":"1:1"}

图片 `prompt` 必须非空且最多 32000 个 Unicode 字符;`n` 为 1–10,默认 1;`resolution`(或同义的 `area`)为 `1K`、`2K`、`4K`,默认 `1K`,两者同时提供时须一致。`aspect_ratio` 支持 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`9:21`、`3:2`、`2:3`,默认 `1:1`。可指定 `response_format` 为 `url` 或 `b64_json`,但插件上游请求固定 URL 和 PNG,不应据此保证返回 base64;`stream` 只能省略或为 false。当前校验不接受参考图或图片编辑及其他未列出字段。

语音任务 JSON 示例:

{"model":"YOUR_PUBLIC_SPEECH_MODEL_ID","prompt":"Hello from OneAster.","audio":{"mode":"speech","voice":"male-qn-qingse"}}

语音 `prompt` 非空且最多 9999 个 Unicode 字符;`audio.mode` 必须是 `speech`,目前唯一支持的 `voice` 是 `male-qn-qingse`(省略时默认它)。`instructions` 不能包含非空的自由风格指令;不接受额外音频设置或输出格式参数。插件向供应商请求非流式 URL,生成 MP3(32 kHz、128 kbps、单声道)。

提交后保存响应的网关 `task_id`,通过同一入口的 `GET /v1/tasks/{task_id}` 或 `GET /pg/tasks/{task_id}` 查询,再用 `GET .../artifacts` 取得公开产物列表,使用列表中的 `key` 与 `content_url` 请求 `GET` 或 `HEAD` 内容。图片 key 为 `image-1`、`image-2` 等,语音 key 为 `speech`;不要混用供应商 ID。`/v1` 任务读取使用推理 Key;`/pg` 读取仅限本人有效登录 Bearer。浏览器读取受保护内容时须携带对应授权,不能把 Bearer 放入 URL。插件的供应商调用是同步完成,但以网关任务形式记录;结果仍受保存与过期边界约束。`FAILURE`、`UNKNOWN` 或中断不等于可安全自动重新生成。

图片数量与结算

`n` 是请求数量,不保证实际产物数。支持的图片路径在可确认有效产物数量时按实际数量更新结算:部分或多于请求的有效图片会反映实际数量。MiniMax 图片插件以有效 HTTPS 图片结果计数,并要求供应商使用量中的 `generated_images` 与之相符;缺失或不一致的用量不能当作已确认结算。普通 OpenAI 格式图片响应以非空 `url` 或 `b64_json` 识别有效图片;没有可确认数量时保留请求数量,不能假定空结果等于零费用。图片流正常结束才可依据完成事件降低数量,客户端中途断开不能据此降低结算数量;若已观察到更多完成图片则可按更高数量计。失败、预扣释放及异步任务差额按对应原生账务规则和证据处理,不能把所有失败一概视为全额退款。任务数据或产物不保证永久保留;以实际钱包、日志和任务结算证据为准,客户端不自行算价。实际售价和组倍率由管理员配置。

Key 预算

创建 Key 时 `budget_credits` 可省略、为 null 或空字符串表示无限制;有限预算须为可按原生 quota 精确表示的正数,最多四位小数,且受原生额度上限约束。创建预算可以高于钱包余额;它既不增加钱包,也不保证调用时余额充足。实际调用仍受钱包、Key 状态、模型与渠道等规则限制。更新 Key 是独立校验:修改有限总预算时可能因超过可用钱包返回 `key_budget_exceeds_wallet`,或低于累计已用额度返回 `key_budget_below_spent`;不要将创建规则套用到更新。无限 Key 预算也不等于无限钱包。

后端只读诊断 CLI

以下命令在 **oneaster-gateway 后端仓库**执行,使用 Node.js 24+、`ONEASTER_GATEWAY_URL` 与 `--token-file` 指定本人原生登录凭据文件;示例路径均为占位符。文件应为本人拥有的非符号链接且权限 0600。工单和 Stripe 风险命令拒绝 PAT 与推理 Key,CLI 不负责登录或 MFA。

export ONEASTER_GATEWAY_URL="https://YOUR_GATEWAY_HOST"
TICKET_ID="00000000-0000-4000-8000-000000000001" # replace with your ticket ID
npm run admin --prefix oneaster -- support capabilities --token-file /path/to/SESSION_TOKEN_FILE
npm run admin --prefix oneaster -- support list --token-file /path/to/SESSION_TOKEN_FILE
npm run admin --prefix oneaster -- support get "$TICKET_ID" --token-file /path/to/SESSION_TOKEN_FILE
npm run admin --prefix oneaster -- support messages "$TICKET_ID" --include-content --token-file /path/to/SESSION_TOKEN_FILE
npm run admin --prefix oneaster -- stripe-risks list --token-file /path/to/ROOT_SESSION_TOKEN_FILE

`support` 默认只读本人工单;`capabilities` 不接受 `--admin`,`list`、`get`、`messages` 可由具备实际权限的管理员使用 `--admin`;`--user-id` 仅用于管理员 `list`。`list` 支持 `--page`、`--size`、`--status`、`--type`;`messages` 支持 `--page`、`--size` 和 `--include-content`。消息正文默认隐藏,显式开启后仍经过过滤;输出附件元数据,不下载附件。命令不自动翻页、重试或写工单;`--dry-run` 仅校验本地语法和路径。

`stripe-risks list` 仅允许有效原生 Root 会话,读取最近最多 100 条;它不访问 Stripe、不解除风险,不输出 reason、金额或全库总数。空列表不证明全库无风险;单条 `resolved_at=0` 表示该条未解除,`user_id=0` 表示未关联用户。

管理设置与运维观察

普通单项 `PUT /api/option/` 在数据库确认写入与提交后才发布到本进程;数据库失败返回既有错误响应,不发布拟议值。响应丢失或提交时断线可能使结果不确定,先核对持久化状态再决定是否重试;秘密字段可能不在读取响应中。保证仅限该进程的相关写入与刷新顺序,跨实例可能有刷新延迟。个别旧校验路径可能在持久化后运行时解析失败或部分发布,不能把所有错误解释为完全未保存。

KIE 余额与飞书告警是独立运维 worker,默认监控与投递均关闭;源码存在不代表当前部署已启用、已连通或已发出告警。KIE 积分不是 OneAster 钱包积分,余额未知不应填成零;没有失败样本或余额恢复不证明模型实时可用。没有为该 worker 新增公共 HTTP 接口。

重试与 DeepSeek 兼容

标准聊天继续使用 `POST /v1/chat/completions`。网关内部请求体读取与重试的修复不要求客户端增加特殊请求头,也不保证所有请求可安全自动重试:结果不明时先查询已有请求或任务证据,避免重复付费生成。对于走 DeepSeek 适配器的 Chat Completions 请求,发往上游前 `developer` 消息角色转换为 `system`;这是特定适配器的兼容处理,不是所有模型或 Responses 协议的通用角色语义。