MG-04-007 图片调度接口

2026-10-16 条件分档（MG-IMAGE-13，当前）

取代下方MG-IMAGE-11/12的三个分辨率独立调度：1K和2K共用同一顺序，4K单独。仅当系列内所有未删除且登记发布/已有绑定的型号，都有明确枚举的标准分辨率，且每个型号同时区分低档与4K时，才返回两档。存在自由尺寸/未定义分辨率/auto或未知选项/部分型号不区分/任一参数组合没有明确分辨率，则只返回统一调度。仅识别标准image_size/resolution/size的明确枚举（含准确像素尺寸），不根据品牌、型号名、质量或描述推断；组合使用持久标准参数，不以页面并集掩盖不明确组合。

GET系列详情新增服务端dispatch_bands：两档为[{id:"1K-2K",title:"1K–2K",resolutions:["1K","2K"]},{id:"4K",title:"4K",resolutions:["4K"]}]；统一为[{id:"all",title:"统一调度",resolutions:[]}]。页面以此显示，不自行重复推断。统一模式不要求Key配置分辨率范围，也不显示强制分辨率配置或预览尺寸选择；已经明确填写的Key范围仍作为额外能力限制，原生能力/健康/成本/容量门禁不变。

沿用PUT和resolution_orders三个键，避免新的数据库或迁移：两档模式必须使1K与2K数组完全相同，4K只含支持该档的Key；统一模式三个数组完全相同且包含全部选定Key。服务端拒绝独立顺序/错误成员，不只靠前端联动。原生执行元数据记录image_family_dispatch_mode，统一模式所有尺寸/缺省尺寸消费同一顺序；分档模式1K与2K都消费2K顺序。实际型号、尺寸和质量不被改写；显式Key范围仍可过滤统一顺序中的不合格Key。

旧配置只读归并，以原2K次序为共用顺序，其他应保留Key补末尾；存在顺序或执行模式差异返回legacy_configuration，页面提供“应用当前调度规则”并暂缓预览，也可首次实际修改时统一保存，GET不改供应状态/策略。标准定义版本与分档描述进入聚合token，任一成员参数改变都会使旧保存冲突；仅部分成员补齐不能开启分档。已保存执行配置保持版本化，新目录规则在下一次配置保存时持久化；不在读取或启动时自动改历史策略或启用供给。

2026-10-16 视频式调度交互（MG-IMAGE-12）

系列管理API及执行语义保持。页面复用视频调度工作区：左侧系列，右侧1K/2K/4K紧凑列表；当前配置与可用Key候选按范围直接展示，无需先添加再整页提交。勾选选用或点击分组/采购价格集中设置即可纳入系列。选用/成本/型号并发仍为此Key在系列内共用，不伪装为单分辨率覆盖；Key总并发只读。

拖拽手柄或上下方向键修改当前分辨率的顺序，支持按单张已知采购价格排序（精确十进制比较、同价稳定、未知成本在后）、将相对顺序复制到其他分辨率。复制只排列目标已有成员，不引入不支持4K的低档Key。未配置分辨率的历史分组保留明确配置/移除入口。未绑定候选不会因页面读取而创建Supply。

操作后350ms合并改动、串行调用原系列PUT，显示等待保存/正在保存/已保存/保存失败。请求在途可继续勾选或排序，后续请求继承响应的新聚合版本且保留后续编辑。刷新/切换系列/预览在待保存时停用；离页沿用未保存保护。失败保留草稿并停止循环提交，非409支持显式重试或放弃，409仅允许明确放弃并重新载入，不覆盖他人配置。成本/并发与系列重试/策略/币种使用独立设置弹窗，未应用修改不提交，关闭沿用草稿保护。

此变更仅管理端交互，无Go/API/迁移变更；普通配置不触发真实生成、测活或供给启用。

2026-10-16 系列调度基础（MG-IMAGE-11，分档粒度已由MG-IMAGE-13取代）

用户指定管理粒度提升到GPT/Gemini/Grok/Seedream系列，取代下方历史实际型号选择器。具体调用型号仍在统一模型目录中持有参数、官方协议与精确上游映射，不替换为虚构的公共系列模型，不跨具体型号降级。

• /supplies/image/dispatch 选择模型系列，按1K/2K/4K分别编辑Key分组的有序列表；每个分辨率顺序独立。分组单价/计费方式/并发/参与状态在此系列所有分辨率共用；分辨率范围在渠道配置。系列统一重试为不重试或最多一次换Key。
• 2K在低价1–2K Key与1–4K Key间排序；低价明确失败或健康/容量不可用后可选后备；4K排除1–2K Key。实际型号、尺寸、质量不改变，提交未知不重复付费。既有成本币种/预算护栏保持，未知成本不视为免费。
• 上游分组在本网关就是独立Key渠道，同一地址下Key的容量/健康/凭据仍独立；具体型号只在分组型号映射与只读预览中出现，不再作为调度首页选择器。
• 1K/2K/4K范围是独立能力门禁，具体Supply验证后的尺寸、质量、数量与协议限制仍全部满足。像素尺寸按最长边≤1024/2048/4096向上归档；Gemini使用与原生适配器相同的显式质量→imageSize解析，4k不会以基础像素尺寸绕过范围。自动/缺失尺寸无法确定档位时不猜测，受限Key不入选。大于4K不会塞进4K分组。

系列管理契约

独立管理员 /admin/v1/image-families，浏览器 /backend/image-families，既有会话/CSRF/同源/本地客户端保护保持。系列成员以未删除且登记发布或已有绑定的目录型号为准；渠道参数暂时缺失只影响有效表单，不应隐藏系列成员。列表与详情使用同一成员口径。GET列表返回id/title/model_count；GET /{family} 返回version、系列策略/币种/max_attempts、具体型号只读members、groups、available_groups及resolution_orders。

PUT /{family} 同时携带If-Match: "<64位聚合版本>"与JSON：

{"version":"<GET返回的版本>","strategy":"ordered","currency":"CNY","max_attempts":2,"groups":[{"channel_id":"<Key UUID>","enabled":true,"concurrency_limit":2,"cost":{"amount":"0.10","currency":"CNY","unit":"per_image","charge_on":"success"}}],"resolution_orders":{"1K":["<Key UUID>"],"2K":["<Key UUID>"],"4K":[]}}

每档列表必须恰好包含该档可调用的已配置分组，不允许重复、遗漏、额外Key或伪造范围。范围未配置的Key不能作为启用分组保存。Key仍只对其明确登记的具体型号生成绑定；不凭系列名给Key添加未声明型号。

聚合版本包含目录成员/版本、实际模型、Key及供给版本、映射、范围、策略与成本；不包含易变时间戳和健康计数。保存先按ID锁目录与Key，再复用原生逐型号Supply/成本/能力/绑定/CAS写入，在同一事务提交；中途或最终审计失败全部回滚。无第二套路由数据库和新迁移。分辨率顺序与系列标记放在已有执行模型的版本化public_capability，真实Planner消费该顺序；所有成本/健康/容量/Attempt仍原生。新能力或采购资料仍使Supply待验证，不因系列保存启用供给。

历史独立型号配置可读；如不一致返回legacy_configuration=true，管理员保存后按当前系列配置统一。已标记系列托管的型号拒绝旧逐型号PUT，避免旧已打开页面覆写系列策略。新增目录成员或Key/范围变化会使旧聚合版本冲突，需刷新核对；未自动给新型号制造供给验收。

POST /{family}/preview：{version,catalog_id,failed_channel_ids:[],request:{size,quality,n,response_format,reference_count}}，型号必须属于系列、最多模拟一个已有Key不可用；前后核对聚合版本，复用真实图片Matcher/健康/成本/容量Planner，只读不创建任务/Attempt/租约/决策日志，不调用Provider。

历史逐型号原生契约（兼容读取与未托管数据）

MG-IMAGE-06，2026-10-15。用户当前决定优先于旧图片渠道级直供设计：上游均为 new-api，每个 Key 独立渠道；一个标准图片型号可以绑定多个渠道，同一个渠道可以供应多个标准型号。

管理入口

• /supplies/image：Key 名称、上游地址、单个加密 Key、所供标准模型、模型映射、Key 总并发。支持从模型目录选择全部标准图片模型，或读取已保存渠道的上游模型目录。新渠道默认停用。
• /supplies/image/dispatch：按标准模型配置多条渠道路线、顺序、采购成本、模型并发和是否参与调度。模型目录的图片“调度”链接携带 ?model=<catalog_id>。
• “按渠道顺序”将每条路线置于独立顺序档；“优先采购成本”将所有路线置于同档，使用既有确定性成本比较，相同时以手动顺序决胜。未知成本不可视为免费，仍由内核排除。
• 模型并发是该 Key × 标准型号的 Supply 上限；Key 总并发由同渠道全部 Supply 共用。0 表示没有可分配容量。并发租约继续由现有 PostgreSQL/Redis 协调器管理。
• 采购单价为十进制字符串，支持 CNY/USD、每张/每次、成功扣费/提交扣费。单个模型所有已知价格使用同一币种；不做隐式汇率换算。每张计价按请求 n 同时放大成功及提交失败成本，每次计价保持不变。
• 新绑定从标准模型目录取得已知参数作为初始能力配置，不将目录元数据标记为上游已验证能力。渠道模型映射变化后须显式同步并保存绑定；编辑规格、接口或成本会使原有供给验收失效。

管理 API

以下均在 /admin/v1 下，保持独立管理员会话/内部管理员权限。浏览器通过同路径 /backend/image-dispatch 窄 Facade，沿用会话、CSRF、同源和本地客户端校验。各端点拒绝查询参数，严格解析 JSON，密钥及验证证据不能通过调度输入写入。

PUT 内容：

{
  "strategy": "ordered",
  "currency": "CNY",
  "max_attempts": 2,
  "channel_versions": {"<channel_uuid>": 3},
  "routes": [{
    "supply_id": "<server-issued_supply_uuid>",
    "supply_version": 0,
    "channel_id": "<channel_uuid>",
    "upstream_model": "gpt-image-2",
    "protocol": "openai-image",
    "enabled": true,
    "concurrency_limit": 2,
    "cost": {"amount": "0.25", "currency": "CNY", "unit": "per_image", "charge_on": "success"},
    "capability": {
      "operations": ["generate"], "resolutions": [], "aspect_ratios": [], "quality_levels": [],
      "min_output_count": null, "max_output_count": null, "max_reference_images": null,
      "response_formats": ["url"], "execution_mode": "sync"
    }
  }]
}

protocol 支持 openai-image 和 gemini-image，同一 new-api Key 可以为不同标准型号使用各自官方协议。所有路线/供给 ID 必须使用 GET 返回值；不允许客户端接管其他历史 Supply。移除路线时 channel_versions 还须包含旧路线渠道，用于比较并交换。浏览器 PUT 外层额外携带 version，Facade 转为 If-Match；Go JSON 不接受该外层字段。

预览内容：

{"version":1,"request":{"size":"1024x1024","n":1,"response_format":"url","reference_count":0}}

预览仅接受规格、数量和参考图数量，不接受 prompt、素材 URL 或图片。返回 configuration_source=saved、model_version、候选成本/容量/排除原因及选择。未保存草稿禁止预览；并发修改返回 409。预览不请求上游，不创建媒体任务、Attempt、决策记录、审计或容量租约。

持久化与不变量

复用 public_models、supplies、supply_bindings、image_capability_versions、cost_rule_versions、已有调度策略与并发租约，不新增第二套路由数据库。Supply 为标准型号 × 渠道的稳定身份，移除绑定保留历史，再添加复用原供给与当前版本。能力/成本变更继续由既有版本化写入函数执行，排序保存不重写验收证据。

事务按标准定义、排序后的渠道、执行模型、Supply 的顺序锁定，校验全部相关渠道/模型/供给版本；晚期审计失败整体回滚。重复提交相同版本和相同配置不产生新版本。成本清空使用显式未知标记，不能重新读取旧价格当作当前价格。

新 Supply 的 enabled=false、production_ready=false、lifecycle=draft。参与调度绑定开关不等同于真实供给验收/启用。保存配置不会启用公共图片生成入口，不会恢复旧渠道，不会执行付费验收；Origin 原生异步提交与恢复仍需单独接入和验证。代码回退保留已有配置与历史引用，无数据库迁移或数据删除。

自动保护与有界执行（MG-IMAGE-09）

图片 Planner、只读选路预览和原子容量准入共同消费既有渠道/供给健康状态。自动保护/测活及恢复接口见 图片渠道。模型故障只排除对应 Supply，Key故障排除该渠道全部路线；同上游其他 Key 独立。

2026-10-16用户更正：图片执行仅由标准模型max_attempts控制重试：1为不重试，2为失败后最多换Key重试一次，适用于该模型全部渠道。渠道不再配置重试，历史Key的retry_enabled不影响执行；一次请求不因同Key下其他Supply重复使用相同凭据。明确的供应拒绝才进入换渠道，采购成本继续按已冻结报价分别记入并约束下一选择。DNS/建立连接之前的确定失败可换渠道；已发送后的读错误、超时、取消、成功响应无有效图片均不会再次付费创建。提交未知持久记录为submission_uncertain；媒体转存失败只恢复已有结果。

现有图片异步包装链路保持20分钟持久期限，等待容量/可用供给/结果转存按租约代次从2秒递增退避、最高60秒，预期等待不作为周期错误日志。期限到达在再次执行/续租前终止并释放Permit；执行上下文也受任务期限和租约到期前5秒的剩余时间约束；每批最多认领当前执行槽数量，避免任务在进程队列中等待到租约失效。已存在的submitting/submitted/unknown或失败Attempt不会因租约恢复再创建任务；已存储输出可按原Attempt恢复。无效或缺少图片的确定结果会终止，不进入无限轮询。

这些约束作用于已有图片执行和异步结果恢复。Origin原生batch_id提交/分页轮询仍未接入，不能将本次后台测活或异步包装等同于已支持该收费协议；公共图片接口仍未挂载。没有真实上游生成验收或生产切流。