SStar Developers
开发者中心/图片分辨率定价
分档积分、报价版本与旧站兼容查看 Markdown

绘画模型分辨率定价与站点接入#

本功能复用既有接口，版本 1 是显式启用的增量合同。2026-09-24 已部署分辨率定价功能，并按运营授权完成 26 条规则的一次性初始化；后续仓库更新不会自动改写人工售价。

价格归属#

  • RokoAPI：模型美元价。管理员填写分辨率表，保存为可执行 v2: 表达式；公开 pricing_display.rates 为表达式的派生结果。
  • Star-Task：用户积分售价。站点规则优先于全局规则；美元价格仅作为换算来源。
  • 历史规则、固定 cost_points、旧 quality=1K/2K/4K 站点不会被批量迁移。只在管理员明确发布新规则时启用严格分档。
  • 公开目录不等于调用授权。前端使用 Star-Task GET /v1/models?view=products&site_id=... 返回的可调用模式及精确 task_model / task_type。

前端报价与提交#

使用既有用户 JWT 鉴权、站点身份及 CORS 约定；不在浏览器持有供应商 Token 或站点定价管理 Token。

http
POST /v1/pricing/quote
Authorization: Bearer <USER_JWT>
Content-Type: application/json

{
  "site_id": "your-site",
  "model": "<modes[].task_model>",
  "task_type": "text-to-image",
  "input": { "prompt": "画一座海边灯塔", "resolution": "2K", "n": 2 }
}

响应仍为现有 ok 包装格式；示例价格仅演示，不是生产售价：

json
{
  "ok": true,
  "site_id": "your-site",
  "model": "<modes[].task_model>",
  "task_type": "text-to-image",
  "cost_points": 10,
  "breakdown": [{ "id": "catalog_rate", "key": "resolution=2k", "units": 2, "points": 10 }],
  "pricing_version": 3,
  "pricing_revision": "<64位十六进制摘要>",
  "normalized_input": { "prompt": "画一座海边灯塔", "resolution": "2k", "n": 2 }
}

pricing_revision 和 normalized_input 仅在新的严格图片规则生效时出现。保留数值型 pricing_version，不要把它改当任务报价锁；它是规则集合的兼容版本。pricing_revision 绑定实际选中的规则、站点、模型、模式、计费参数和总价。

用户改变分辨率、画质、数量或参考图后重新报价。异步报价响应应防止乱序覆盖：只展示与当前参数对应的最新结果。提交前显示“预计消耗 X 积分”；模型卡片的 cost_points / reference_price 仍用于概览，不能代替当前参数的报价。

http
POST /v1/tasks
Authorization: Bearer <USER_JWT>
Content-Type: application/json

{
  "site_id": "your-site",
  "model": "<modes[].task_model>",
  "task_type": "text-to-image",
  "input": { "prompt": "画一座海边灯塔", "resolution": "2K", "n": 2 },
  "options": { "pricing_revision": "<quote返回的摘要>" },
  "idempotency_key": "<本次提交的唯一键>"
}
  • 新站推荐传 options.pricing_revision。价格变化时返回 HTTP 409 PRICING_CONFLICT，且不会扣款；重新报价并让用户确认后再提交。
  • 老站不传这个可选字段，仍按提交时服务端现行规则创建任务。
  • 不传客户端计算的积分；服务端重新计算，供应商预估价格不能覆盖严格分档的站点售价。
  • SDK 新增 client.quoteTask({ model, task_type, input })；现有 createTask 增加可选 options.pricing_revision，不改变返回类型。

参数与结算#

内部 resolution 为小写，大小写输入等价；界面可以显示大写。缺省使用已发布规则的 default_resolution。只有明确支持历史别名的合同才把 quality=2K 当分辨率；真实 quality=high 不与分辨率混淆。

像素尺寸只接受合同 size_to_resolution 的精确映射，不能按最长边自行猜测。不同模型不保证有相同档位；不支持 4K 的模型不能显示 4K。冲突参数、不支持档位、非整数或越界 n 返回 400；严格规则没有“未匹配就用最低价/最高价”的退路。

按张为 unit=output，总价为单价乘 n；按请求为 unit=request，不乘 n。美元转换积分后，在总价处统一取整。任务 metadata 冻结规则、参数版本和报价明细，发布新价不影响已创建任务。成功输出张数可信且少于请求数量时按冻结规则退差额；无法确定数量时保留预扣，不根据猜测退款。全失败沿用现有幂等退款路径。结算积分以 usage 记录为准，任务的 cost_points 仍保留原预扣含义，兼容旧站。

站点后端自定义积分表#

沿用已授权的 /site-api/v1/pricing/models/<TASK_MODEL>，先 GET 当前 etag，再 PUT。使用独立站点定价 Token；该接口不接受浏览器调用。价格是整表覆盖。

json
{
  "expected_etag": "<GET返回值>",
  "pricing": {
    "type": "image_resolution",
    "contract_version": 1,
    "field": "resolution",
    "default_resolution": "1K",
    "unit": "output",
    "prices": { "1K": 3, "2K": 5, "4K": 9 }
  }
}

contract_version: 1 明确启用新规则。省略它保留旧版发布与兜底行为；并非所有历史站点都必须立即升级。field: quality 用于已经通过该字段传分辨率的旧站。默认单位为 output，如需按整次请求收费可选 request。价表须覆盖模型已声明的所有分辨率；如果模型声明只有 1K/2K，不得增加 4K。管理 API 仍要求整数积分、遵守授权 Token 的最低积分限制。

先调用 /preview 检查默认档位、各档位及 n=2，再发布。type: inherit 恢复全局规则。包含独立画质、参考图附加费的复杂零售价继续使用平台管理员结构化规则，不要用这个仅含分辨率的简表意外删除这些收费项。

平台后台导入与自动跟随#

沿用管理员接口：

  1. POST /internal/admin/providers/rokoapi/catalog/<MODEL_ID>/pricing-draft，请求 { "points_per_usd": 100, "update_mode": "manual" }。
  2. 检查返回的 rules_json、完整档位、换算系数及精确目标绑定。
  3. PUT /internal/admin/providers/rokoapi/catalog/<MODEL_ID>/pricing，请求包含 scope: global、target_model、相同的 confirm_model 和 rules_json。

默认 manual，上游调价只提示，不覆盖现有售价。明确传 update_mode: follow 后，后续目录同步重新按同一换算系数生成全局价格，并在同一个 D1 batch 内发布；并发管理员修改受到旧版本和旧规则 CAS 条件保护。无标记的历史规则视为手动。跟随规则属于自动换算价格，不应再手工改其中的单行价格；要保留独立利润/售价请改成 manual。

站点自定义规则始终保留，不参与自动跟随。上游新表缺档、无法安全导入或版本不可用时保留上次完整规则，并增加 pricing_skipped_bindings；新增而未定价的档位会报价失败。取消跟随：生成/发布 manual 草稿。

RokoAPI 发布的 generation_config.resolution_pricing.version=1 使导入草稿包含 input_contract。新模型首次无本地售价时仍按既有默认系数生成初始手动价格；已存在本地规则的模型必须显式生成草稿和发布，不会因本次部署自动改价。

发布与回滚#

  1. 先部署兼容代码；不需要新增数据库表或迁移，不修改已有站点 Token、模型 ID 或路由。
  2. RokoAPI 后台为指定模型填入真实单价、支持档位和默认档位；检查美元目录。
  3. Star-Task 生成草稿，核对积分售价，再显式发布选定的全局或站点规则。
  4. 新前端按报价接口升级；旧前端继续正常提交。
  5. 回滚规则沿用既有站点历史回滚或恢复继承；已创建任务继续用自身快照。

开发验证#

覆盖大小写、历史 quality 别名、像素映射、默认档位、批量取整、缺档/重复档拒绝、部分成功退差、冻结价格、过期报价拒绝、旧站无版本提交、目录跟随和站点覆盖保留。测试不调用付费模型、不修改线上价格。

2026-09-24：首次上线价格初始化#

按本次明确的运营要求，支持 1K 的图片模型将 2K/4K 初始化为同画质的 1K 售价；只生成模型实际支持的档位，Grok 目前不增加 4K。每个站点使用自己的 1K 积分，保留数量单位、参考图附加费、画质差异和旧参数兼容。没有独立规则的模型沿用 model_groups.default_cost_points，不按上游美元价格重新换算。

这是一次性初始化，后续 2K/4K 可分别手动修改。现有旧规则不强制切换严格参数合同，也不自动开启 follow；因此已接入前端无需随此次部署同步升级。已有严格合同则继续使用原合同。

运维工具 scripts/prepare-image-resolution-prices.py 从只读导出的定价、模型绑定生成 apply.sql、rollback.sql 和 expected.json；更新包含旧版本及旧 JSON 比对，重跑不会覆盖后续人工价格。执行后必须重新读取 D1，对比每条预期规则及版本；失败比对时重新审阅，不可去除并发保护。

上线验证结果#

2026-09-24 首次功能上线版本：9bcbe22f-7890-4c6b-8a8b-eb5ebfde98cc。全局及 site-08 共 26 条规则已在 D1 生效，逐条核对价格 JSON、版本、启用状态均一致。另用生产回读规则验证同画质、数量（1/3）及参考图下 1K/2K/4K 的报价一致，26 项通过；原项目全量测试 322 项通过，1 项付费外部集成跳过。健康接口及开发文档已在线验证。

RokoAPI 的 8 个模型美元价已于 2026-09-24 完成部署和初始化；公开目录各档价格、表达式及哈希验证通过。前端继续使用现有参数和服务端报价接口，Star-Task 独立积分售价不会因美元价调整而自动改变。