MG-04-002 管理API

新渠道使用原生 Go adapter；CHANNEL_PLUGINS.md 仅保留历史记录说明。

原生适配器目录（MG-NATIVE-01）

GET /admin/v1/adapters 返回 data: [{provider_kind, protocols: [{request_profile, adapter_profile, label}]}]，仅列当前二进制已注册的原生视频协议，不包含 js-video。需要管理认证。

新建视频渠道必须选已注册 provider_kind；connection_settings.request_profile 若指定必须属于该适配器。ArtBox 使用 provider_kind=sora-video、request_profile=artbox_video、pricing_profile=artbox。模型发现仅提供选定的协议；导入仍创建停用供给。

以下旧入口返回 HTTP 410 / native_adapter_required：POST /channel-plugins、POST /channel-plugins/validate、POST /channel-plugins/dry-run、GET /channel-plugins/templates/wangpai、PUT /channels/{id}/plugin。GET /channel-plugins 与 GET /channels/{id}/plugin 保留历史查询；历史执行与在途任务不删除。创建新的 js-video 渠道被拒绝。

当前供应管理接口和 UI 保留；新平台员工授权/统一入口按 MG-OPS-01 接入。服务 Key 不是管理权限； 历史客户/价格管理接口不挂载，不能因旧章节存在而恢复。

状态说明：以当前有效边界为准。供应执行规则与历史实现证据保留；客户身份、售价、结算、全量旧跨仓契约及图像开放计划不代表当前验收范围。

当前契约以 D-022 内部视频模式为准：Bearer GATEWAY_ADMIN_KEY，不同于服务调用密钥。 GET /access 返回 {"mode":"internal-video"}；旧账号登录、用户、客户组、客户 Key 和售价接口均为 404。

Base：

/admin/v1

所有写操作记录管理员、Request ID、变更前后摘要和时间。Credential 明文、完整 用户 Key、签名 URL 和素材不得进入审计。

1. 数据看板

GET /dashboard

默认汇总最近 24 小时的图像和视频请求、成功、失败和排队数量。可以通过 from 与 to 指定不超过 31 天的 UTC 时间窗口。响应只包含运营统计，不包含 Credential、 素材、规范化请求、Provider URL 或签名 URL。

4. Channel

GET    /channels
POST   /channels
GET    /channels/{id}
PATCH  /channels/{id}
DELETE /channels/{id}
POST   /channels/{id}/restore
POST   /channels/{id}/credentials
POST   /channels/{id}/test-connection
POST   /channels/{id}/discover-models
POST   /channels/{id}/discover-prices
GET    /channels/{id}/discoveries

列表固定为 media_type=video；图像筛选或历史图像 ID 返回 404。创建必须提交 media_type，该字段创建后 不可修改；新 Channel 默认 disabled。连接测试成功不等于模型 Supply 可生产。

移除为可恢复归档（D-023）。DELETE 与 restore 都要求 If-Match，返回 200、更新后的 Channel 和 ETag；缺版本 428、过期版本 409、未知或图像 ID 404。DELETE 原子设置 Channel 为 archived，并将其所有 Supply 停用且清除 production_ready；不删除凭据、 绑定、价格版本或历史，不取消已创建 Attempt。restore 只恢复 Channel 为 disabled。 同一版本对已归档渠道重复 DELETE 或对未归档渠道 restore 为幂等无操作；过期版本仍 409。 归档期间普通写入/发现/测试返回 409 CHANNEL_ARCHIVED；PATCH 不允许直接写 archived。 GET /channels 与 GET /supplies 默认隐藏归档父级和子项；include_archived=true 显式包含归档项，false 为默认，其他值 400。单项 GET 保留以供历史查看。归档渠道名称仍占用。

5. Supply

GET    /supplies
POST   /supplies/import
GET    /supplies/{id}
PATCH  /supplies/{id}
PUT    /supplies/{id}/video-capability
POST   /supplies/{id}/cost-rules
POST   /supplies/{id}/test
POST   /supplies/{id}/enable
POST   /supplies/{id}/disable

受控测试不进入用户调度、计费、重试或降级链路。图像测试执行一次 Validate + Generate 并下载校验全部结果；视频测试执行一次 Validate + Submit， 使用返回的任务标识轮询到终态，再下载校验全部结果。只有结果大小、摘要、媒体类型和 文件特征都通过时才产生 result_verified。生产门禁按当前 Adapter Profile 和 Capability Version 校验 result_verified；submission_verified 仅保留历史审计， 失败、仅提交成功或旧版本证据都不能启用 Supply。测试证据不保存 Provider Task ID、 结果签名 URL、Prompt、素材 URL 或 Credential。

视频管理表单沿用 supplytest.Request，不增加上游专有字段。先获取供给详情， 用当前 Supply.version 设置 If-Match: "7"（示例），再显式确认一次潜在付费调用：

{
  "video": {
    "prompt": "A paper boat",
    "duration_seconds": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "seed": 0,
    "prompt_enhance": false,
    "reference_images": [{"url": "https://example.test/start.png", "role": "first_frame"}]
  },
  "timeout_seconds": 900
}

示例不代表任一上游支持这些参数；时长/分辨率/比例与素材数量以该供给能力为准。 seed、prompt_enhance、参考素材均可省略，显式 0/false 不得丢失。 reference_videos/reference_audios 与图片数组结构相同，仅使用 reference 角色； 首尾帧角色仅用于图片。表单只接收 HTTPS 素材，服务端素材安全校验仍为最终边界。 等待上限为 1–1,200 秒，缺省 900 秒；超时不表示上游任务已取消或费用已退还。

详情端点当前持久化实现为 { "data": { "Supply": ..., "VideoCapability": ... } }， 外层 Go 字段名大小写需保留；表单也兼容历史 snake_case 详情结构。 测试返回 { "data": { "evidence": ..., "media_type": "video", "outcome": ..., "provider_error": ... } }。 HTTP 200 只说明获得测试响应，provider_failed/timed_out/content_rejected/ invalid_request 不得显示成功。只有 outcome=passed、evidence.passed=true、 verification_level=result_verified 且证据匹配当前供给/Profile/Capability 才显示结果验证通过。 网络异常或不完整响应展示结果未确认，不自动重发。该接口无跨请求持久化一次预算； 重复打开页面仍可触发新的付费调用，迁移验收应继续使用持久化预算 CLI。

启用前服务端验证：

• Channel 和 Credential 有效；
• Capability 完整；
• Cost Rule 可比较；
• 真实测试证据存在；
• Video 真人政策和证据存在；
• Provider Adapter 支持该 Request Profile；
• 没有重复 SKU。

6. Public Model

MG-RESTORE-01：Supply PATCH 增加 supply_family（最多 120 bytes 的渠道内分组名）和 upstream_model。 仅改分组不改变验证；更换原始型号/协议/规格会停用并要求重新验证。If-Match 防止覆盖并发修改。 GET /supplies 附加当前 video_capability（可缺失；版本不匹配时不附加），采用批量查询，不使用迁移观察冒充已核验参数。 绑定增加 priority（0–1000000 整数，默认 0）；策略支持 manual_priority。保存不会自动发布，现有发布门禁不变。

GET    /public-models
POST   /public-models
GET    /public-models/{id}
PATCH  /public-models/{id}
PUT    /public-models/{id}/bindings
PUT    /public-models/{id}/dispatch-policy
PUT    /public-models/{id}/degradation-rules
POST   /public-models/{id}/simulate
POST   /public-models/{id}/publish

bindings 只接收 Supply ID、Role 和 Enabled，不接受能力、价格或 Provider 模型。

不提供客户售价：上游采购成本保留在 Supply，标准模型和独立别名仅承载内部路由。

发布校验：

• 至少一个 Exact Supply；
• 每个 Supply 媒体类型一致；
• 策略和成本护栏完整；
• Degraded Binding 有已验证 Degradation Rule；
• 供内部调用的模型能力与降级披露完整；
• 不校验客户组或客户售价，相关授权留在 new-api。

7. 路由模拟

POST /admin/v1/public-models/{id}/simulate

输入一个真实形状但不提交 Provider 的请求，返回：

• 规范化结果；
• 候选 Supply；
• 每个候选的能力、健康、容量和成本；
• 排除原因；
• 选择结果；
• 是否进入 fallback/degraded；
• 将执行的请求变换；
• 预计累计成本。

模拟不能获得 Capacity Lease，也不能创建 Attempt。

8. 使用记录与任务

GET /records
GET /records/{request_id}
GET /tasks
GET /tasks/{task_id}
GET /attempts/{attempt_id}

同一个详情 API 为统一使用记录页面提供同步和异步差异化数据。

管理员可以查看 Provider Task ID 和脱敏错误，但不能通过普通查询读取 Provider Credential。

异步详情包含 PostgreSQL 只追加时间线，覆盖 queued、dispatch、submit、每次 poll、 retry/reroute、result 和 terminal。管理员事件可以额外显示 Attempt、Supply、 Channel 稳定 ID 及安全错误分类，但时间线本身不保存 Provider Task、Credential、 成本、URL、Prompt、素材或 Provider 响应正文。同步图像详情没有异步时间线。

9. 健康、容量和告警

GET  /health/channels
GET  /health/supplies
GET  /health/events
POST /health/channels/{id}/disable
POST /health/channels/{id}/probe
POST /health/supplies/{id}/disable
POST /health/supplies/{id}/probe

GET  /capacity
GET  /queues

GET   /alerts
PATCH /alerts/{id}/acknowledge

GET /statistics/supplies?media_type=image|video&public_model_id={id}&from={utc}&to={utc}

只读列表使用有界 limit/offset 分页；健康事件和告警支持 from、to，窗口 最长 31 天。未解决告警不会因为创建时间早于查询窗口而从管理员视图消失。

Channel 手工停用阻止全部新 Attempt；Supply 手工停用只阻止该 Supply。已经提交的 异步 Attempt 继续轮询。

statistics/supplies 按 Channel 和 Supply 返回调用量、终态成功/失败、可空成功率、 错误类别/错误码分布、小时或日趋势和最近失败。media_type 必填，窗口最长 31 天； public_model_id 可选但必须与媒体类型一致。响应不包含 Credential、Provider 响应正文、 Prompt、素材或签名 URL。

10. 核心设置

GET /settings
PUT /settings/dispatch
PUT /settings/tasks
PUT /settings/storage
PUT /settings/alerts
PUT /settings/public-api

数据库、Redis、Credential 主加密密钥等部署秘密只能通过环境和部署配置管理， 不通过后台设置。

当前单机 Compose 开发版本中，这组 API 是版本化、可审计的配置权威存储， 响应明确返回 runtime_effective: false；Runtime 接线完成前，修改它们不会改变实时 请求行为。实际运行仍使用部署配置和 Public Model 的调度策略，后台页面必须显示 这一限制，不能把保存成功解释为已经生效。

11. 配置并发与版本

• 写 API 使用版本号或 ETag 实现乐观并发；
• Cost Rule Version 发布后不可改；
• Public Model Policy 和 Degradation Rule 发布生成配置版本；
• 正在执行的 Attempt 使用创建时快照；
• 配置更新只影响后续 Attempt；
• 冲突返回 409 CONFIG_VERSION_CONFLICT。

完整视频配置与选路预览（MG-DISPATCH-01）

PUT /admin/v1/video-configuration 使用独立管理员会话与 CSRF，或管理员 Bearer。 模型集合在一个事务提交，Body 包含 channel_versions: {UUID: version}、variants、 models。各变体字段为 id、parent_id、parent_version、version、resolution、 parameter（空/quality/resolution）、upstream_value、concurrency_limit、 capability（单一规范分辨率）、可选 cost（RuleVersion 形状）。新变体 version=0， 旧变体必须匹配现行版本；不能改用其他父级协议/上游身份。能力中的 max_combined_reference_count 可为未知 null 或非负数量。草稿不继承验收证据。

models 项为 id、version、preserve_published、configuration；configuration 沿用整体模型保存接口。新模型 version=0；preserve_published 只保持已启用并发布且 绑定仍验证的模型，执行语义改变后保存为停用草稿。显式 configuration.apply=true 仍要求完整生产验收。成功为 200 {data:{saved:true}}，版本冲突 409；任何失败全部回滚。 同一渠道模型的变体必须具有相同 tier/manual_order。缺价格为未知，不复用旧价格冒充。

POST /admin/v1/public-models/{id}/video-simulate 接收规范 StoredRequest 字段（如 billing_mode=auto、prompt、duration_seconds、resolution、aspect_ratio、generate_audio）。 模型名以路径 UUID 的现行模型为准，返回 data.model_version 与 data.decision。 候选和排除原因来自同一执行 Planner；停用模型 selection_reason=standard_model_disabled， 不返回可执行首选。该操作只读，不上传/获取素材、提交生成、创建任务或申请租约。

运行状态与启用条件见 供应运行启用链路。

渠道目录型号生命周期（MG-CHANNEL-04）

POST /channels/{id}/models/lifecycle 接收{upstream_model:string, deleted:boolean}，必须提供渠道If-Match版本；仅允许该视频渠道已观察/已保存或既有删除标记的型号。使用渠道父锁及CAS，在同一事务保存connection_settings.catalog_deleted_models、停用该上游型号的全部Supply并清除production_ready、写入审计。保留Supply身份、能力/成本、绑定、Attempt与历史；恢复只清除标记，不启用规格。不访问Provider。重新发现不会清除人工删除标记；目录返回行级deleted供筛选，消失的删除型号仍可恢复。

删除型号的原生Supply启用入口返回422生产门禁；过期渠道版本409、未知型号/非视频渠道404、归档渠道409、非法参数400/422。失败回滚整个事务。幂等同版本操作不增加版本；并发旧版本仍409。

控制台渠道编辑复用PATCH /channels/{id}，只改名称、base_url、并发及选定的连接字段（request_profile/pricing_profile/operator_note），保留其他连接设置及删除标记。控制台要求先停用渠道再修改地址/协议；状态/凭据沿用独立现有操作。