MG-04-006 图片渠道接口
MG-IMAGE-06（2026-10-15）：当前每个上游 new-api Key 独立渠道，标准型号多渠道调度见 图片调度。本文渠道凭据、映射、归档与发现契约继续有效；旧单层图片直供描述不再作为调度架构。
MG-IMAGE-03，2026-10-15。用户已确认直接复用 new-api 原生图片渠道管理。2026-10-15 起正式入口为侧栏“图片渠道” /supplies/image；模型目录的图片页签与视频渠道菜单均进入同一渠道管理。旧 /supplies/image?model=... 书签仍打开此渠道列表，不恢复模型供给编辑。本批交付渠道管理，不开放图片生成或客户账务接口。
原生实现与本仓映射
固定 new-api v1.0.0-rc.44 / 633b4c5b190dc1af99a2814391354d86948e7943。直接提取原生模型映射可视化/JSON 组件、模型列表解析、映射格式校验和批量前后缀规则，保留 AGPL-3.0 许可证、来源路径与哈希；见 来源记录。组件依赖适配现有 UI、中文与 React 19.1，示例换为图片模型。原生模型列表与映射字段保存到现有 channels.connection_settings，沿用独立管理员会话、加密凭据版本和 PostgreSQL。没有第二套路由数据库。
方法与路径（/admin/v1） | 行为 |
|---|---|
GET /image-channels?include_archived=true | 列表，只返回图片渠道，默认不含归档 |
POST /image-channels | 一次原子创建渠道与供应凭据 |
GET /image-channels/{id} | 单渠道回读；视频 ID 返回 404 |
PUT /image-channels/{id} | If-Match: "version"，一次原子保存全部渠道字段与可选新凭据 |
DELETE /image-channels/{id} | 按版本归档并停用供给，保留历史 |
POST /image-channels/{id}/restore | 按版本恢复，保持停用 |
POST /image-channels/{id}/discover-models | 按版本读取上游目录；不保存选择、不启用、不生成 |
客户端通过同会话/CSRF 的 /backend/image-channels facade 调用；PUT 和上述单渠道写操作在 JSON 中携带 version，由 facade 转为 Go If-Match。Go 管理端继续要求管理员认证，公共服务 Key 不获得权限。未知字段、非法 ID/版本/方法/查询拒绝。
保存字段：name、type（1=OpenAI 兼容，24=Gemini）、base_url、key、models（逗号分隔）、model_mapping（JSON 字符串）、remark、status（1=启用，2=停用）、concurrency_limit。新建默认停用；新建必须提供单个 API Key，编辑时留空保留。读取只返回 has_credential，没有原文、掩码或密文密钥。未知历史协议返回 type=0，编辑须显式选择支持的协议，不静默归类。
示例模型列表 gpt-image-2，映射 {"gpt-image-2":"gpt-image-2-cc"}。映射键必须属于调用模型列表，键与目标为精确模型名；目标不必同时出现在调用列表。重复键、空目标、非法 JSON、原型保留键和隐藏空白拒绝。批量规则由原生模块展开为明确映射后保存，不引入运行时正则规则。
保存与执行边界
保存、凭据轮换和审计在同一事务完成；并发版本冲突返回 409，不自动重发，界面保留当前草稿。审计失败则全部回滚。旧凭据仍可按原版本读取供在途执行使用。切换协议、地址、模型/映射或凭据会暂停此图片渠道的供给并失效其就绪状态；普通名称/备注不重写执行身份。
渠道启用仅为渠道准入状态，要求有效供应凭据；不会创建或启用 Supply，也不代表模型生成验收通过。供给验证/启用与完整图片执行集成仍独立。归档/恢复保持历史引用；视频和旧图片生成/供给管理端点的既有边界保持。
目录读取使用已有 OpenAI/Gemini 目录适配器，复用网关公共网络传输的 DNS 固定与私网拒绝；禁止重定向，单响应最多 2 MiB、HTTP 30 秒、总操作 35 秒。读取配置版本变化时返回冲突，不能把旧目录应用到新配置。连接与目录成功不是生成证据。所有 Provider I/O 位于事务外。
客户组、Key、钱包、销售价、旧 Ability/Priority/Weight 和渠道亲和度不移植。MG-IMAGE-01 的旧渠道盘点与两次直连证据保留，不能自动迁入为本服务已启用渠道。
验证与发布
实现、测试、隔离浏览器证据和发布状态见 任务记录。本批无需 Migration；生产发布后仍须单独配置/迁入渠道并按实际模型验证。回退代码保留图片渠道配置、凭据、任务和历史数据。
2026-10-15 渠道级供给与重新接入
用户确认图片供给直接以渠道为单位，不再维护旧图片盘点的模型级供给、规格、档位与独立保存。每条渠道持有自己的协议、地址、凭据、模型列表/可选精确映射、启停和并发；同一渠道内多个型号不再展开为多条供给管理记录。视频规格与分辨率调度不变。
React 不再挂载历史 ImageProvider/ImagePage/ImageCatalog；旧盘点与工具源码只保留档案。Console 启动不再读取/生成本机 image-supplies.json，也不从历史 evidence 自动导入供应商。经管理员鉴权后旧 GET/PUT /backend/image-document 明确返回 HTTP 410 image_supply_document_retired，写请求仍须 CSRF；已有本机文件不会被读取、覆盖或删除。新管理端只保存 PostgreSQL 的 image-channels。
用户指定仅重新连接 tuba、vakv；其他供应商不重新导入。旧网关读取为 SELECT，不能改写原应用账户或任务。当前图片渠道按版本归档后新建连接，历史凭据/任务引用保留。两家按实际协议/账户保存，不能因为同域名就合并密钥：tuba GPT（旧 133）、vakv GPT（旧 131）、vakv Gemini（旧 136）。旧 135 把 GPT 型号填在 Gemini 协议中，明确不恢复；旧 132 为另一 tuba 账户，本轮未选择。
重新保存连接、鉴权目录成功和真实图片生成是独立状态。重连不开放公共图片生成端点、不自动启用供给、不发起收费生成；新渠道默认停用，目录读取使用既有安全传输。最终实际重连/验证见 MG-IMAGE-04。
图片目录客户端的可选 DNS 配置
默认继续使用系统 DNS 与现有公网传输保护。当隔离开发环境的代理返回 fake-IP 时，可显式设置 GATEWAY_IMAGE_CATALOG_DNS_OVERRIDES，值为 JSON 对象，例如 {"catalog.example":["93.184.216.34"]}。仅图片渠道的 OpenAI/Gemini 目录读取使用此客户端；视频执行、结果下载、TOS、系统 DNS 和其他应用均不变。未设置时保持原行为。
配置最多 16 KiB、32 个精确域名，每个最多 8 个公网 IP；拒绝 IP 域名、通配符、无效名称、重复规范域名及任何私网/保留地址，错误配置阻止启动。未列出的域名仍走原 DNS 并检查全部结果。与测试注入 HTTPClient 同时配置会报错，避免覆盖测试传输。TLS 主机名/SNI、证书校验、固定目标 IP、禁代理/禁重定向、30 秒及 2 MiB 限制保留。
这是运行环境配置，地址变更须先核验运营商的当前公网解析并更新；不把 IP 改写为渠道 API 地址，也不允许使用本设置绕过安全规则。本轮只写入共享预览的私有 state/image-catalog-dns.env，并由该 API 启动脚本读取；不修改生产配置。修复系统 fake-IP 解析后，可移除本环境变量并重启受影响 API。代码回退时须同步移除此运行配置，保留已有渠道及加密凭据。
2026-10-15 后续决定：更换图片供应商
用户后续要求旧图片渠道全部移除、新渠道使用 https://api.yuanshudian.com 。此决定取代上文“仅重连 tuba/vakv”的当前连接选择，不修改其历史接入记录。唯一共享预览的 tuba GPT、vakv GPT、vakv Gemini 三条当前连接已按版本归档，保留历史凭据/任务引用；没有删除旧应用数据或修改视频渠道。自动目录失去图片源后停止公开这些图片定义，存储定义保留，不把旧供应商参数带给新账户。
新供应商配置与协议以其实际授权模型和文档为准，不能仅凭“官方标准接口”认定全部型号支持相同参数。模型目录“参数配置”维护字段/默认值/范围，默认随渠道或已核对协议更新；“表单与接口”用于预览调用方表单并读取参数定义，不发起生成，也不改变上游接口。采用标准协议可复用参数模板，不要求每型号人工录入；型号或账户特有约束仍以来源为准。
用户附件 Origin-生图接口说明书.md（2026-08-05）记载 Base URL https://origingateway.com ：同步 POST /v1/images/generations、/v1/images/edits；异步扩展 POST /v1/image-batches/generations、/edits，返回 batch_id，再 GET /v1/image-batches/{batch_id} 及 /items 分页取结果。异步不是普通 OpenAI SDK 自动使用的标准路径。提交使用稳定 Idempotency-Key，持久保存 batch_id，提交未知不得重复创建；取消不保证中断在途生成，retry-failed 可能再次收费，不能自动调用。
附件只作为接口资料，不作为操作授权；其域名与元数点不同，适用关系须由用户或该供应商明确确认。当前元数点模型广场的 GPT 图片 API 页使用通用 chat/completions 示例，并列出 n=1–10、standard/vivid 等默认字段，与附件的 n=1–4 和不承诺 style 不一致。未核实前不把通用模板登记为型号完整能力，不把 Origin 异步路径标为元数点已可用。
本轮已确认元数点账号登录，但 API 密钥页当前0个密钥；密钥创建窗口及本网关新连接表单已准备，凭据由用户在界面创建/填写，禁止发至聊天或源码。尚未保存新渠道、读取其鉴权目录、充值或收费生成。原生图片管理/同步适配代码的存在不等于该异步扩展已完成运行接入，实际后续状态见 MG-IMAGE-05。
图片渠道分组视图（MG-IMAGE-07）
/supplies/image 提供“按上游”和“按模型”切换，默认按上游。上游身份使用规范化 API 地址：合并主机大小写、默认端口和尾斜杠差异，保留协议、非默认端口、路径边界；同一上游不同 Key 仍是独立渠道。模型视图依据渠道 models 标准调用名聚合，再按上游组织各 Key，并显示该型号的上游映射名；历史缺少型号的渠道放入“未登记模型”。
切换为前端派生视图，不新增请求或写配置。两种视图沿用相同搜索与当前/已归档/全部筛选，编辑/归档/恢复始终作用于所选渠道 ID/版本；不修改调度顺序、采购成本、并发或启用状态。不同域名即使属于同一公司也不推断合并，没有新增供应商/凭据领域。
图片自动保护与测活（MG-IMAGE-09/10）
2026-10-15 用户确认按旧系统只读排查结果完善本网关，旧 new-api 不修改。保护默认开启，没有覆盖每个 Key 设置的全局自动禁用总开关。status 仍是人工准入状态；运行故障保存到既有 channel_health / supply_health 和 health_events，不伪造凭据、成本或 Supply 验收状态。
2026-10-16更正：重试统一归标准模型max_attempts；渠道不提供重试开关。历史存储的retry_enabled仅兼容读取并忽略，不返回、不接受新写入，不批量改写旧渠道。模型配置入口见图片调度。
POST/PUT 图片渠道增加可选 automation，省略时保留已有配置，新渠道/历史未配置渠道采用下列默认值。部分对象由 Go 按默认值补齐；控制台始终提交完整对象。修改策略沿用渠道版本/CAS、凭据加密和审计，不使已验收供给失效。
{"auto_disable":true,"failure_threshold":3,"cooldown_seconds":300,"probe_enabled":true,"probe_interval_seconds":300}failure_threshold1–20；cooldown_seconds/probe_interval_seconds30–86400 秒。显式关闭自动保护时列表会显示该状态；不是系统总开关。- 上游余额不足（包括 new-api HTTP403
insufficient_user_quota/ 预扣费失败）或鉴权失败：第一次即把该 Key 的运行健康标记为disabled。同域名其他 Key 不受影响，人工配置状态与已有任务保持。 - 明确模型不存在/无权限只对该 Key × 标准型号的 Supply 立即熔断；普通模型5xx、账号池繁忙/429按连续故障阈值熔断。网络/连接/超时按 Key 计数。内容审核拒绝、参数错误、调用方取消及本地存储问题不损害渠道健康。
Retry-After最多延长24小时冷却。 - 冷却不等于恢复。两次鉴权/目录检查成功后，允许冷却到期的 Key 或目录仍含该上游型号的 Supply 进入单并发
probing；实际生成连续成功2次后进入渐进恢复，累计5次才恢复完整并发。目录检查不计入真实成功率，不启用或验收 Supply。鉴权自动停用可经检查进入试运行；余额停用必须由管理员充值/修复后显式恢复，目录200不能证明余额足够。 - 每次创建图片容量租约，PostgreSQL 在渠道锁下重新核对当前人工准入、供给就绪、健康和实际租约数量。旧 Planner 或 Redis 中的较高并发值不能绕过自动停用或单并发试运行。新供给仍默认停用/未验收。
GET 列表/详情和写操作回读增加 automation、automation_status。后者包含 Key 健康快照、连续故障、冷却截止、目录检查时间/结果码/退避计数，以及异常模型供给的健康快照。status=1 与 automation_status.health.state=disabled 表示人工准入开启但 Key 已被自动保护，不能据 status 单字段判断可用性。
新增 /admin/v1/image-channels/{id} 动作，浏览器使用同名 /backend facade，沿用独立会话、CSRF、同源限制和 If-Match：
| 动作 | 内容与约束 |
|---|---|
POST /check | 非收费鉴权/目录测活；If-Match为当前渠道版本。控制台JSON仅传version，Go不需要请求体。人工停用/归档不测试，正在测试或版本改变返回409。返回包含真实检查结果的渠道快照；HTTP200只表示检查完成，不能据此判定测活成功。 |
POST /resume | If-Match渠道版本，Go JSON {"health_version":2}；控制台额外传version。只允许将当前自动停用/熔断的 Key 恢复到单并发试运行；人工停用/归档不能被绕过；双版本不匹配返回409。记录健康事件，不重新提交任何历史任务，也不启用 Supply。 |
测活由 API 进程的专用目录监视器执行，15秒扫描，每轮至多2条、逐条执行；不启动图片/视频生成 Worker。每 Key 使用 PostgreSQL token/45秒租约，检查总超时35秒、回写超时5秒；错误指数退避最多24小时，配置/凭据/租约与健康版本共同阻止陈旧检查覆盖真实故障。Provider I/O 不在事务内。归档、人工停用和关闭定时测活的渠道不进入自动队列；单次目录失败保存安全错误码，预期失败不循环刷错误日志，基础设施周期错误每分钟至多记录一次。
复用既有 OpenAI/Gemini 安全目录客户端与公网/DNS/响应大小保护，不保存原始错误体、密钥或签名URL。目录缺少接口/不支持目录不是单个图片模型故障，不据此禁用其他型号。定时测活不修改模型映射、目录定义或采购参数。
参考来源：Source-Repo https://github.com/QuantumNous/new-api；Commit 633b4c5b190dc1af99a2814391354d86948e7943（v1.0.0-rc.44）；Paths service/channel.go、controller/channel-test.go。Adaptation：借鉴自动/人工停用区分和错误语义，用本网关原生健康事件、租约、成本与单次换供给规则实现；没有移植客户账务、旧Ability或运行平台，未直接复制这两个Go文件。既有原生前端提取组件许可证与出处保持。
迁移037仅新增image_channel_checks的检查结果与租约表；不改变既有供应、任务和凭据。应用回退保留该表及记录，down仅推进迁移标记、不删除历史；再次up幂等。不要将应用回退等同于新表已删除，不支持直接降级销毁业务数据库。
供应商 → 系列 → Key分组（MG-IMAGE-11，2026-10-16）
渠道页按精确API端点归供应商，同地址下Key仍是独立渠道；supplier_name为可选显示名，保持不同协议/路径/端口身份，不按显示名合并端点。点击供应商后左侧显示GPT/Gemini/Grok/Seedream系列，右侧显示本系列Key分组、具体型号及可调用分辨率范围。原编辑/归档/恢复/测活/手动恢复和CAS不变。归档Key不自动复活。
POST/PUT新增可选resolution_ranges: {"gpt":["1K","2K"],"gemini":["1K","2K","4K"]}与supplier_name。使用现有connection_settings持久化；省略保留旧配置，空数组明确表示本系列范围未配置，不能当作全部分辨率。只接受已知系列和不重复的1K/2K/4K。新增编辑可按系列加入全部已登记标准型号，保留逐型号精确映射。
范围变化属于执行能力变更，在同一渠道锁事务中撤销该Key旧Supply的启用/就绪，防止陈旧Planner越过新范围；仍需核对和重新验证能力后启用。历史没有范围字段时保留既有能力契约；进入系列统一管理必须配置范围。空对象与历史无字段等价，不因保存显示名制造能力变更。采购成本/并发/分辨率顺序在系列调度中配置；系列重试不回到Key表单。
MG-IMAGE-14：标准协议与完整目录（2026-10-16）
现行协议选择为 type=1 OpenAI 生图兼容接口、type=24 Gemini 原生接口，两者均可新建。供应商名称和是否部署 new-api 不决定请求协议：OpenAI 目录用 Bearer + /v1/models，Gemini 目录用 x-goog-api-key + /v1beta/models 并分页；执行分别复用既有 OpenAI images 和 Gemini generateContent 适配器。默认地址为相应官方根地址；自定义代理地址按管理员填写保留。
管理员 discover-models 返回该 Key 目录中所有有效型号，包含无法从名称判断类型的别名。识别为图片的条目保留 media_type=image，其余为空/省略；未分类不表示图片生成能力已确认。此完整读取选项由服务端为图片管理员发现设置，不作为渠道配置写入；其他适配器调用/定时检查保留原默认过滤。安全传输、响应大小、分页上限、总超时和版本冲突保护不变。
同名标准型号可加入关联草稿，但已有 标准型号→上游别名 映射保持；管理员明确选择同名上游时删除该标准型号的旧映射，回到同名直传。显式选择新别名会替换该标准型号的单个目标，其他映射保持；保存后生效。目录加载错误显示给管理员；地址、Key或协议草稿变化清除旧目录选项；显式填写Key可直接按草稿拉取，沿用已保存Key时须先保存当前配置再拉取。标准目录加载失败时禁止自动关联，手动原生模型映射编辑仍保留。
该管理修正不表示 /v1/images/edits、任意上游私有扩展或真实收费生成已经验收。原生执行适配器的能力和现有生成入口边界保持，真实 Key 目录/生成需分别验证。
参考：Source-Repo https://github.com/QuantumNous/new-api；Commit 633b4c5b190dc1af99a2814391354d86948e7943（v1.0.0-rc.44）；Paths controller/channel.go、relay/channel/gemini/adaptor.go、relay/channel/openai/adaptor.go。Adaptation：沿用协议分派、完整目录与精确模型映射语义，在本网关原生适配器和原生存储修正，未复制 Go 源码；已有前端提取组件及 AGPL-3.0 来源保留。
新建图片渠道可先调用 POST /admin/v1/image-channels/discover-models（浏览器 /backend/image-channels/discover-models），JSON仅允许 type、base_url、非空单个 key，不携带版本/渠道ID。返回 {models:[...]}，同样按35秒总超时、HTTPS和安全目录传输读取。未保存的Key仅用于本次请求，不保存渠道/凭据/快照或标准型号，也不创建供给；API不回传Key或上游原始错误体。沿用管理员会话、同源和CSRF，无新公共或匿名入口。新建按“协议/地址/Key → 拉取 → 关联标准型号 → 保存”操作，名称与型号无需在拉取前填写；更换Key的编辑草稿可同样预先读取。未填写新Key则使用既有单渠道版本化发现接口，只读取已保存连接。
MG-IMAGE-18：上游型号选择后映射（2026-10-16）
图片渠道表单按new-api v1.0.0-rc.44的上游型号发现/勾选/映射流程组织：先填写协议、API地址和Key，再“拉取上游模型”，在本次目录结果中勾选需要接入的型号，最后关联标准模型并保存。拉取本身不自动勾选或写入型号。明确勾选同名且协议匹配的型号时可默认同名关联；别名需选择对应的标准调用名；原有别名不会因发现同名型号而被覆盖。移除“加入全部标准图片模型”和“添加模型系列”，标准目录只作为映射目标，不作为上游支持证据。
新增或改动连接/型号映射的草稿必须有当前连接拉取成功的目录；选中但未映射、上游未返回的目标或协议错配标准型号阻止保存。新目录中缺失的旧目标明确标注，必须由管理员取消，不静默删除历史关联。高级模型映射保留既有new-api可视化/JSON/批量工具，但同样检查标准调用名和精确上游目标；批量规则作用于已选上游型号，不把未经验证的别名加入标准目录。
已保存渠道只改名称、备注、并发、分辨率或保护策略时无需强制重新读取上游；名称等元数据草稿不再阻止使用已保存Key拉目录。修改地址或协议后原目录失效，需填写对应Key按新连接重新读取；新Key只在请求内存及最终加密保存路径流转。目录失败和空目录明确显示，不能回退为全部标准型号。渠道类型文案改为“OpenAI 标准生图接口”，协议type=1及API字段保持不变。
Source-Repo: https://github.com/QuantumNous/new-api；Source-Commit: 633b4c5b190dc1af99a2814391354d86948e7943；Source-Paths: web/src/features/channels/hooks/use-channel-model-discovery.ts、components/upstream-model-selection.tsx、hooks/use-channel-mutate-form.ts。Adaptation: 参考发现与选择分离、保留旧选项及别名的交互，在已有网关组件内实现；沿用原生标准模型目录、加密凭据、CAS和现有AGPL映射组件，不复制客户/分组/账务或路由领域。后台models字段仍是标准调用名、model_mapping仍是调用名到上游精确名，不改变API持久格式或生成执行协议。此节取代此前表单“加入全集/系列”和拉取自动加入同名型号的界面描述，不批量改写已保存配置。