feat(ai-avatar): finalize 支持 cover_url/video_title + 兜底自动抽帧 #2288

Merged

xiaoxia merged 3 commits from feat/ai-avatar-finalize-cover into develop 2026-10-13 22:43:01 +08:00

Conversation 2 Commits 3 Files Changed 4

+377 -8

xiaoxia commented 2026-10-13 20:40:55 +08:00

Owner

Copy Link

Copy Source

背景

配合前端修复「AI数字人选封面后点完成视频没入库/封面为空」的 Bug。

改动

1. schema: 新增 FinalizeRenderRequest，含两个可选字段：
   • cover_url: 用户选定的封面公网 URL（本地封面需前端先 OSS 直传拿公网 URL；blob:/data: URL 后端检测后忽略）
   • video_title: 成片库展示标题，覆盖默认 AI数字人_{job_id[:8]}
2. POST /{job_id}/finalize: 接受 JSON body（老客户端空 body 完全兼容）
   • 封面三级优先级：body.cover_url > job.output_cover_url（smart-cover 已写入）> 兜底 generate_smart_cover 自动抽帧
   • 非 HTTP(S) URL 检测：blob:/data: 等无效 URL 记录 warning 并忽略，避免破图入库
   • 路由层前置校验 output_video_url 非空，错误码对齐 service
   • 兜底抽帧成功后回写 job.cover_config+job.output_cover_url
3. service.finalize_job/_persist_to_library: 新增 video_title 形参覆盖默认成片名

前端联调

• finalize 调用：POST /ai-avatar/render/{job_id}/finalize，body 可选 {cover_url, video_title}
• 本地上传封面：先用 POST /upload/direct/prepare+complete 直传 OSS 拿公网 URL，再 finalize 传 cover_url
• smart-cover 路径不变：调完 smart-cover 后端已写 cover_config，finalize 不用再传
• 未选封面也能 finalize：后端兜底自动抽帧
• 烧录标题 title_config 仍在 submitRender 时传，finalize 改不了已渲染视频

验证

• pytest 17088 passed，syntax ok
• 3 文件 +65/-8，无迁移无新依赖

## 背景 配合前端修复「AI数字人选封面后点完成视频没入库/封面为空」的 Bug。 ## 改动 1. **schema**: 新增 `FinalizeRenderRequest`，含两个可选字段： - `cover_url`: 用户选定的封面公网 URL（本地封面需前端先 OSS 直传拿公网 URL；blob:/data: URL 后端检测后忽略） - `video_title`: 成片库展示标题，覆盖默认 `AI数字人_{job_id[:8]}` 2. **POST /{job_id}/finalize**: 接受 JSON body（老客户端空 body 完全兼容） - 封面三级优先级：`body.cover_url` > `job.output_cover_url`（smart-cover 已写入）> 兜底 `generate_smart_cover` 自动抽帧 - 非 HTTP(S) URL 检测：blob:/data: 等无效 URL 记录 warning 并忽略，避免破图入库 - 路由层前置校验 `output_video_url` 非空，错误码对齐 service - 兜底抽帧成功后回写 `job.cover_config`+`job.output_cover_url` 3. **service.finalize_job/_persist_to_library**: 新增 `video_title` 形参覆盖默认成片名 ## 前端联调 - finalize 调用：`POST /ai-avatar/render/{job_id}/finalize`，body 可选 `{cover_url, video_title}` - 本地上传封面：先用 `POST /upload/direct/prepare`+`complete` 直传 OSS 拿公网 URL，再 finalize 传 cover_url - smart-cover 路径不变：调完 smart-cover 后端已写 cover_config，finalize 不用再传 - 未选封面也能 finalize：后端兜底自动抽帧 - 烧录标题 title_config 仍在 submitRender 时传，finalize 改不了已渲染视频 ## 验证 - pytest 17088 passed，syntax ok - 3 文件 +65/-8，无迁移无新依赖

xiaoxia added 1 commit 2026-10-13 20:40:55 +08:00

feat(ai-avatar): finalize 接口支持 cover_url/video_title 可选字段 + 兜底自动抽帧 ... 5603c92a02

- 新增 FinalizeRenderRequest schema: cover_url / video_title 均可选
- finalize 端点接受 JSON body (Body default=空对象，老客户端空body兼容)
- 封面三级优先级: body.cover_url > job.output_cover_url(smart-cover) > 兜底 generate_smart_cover 自动抽帧
- 非HTTP(S) URL (blob:/data:) 检测后忽略，避免破图入库
- service.finalize_job / _persist_to_library 新增 video_title 参数覆盖默认 AI数字人_{id}
- 路由层提前校验 output_video_url 非空，错误码对齐 service 层

xiaoxia referenced this pull request 2026-10-13 20:42:55 +08:00

fix(ai-avatar): 修复选封面点完成后视频封面丢失/未入库 #2289

gitea-actions bot commented 2026-10-13 20:43:56 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#2288
预览链接	https://pr-2288.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #2288 | | 预览链接 | [https://pr-2288.preview.xiaoxiajianji.com](https://pr-2288.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot added 1 commit 2026-10-13 20:54:28 +08:00

style: auto-format with black + isort + ruff + prettier [skip ci-format-check] 28e3408a19

xiaoxia added 1 commit 2026-10-13 21:31:09 +08:00

test(ai-avatar): 补 finalize 路由 10 个单测覆盖 body/cover_url/video_title/兜底/幂等等路径 ... 8245302aca

- 修复 blob/data: URL 被忽略后未继续 fallback 到 job.output_cover_url 的逻辑（改为按优先级循环校验每一级）
- 覆盖：404/400 状态码、空body兼容、body.cover_url优先、blob URL 忽略并fallback、兜底抽帧写回DB、幂等existing、video_title覆盖、service错误映射
- 33 个路由测试全过；全量 17098 passed

xiaoxia merged commit 5f0533e937 into develop 2026-10-13 22:43:01 +08:00

gitea-actions bot commented 2026-10-13 22:47:24 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #2288 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #2288 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

feature/admin

Admin 后台功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#2288