fix(video): NewAPI Channel 2 - 修复轮询与结果解析
创建成功后的短暂 task_not_exist 按退避策略重试,并在短期窗口耗尽后保留 running 状态,继续回查原 Provider Task ID。 补齐嵌套任务 ID 与视频结果地址解析,更新生成插件、协议文档和专项回归测试。
This commit is contained in:
@@ -6,6 +6,7 @@
|
||||
"local-development",
|
||||
"code-map",
|
||||
"backend-database",
|
||||
"newapi-channel-2",
|
||||
"system-update",
|
||||
"protocol-plugins",
|
||||
"canvas-data-structure"
|
||||
|
||||
49
docs/content/docs/backend/newapi-channel-2.mdx
Normal file
49
docs/content/docs/backend/newapi-channel-2.mdx
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: NewAPI Video Generations Channel 2
|
||||
description: Channel 2 视频任务创建、轮询与上游任务同步延迟处理
|
||||
---
|
||||
|
||||
# NewAPI Video Generations Channel 2
|
||||
|
||||
## 请求流程
|
||||
|
||||
声明式插件使用以下接口:
|
||||
|
||||
- 创建:`POST /v1/video/generations`
|
||||
- 查询:`GET /v1/video/generations/{taskId}`
|
||||
|
||||
创建响应支持顶层 `id`、`task_id`、`taskId`,以及 `data.id`、`data.task_id`、`data.taskId`。当中转包装 ID 与真实上游任务 ID 同时存在时,按 `data.task_id`、`data.taskId`、顶层 `task_id`、顶层 `taskId`、`data.id`、顶层 `id` 的顺序解析,避免把中转内部记录 ID 用作上游查询 ID。宿主把解析出的值保存为 `provider_request_id`,后续查询始终使用该值,并对路径参数进行 URL 编码。
|
||||
|
||||
查询响应进入成功状态后,插件会从 `data.result_url`、`data.video_url`、`data.output_url`、`data.url`、`data.metadata.url` 以及对应的 `data.data.*` 嵌套字段读取视频地址,再回退到兼容的顶层结果字段。只返回成功状态而没有任何结果地址时,宿主仍按协议异常处理,不会创建空资源。
|
||||
|
||||
## 上游同步延迟
|
||||
|
||||
创建接口返回任务 ID 后,Channel 2 可能在数百毫秒到数秒内仍对查询接口返回结构化的 `400`:
|
||||
|
||||
```json
|
||||
{"code":"task_not_exist","message":"task_not_exist"}
|
||||
```
|
||||
|
||||
宿主只在同时满足以下条件时把该响应视为“任务状态尚未同步”:
|
||||
|
||||
1. 渠道接口类型精确为 `newapi-channel-2`;
|
||||
2. 已经保存非空 Provider Task ID;
|
||||
3. HTTP 状态为 `400`;
|
||||
4. JSON 的 `code` 或 `message` 精确等于 `task_not_exist`。
|
||||
|
||||
不符合条件的 HTTP 错误、非 JSON 正文或其他错误码仍立即按失败语义处理。
|
||||
|
||||
## 轮询与延期
|
||||
|
||||
新任务首次查询前等待 `2` 秒;同步错误在同一次执行中按 `2` 秒、`3` 秒、`5` 秒、`5` 秒退避,最多短期查询 5 次。短期窗口耗尽后,Worker 不发送新的创建请求,也不切换渠道或退款,而是:
|
||||
|
||||
- 保持本地任务状态为 `running`;
|
||||
- 保留原 `provider_request_id` 和计费状态;
|
||||
- 释放当前租约并把 `next_poll_at` 延后 15 秒;
|
||||
- 下一轮从已保存的 Provider Task ID 恢复,只发送查询请求。
|
||||
|
||||
因此,上游生成耗时 500 至 600 秒时,本地会持续以低频查询等待完成,不会把正常排队误报为“模型服务拒绝了请求”。视频真正返回失败状态时,仍按供应商失败处理。
|
||||
|
||||
## 兼容边界
|
||||
|
||||
该容错只适用于 `newapi-channel-2` 视频任务。其他 NewAPI 接口、其他 Provider、缺少 Provider Task ID 的任务,以及真实参数错误不进入延期路径。
|
||||
@@ -5,6 +5,14 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
|
||||
|
||||
# 待测试
|
||||
|
||||
## NewAPI Video Generations Channel 2 轮询恢复
|
||||
|
||||
- [x] 官方插件兼容从 `data.task_id` 和 `data.taskId` 读取上游任务 ID;Channel 2 创建成功后首次查询等待 2 秒,仅将结构化 `400 task_not_exist` 识别为上游同步延迟,并按 2 秒、3 秒、5 秒、5 秒退避复查同一任务。
|
||||
- [x] 短期重试耗尽后,Worker 保留本地任务 `running`、原 `provider_request_id` 和计费状态,延后 15 秒继续查询;恢复过程不重复发送创建请求、不切换渠道,也不立即失败或退款。其他接口类型、HTTP 状态和错误码仍按原失败语义处理。
|
||||
- [x] Channel 2 终态响应兼容 `data.result_url`、`data.video_url`、`data.output_url`、`data.url`、`data.metadata.url` 及对应的 `data.data.*` 嵌套路径;API 调用日志在该接口下优先记录嵌套真实任务 ID。协议与日志富化专项回归测试通过。
|
||||
- [ ] 使用真实 Channel 2 分别验证上游任务 ID 短暂不可见和生成耗时 500 至 600 秒的任务:本地不再提示“模型服务拒绝了请求”,创建请求只出现一次,后续始终查询同一 Provider Task ID,最终视频正常回写;真实参数错误仍应及时失败。
|
||||
- [ ] 使用返回 `SUCCESS` 且视频地址位于 `data.result_url` 或 `data.data.video_url` 的真实任务,确认不再提示“声明式协议已完成但没有返回结果”,并在当前 OSS 配置下成功下载并持久化为本地资源。
|
||||
|
||||
## 编辑器(M2 命令状态机)
|
||||
|
||||
- [x] 命令协议黄金文件:`editor-commands` 8 个黄金 op(addClip/moveClip/trimClip/splitClip/removeClip/setClipProperty/addSubtitle/removeSubtitle)全量快照比对通过;未知 op、非法 payload 一律抛错(fail-closed)且输入不可变。
|
||||
|
||||
Reference in New Issue
Block a user