模型门户、试用与核账

1.1候选的身份、流式交付、冻结费用、V2四项和共享月预算合同。

本文件描述本分支源码和隔离验证可审查的接口；不证明生产已部署、真实供应商/支付渠道或所有 profile 已验收。匿名目录可见、HTTP200、流终止、desired价格已保存都不能替代当前执行和财务准入。会员订阅/OAuth SDK 与个人 PAYG API Credits 分账。

目录、身份与代码

官网 /zh/models、/en/models 使用 GET /api/open/v1/catalog/entries 同一公开投影；详情路径是 /<locale>/models/<publicKey>，对比最多4项。publicKey=m-<UTF8业务模型ID的无padding base64url> 仅供公开地址；执行选择具体 profiles[].id UUID、wire及已声明参数。组合筛选必须由同一 profile 同时满足。标题/maker/双语描述由 docs/api-open/model-portal-metadata.json 显式登记，通过 scripts/sync-model-portal-metadata.mjs 生成两应用副本；未登记显示原名称，不捏造模型清单或厂商。

公开响应 {version,observed_at,data} 为raw DTO；30秒缓存/ETag。目录观测超过60秒时保留只读数据并禁试用，刷新不能把旧 observed_at 洗成新数据。protocol_supported、对应合同的财务/price ACK、release receipt与有效输出上限分别判断。known_bad健康不是永久禁用，固定渠道仍可能由服务端 HALF_OPEN 探测；busy/unavailable保留503。性能过期/样本不足与目录过期分开。

V1参考价显示 Credits/百万总TOKEN（含cache）；原HTTP端点仍以Credits/总TOKEN的来源费率计量。金额用十进制字符串，不能用浮点放大后舍入。0只有价格ready且有显式 free_reason 才标免费；未知价格显示 —。

门户按所选UUID/wire生成curl及Go/Rust HTTP样例。官方客户端锁定 openai@5.12.2、@anthropic-ai/sdk@0.60.0，只在真实 capabilities 的 compatV1Enabled=true 且wire匹配时开放页签；否则使用 /api/open/v1/models/<UUID>/chat|anthropic。OpenAI SDK baseURL是 https://acosmi.com/v1，Anthropic SDK baseURL是 https://acosmi.com（SDK自己加 /v1/messages）；x-api-key独立开关关闭时同时设置 Authorization: Bearer $ACOSMI_API_KEY。示例只含环境变量占位和固定演示prompt，不含页面Key、Cookie或用户prompt；不要给模型执行配置自动重试。

新增 channel UUID通过 acosmi_options.routing={mode:'fixed',channel_id} 显式选路；priority是服务端人工配置顺序，不是最便宜/最佳/语义路由。管理员 sortOrder 越小越先，UUID稳定处理同优先级。新渠道默认关闭、legacySelectable=false；会员/default、旧SDK、工具/工作流读者仍走legacy名单。更换adapter/wire/origin需新建profile，不能原地让旧任务改投。

浏览器试用与请求核账

浏览器默认执行路径 /zhuanqian/api/console/playground/chat（代码逻辑route /api/console/playground/chat）固定转发 Go /api/v4/open-api-playground/chat。浏览器发送当前Java Authorization: Bearer、HttpOnly Nexus session cookie、显式 X-Acosmi-Playground-Key、新UUID X-Request-ID，body固定 {profile_id,wire,payload}。BFF先独立验证Java→canonical主体和Nexus主体配对，Go再独立验证PAYG Key的canonical tenant/user、有效性、当前scope；不能先把上下文改成Key owner再比较。payload不能覆盖model/tenant/user/endpoint。写操作只接受同源；反代部署可固定 CONSOLE_PUBLIC_ORIGIN。

Key由用户显式签发24小时个人 models:chat，或从安全保存处粘贴已有Key。明文只保留React页面内存；不写local/session storage、URL、日志。刷新、注销、token更新或换账号清Key、prompt、旧输出及旧回调，并停止接收旧流。清内存不等于吊销。轮换 POST /api/v4/open-api-keys/:id/rotate 返回与签发相同的一次明文，旧凭证不再准入新请求；原hold/历史核账、同 budgetScopeId 的月预算与累计保持，轮换不自动续跑模型。

输出预算默认 min(1024,profile.max_output_tokens)；上限必须已知且为正整数。切换profile重新初始化并提示。Anthropic使用已声明的max_tokens；OpenAI按声明优先max_completion_tokens，否则max_tokens；两者都不声明则不开放。首次仅文本和已支持工具定义，不把媒体/法律执行器接到本Playground。

执行是专用ReadableStream，不能经10秒管理JSON代理或JSON fetcher。15秒无正文显示“仍在等待”，不自动重发；发布需验证正整数 GO_MODEL_EXECUTION_TIMEOUT_MS≤3600000，BFF超时至少Go+30000ms，缺配置返回503。UTF8/SSE分片保留残帧；原生DONE/message_stop仅表示内容交付终止。停止接收、断网、部分输出和丢响应不证明未消费。

本人GET通过固定BFF映射：/api/console/requests/:id→/api/v4/open-api-requests/:id；/api/console/requests?transport_request_id=UUID→Go同query；performance、budget和budget/operations同样固定映射。它们把已配对Java会话转为Nexus bearer，no-store、owner验证，不依赖Key明文或是否吊销。Java本人 /api/distribution/api-credit/requests/:consumeRequestId 返回camel金融记录；Go详情保留snake直接金额和原reservation/finalization/usage/charge_lines。无法证明的旧关联为UNRESOLVED，不能补造。冻结分项核对读取原请求 measurement_schema/effective_price_version/peak_multiplier；费率为Credits/百万Token。rounding_difference 是合同总额减四项展示金额之和，只解释展示舍入，不是现金调整；UNKNOWN_RESOLVED迟到真实usage且完整四行也可确认，未知为null。

费用状态与执行状态独立：RESERVED是冻结，SETTLED是实扣，RELEASED是释放hold（非现金退款），UNKNOWN_RESOLVED是责任终结，FINANCE_CONFIRMATION_PENDING/UNAVAILABLE保持未确认。未知金额用null/—，不填0；hold不与实扣相加。customer_charged_credits、contractual_credits、platform_covered_credits分列，以不可变财务记录为准。

V2四项、观测与预算

V2仅 TEXT_COMPONENTS_V2 / UNIFIED；输入uncached、输出total（含reasoning）、cache_read、cache_write_total按Credits/百万对应TOKEN。无TTL、搜索、request或reasoning附加收费。与V1价域及publication/cursor/ACK完全独立，同业务模型统一客户价格，不以物理channel采购价计算客户账单。

管理员 GET/PUT /api/v4/managed-models/:id/components-price 仅返回窄客户source+ready；PUT {measurement_schema,rates,free_reason,withdrawn}，schema只能 OPENAI_GROSS_READ_V1 或 ANTHROPIC_NET_CACHE_V1；四项均十进制字符串，任意0须free_reason，撤回时rates必须 {}。desired写入不代表ACK/执行ready，不能将V1历史ACK当V2当前版本；公开合同声明还须 pricing_v2.price_status=ready、financial_ready_v2、release_accepted_v2。

用户先对完整本次原生文本参数 POST Java /api/distribution/api-credit/quote：{executionProfileId:UUID,payload}。服务端确定owner/model/计量估计/schema；不接受客户端自报tokens。返回camel contractVersion,priceScope,effectivePriceVersion(正整数),measurementSchema,estimatedHoldCredits(string),outputLimit(string),observedAt。quote不执行provider且只是参考。随后用户另一次显式点击提交 payload.acosmi_options={contract_version:'TEXT_COMPONENTS_V2',expected_price_version:quote.effectivePriceVersion,max_credits:'十进制字符串'}。max默认本次quote hold，不能静默提高；参数或执行修订改变清报价，409PRICE_CHANGED即便降价也必须重新quote并显式运行。服务端重新计算peak/hold、冻结本域价；实扣不超过cap，合同超cap部分列平台承担。

公开 GET /catalog/entries/:publicKey/performance 和本人 /api/v4/open-api-analytics/performance 窗口15分钟，样本域 accepted_payg_text，按profile/channel/config_revision/wire分组，不冒称会员、所有provider或全局性能。execution_success_rate和provider_success_rate保留各自分母；TTFT只认可见正文/工具首内容，非HTTP头/heartbeat。hidden输出或缺最终counter时TPS=null。公开各指标至少100有效样本且最后观测≤5分钟，否则 INSUFFICIENT_SAMPLES/STALE，值显示—并保留窗口/count/observed_at；本人样本不写回公开聚合，也不套公开100阈值。性能不决定费用或单独禁止试用。

执行成功率分母是同窗口全部已准入执行，分子为Go completed且协议完整终止；渠道成功率分母是进入该渠道发送链的全部请求，分子为provider完整成功终止。失败、未知、进行中分别保留count，前置身份/参数/资金拒绝不计入provider分母。TTFT=first_visible_content_at-dispatch_at，reasoning/role事件不计可见首内容；中断前已有可见内容可以保留TTFT并标中断。TPS=final_output_tokens/((provider_terminal_at-first_provider_content_at)/1000)，provider首内容可以含显式reasoning，但隐藏输出/counter范围不符、同步回复、非正时间差或缺counter均为null。P50/P95为nearest-rank ceil(p*n)一基索引，每指标单独计样本；窗口按dispatch_at归属UTC [observed_at-15min,observed_at)，差值用同进程单调时钟。不能用总耗时补造旧记录TTFT。

预算GET/PUT /api/v4/open-api-keys/:id/budget 返回Java camel金额字符串与UTC月份；PUT body {limit_credits:null|string,warning_ratio:string（0.x，1–6位小数且0<r<1）}、UUID Idempotency-Key。null必须是本人明确关闭；0阻挡正hold。确认消费+未终结hold不得越硬限额，轮换Key保留稳定scope。首次reserve冻结UTC月份，跨月/迟到结算归原月；现金退款不冲调用预算。覆盖V1/V2及同scope收费的法律/合规调用。warningIssued表示此scope本UTC月已跨预警阈值，服务端每月持久一次。ACK不可读不成功，保留原operationId，GET /budget/operations/:operationId查APPLIED/REJECTED/PENDING，不盲目创建新PUT。

充值续接与发布边界

继续地址只接受规范 /console/playground?model=m-key&profile=UUID&wire=openai|anthropic，≤1024字符，仅3个query、无scheme/host/fragment/未知键/Key/prompt/身份。API_CREDITS订单 continuationPath 由服务端校验并绑定原owner，其他产品不接受。PAID/PENDING_FULFILLMENT仅表示已付待履约；可信FULFILLED才出现手动“返回模型试用”，不自动调用。换浏览器/刷新后仅恢复model/profile/wire，重新附加本人Key与prompt；组合失效说明原因，不能自动改投。

两个旧模型商店入口共享 /zhuanqian/products，GET/HEAD固定307到相对 /zh/models，丢全部query、不按Referer分流。Acosmi导航直接改“模型API”；法律主题UI配置和独立法律SKU/会员权益入口保留。任何真实provider/付款组合没有发布receipt时仍关闭；本地fixtures、生产编译和目录可浏览不等同生产旅程验收。