CreateReferenceVideoHandler.handle 接口文档

1. 接口概述

项目	说明
接口名称	图片转视频（参考图模式 / Seedance reference2video）
处理器类	`com.star.b2v.web.socket.handler.CreateReferenceVideoHandler`
入口方法	`handle(CreateReferenceVideoMessage message)`
消息类型（messageType）	`CreateReferenceVideoMessage`
通信协议	WebSocket（双向，异步）
执行方式	`@Async("websocketTaskExecutor")` 异步线程池执行
核心依赖	`IMultipleImg2Video.img2video`（默认实现：`SeedanceMultipleImg2VideoImpl`）

业务说明

接收客户端通过 WebSocket 推送的"图片转视频"任务，调用豆包 Seedance reference2video 接口创建视频生成任务，并启动异步轮询。视频生成的最终结果（成功/失败）由 SeedanceBaseService 轮询线程通过 TaskEventPublisher 发布事件，再由 WebSocket 推回客户端。

注意：本接口不是立即返回视频URL，而是提交一个异步任务。客户端需通过同一 WebSocket 监听后续推送的结果消息。

2. 调用链路

客户端 WebSocket 文本消息
        │
        ▼
ApiWebSocketHandler.handleTextMessage           ← 解析 payload，按 messageType 路由
        │  (messageType = "CreateReferenceVideoMessage")
        ▼
MessageMappingFactory.getHandler(CreateReferenceVideoMessage.class)
        │
        ▼
MsgHandlerAspect.around                          ← @Around 切面，@Order(1)
        │  1. 解析 taskId = "{userId}_{clientId}"
        │  2. 查重（同 msgType + 同 msg 内容 + INIT 状态）→ 重复则返回"任务正在处理中"
        │  3. 落库 aisp_websocket_task，回写 dataTaskId
        │  4. point.proceed()
        ▼
CreateReferenceVideoHandler.handle               ← @Async 异步执行
        │
        ▼
SeedanceMultipleImg2VideoImpl.img2video
        │  1. buildRequest(message)              ← 组装 Seedance 请求体
        │  2. createVideoTask(apiUrl, request)   ← 调用火山 Seedance API
        │  3. saveGenerateVideo(message, taskId) ← 落库 aisp_generate_video (状态=进行中)
        │  4. putTaskAsyncDelayed(...)           ← 启动异步轮询
        ▼
（轮询完成后由 SeedanceBaseService 推送结果给客户端）

3. WebSocket 连接

连接地址：ws(s)://<host>/ws?userId={userId}

userId 必填，用于会话路由

连接成功：服务端推送 CONNECT_SUCCESS

心跳：客户端发送 ping，服务端回复 {"pong":"pong"}

消息格式：JSON 文本帧

4. 请求消息（客户端 → 服务端）

4.1 报文结构

外层为 SocketMessage 基础字段 + CreateReferenceVideoMessage 业务字段混合平铺。

字段	类型	必填	说明
`messageType`	String	是	固定值：`CreateReferenceVideoMessage`（路由用）
`taskId`	String	是	格式：`{userId}_{clientId}`，如 `1001_abc123`；用于切面解析 userId/clientId 并落库
`sessionId`	String	否	由服务端在 `ApiWebSocketHandler` 中按连接自动回填，客户端无需传
`msgType`	String	否	由服务端回填为 `CreateReferenceVideoMessage`，客户端无需传
`dataTaskId`	Long	否	由切面 `MsgHandlerAspect` 落库后回写，客户端无需传

4.2 业务字段（CreateReferenceVideoMessage）

字段	类型	必填	默认值	说明
`taskId`	String	是	-	与外层 `taskId` 同值（业务唯一任务标识）；格式必须为 `{userId}_{clientId}`，否则被切面拦截
`storyboardId`	Integer	是	-	所属分镜 ID，用于查询所属剧集资产（角色/场景/道具/生物）并启动轮询
`refImages`	List<String>	否	-	参考图 URL 列表，全部映射为 `reference_image`
`firstLastImages`	List<String>	条件	-	首帧/尾帧图；`genWay > 0` 时生效
`genWay`	Byte	否	0	生成方式：`0`-单帧，`1`-首帧（取 firstLastImages[0]），`2`-首尾帧（取前2张）
`refAudio`	List<String>	否	-	参考音频 URL；与角色音频合计 > 3 时将被舍弃
`refVoice`	List<String>	否	-	参考视频 URL（实际以 `reference_video` 角色提交）
`prompt`	String	否	""	生成提示词；若指定 `promptTemplateId` 则作为 basePrompt
`promptTemplateId`	Integer	否	-	关联提示词模板 ID；为空时直接使用 `prompt`
`promptParams`	String(JSON)	否	-	模板变量 JSON，解析为 `List<VariableVo>` 覆盖模板变量
`seed`	Integer	否	0	随机种子
`amount`	Integer	否	1	生成数量（仅落库，当前实现单任务提交）
`duration`	Integer	否	-	视频时长（秒）；直接透传给 Seedance，不传则由模型默认决定。注意：r2v（参考图模式）下 Seedance 可能忽略此参数，时长以提示词描述为准
`aspectRatio`	String	否	`9:16`	画面比例（如 `16:9`、`4:3`、`1:1`）
`resolution`	String	否	`720p`	分辨率
`hasAudio`	Byte	否	0（false）	是否含音频：`0`-否，`1`-是
`videoModelId`	Byte	否	-	视频模型 ID（仅落库，模型名固定为 `doubao-seedance-2-0-260128`）
`consumeAmount`	Integer	否	-	消耗积分（仅落库）
`status`	Byte	否	-	生成状态：`0`-待处理，`1`-进行中，`2`-成功，`3`-失败（仅落库，由轮询更新；客户端不要传）

4.3 业务规则与限制

模型：固定 doubao-seedance-2-0-260128，不可通过消息切换。

参考图上限：参考图 + 首尾帧 + 剧集资产图片 总数 ≤ 9 张；剧集资产按 maxImages - 已用槽位 补齐。

剧集资产自动注入：根据 storyboardId → episodeId 自动查询剧集资产图片（角色/场景/道具/生物）作为 reference_image，并将角色音频作为 reference_audio。

角色名替换：提示词中出现的资产名称会被替换为 图X（X 为该资产在 content 中的 1-based 索引）。

音频标注注入：对 角色名（台词）： / 角色名（独白）： 模式自动追加 [音频参考：音频N]。

音频数量限制：角色音频 + refAudio 合计 > 3 时，舍弃传入的 refAudio，仅保留角色音频。

duration 透传：duration 字段（秒）会被原样写入 Seedance 请求体的 duration，不做非空兜底。但 Seedance 在 reference2video 模式下可能忽略此参数，实际时长以提示词内容控制为准。

幂等/防重：切面按 msgType + msg内容(JSON) + INIT状态 查重，重复任务直接回推 任务正在处理中，不重复执行。

returnLastFrame：请求固定为 true。

4.4 请求示例

{
  "messageType": "CreateReferenceVideoMessage",
  "taskId": "1001_abc123",
  "storyboardId": 88,
  "refImages": [
    "https://cos.example.com/xxx/ref1.jpg",
    "https://cos.example.com/xxx/ref2.jpg"
  ],
  "firstLastImages": [
    "https://cos.example.com/xxx/first.jpg",
    "https://cos.example.com/xxx/last.jpg"
  ],
  "genWay": 2,
  "refAudio": [
    "https://cos.example.com/xxx/audio1.wav"
  ],
  "refVoice": [
    "https://cos.example.com/xxx/voice-ref.mp4"
  ],
  "prompt": "角色A（台词）：你好呀；镜头缓缓推进。",
  "promptTemplateId": 12,
  "promptParams": "[{\"varName\":\"{{scene}}\",\"possibleValues\":\"雨夜街景\"}]",
  "seed": 1024,
  "amount": 1,
  "duration": 5,
  "aspectRatio": "16:9",
  "resolution": "720p",
  "hasAudio": 1,
  "videoModelId": 1,
  "consumeAmount": 10
}

5. 响应消息（服务端 → 客户端）

所有响应通过同一 WebSocket 连接推送，均为 JSON 文本帧，由 AjaxResult 构造。

5.1 任务提交成功（瞬时确认）

注意：CreateReferenceVideoHandler.handle 本身未在成功路径主动推送 ack 给客户端，仅记录日志。客户端若需要提交确认，请依赖下方"最终结果消息"。提交失败的错误消息见 5.3。

5.2 最终结果 - 成功

由 SeedanceBaseService 轮询成功后通过 TaskEventPublisher.publishSuccess(message, eventPublisher, data) 推送：

{
  "code": "200",
  "msgType": "CreateReferenceVideoMessage",
  "taskId": "1001_abc123",
  "data": {
    "videoUrl": "https://cos.example.com/xxx/result.mp4",
    "lastFrameUrl": "https://cos.example.com/xxx/lastframe.jpg"
  },
  "timestamp": 1690000000000
}

5.3 最终结果 - 失败

由 CreateReferenceVideoHandler.handle 捕获异常后调用：

sendError(message, "图片转视频失败: " + e.getMessage())

TaskEventPublisher.publishFailure(message, eventPublisher, e.getMessage())

{
  "code": "500",
  "msgType": "CreateReferenceVideoMessage",
  "taskId": "1001_abc123",
  "msg": "图片转视频失败: <错误详情>",
  "timestamp": 1690000000000
}

5.4 任务重复（防重拦截）

由 MsgHandlerAspect 直接推送，不会执行 handler：

{
  "code": "500",
  "msgType": "CreateReferenceVideoMessage",
  "taskId": "1001_abc123",
  "msg": "任务正在处理中",
  "timestamp": 1690000000000
}

5.5 taskId 格式错误（切面校验失败）

{
  "code": "500",
  "msg": "taskId格式错误!",
  "timestamp": 1690000000000
}

6. 异常与错误码

场景	触发位置	行为
`taskId` 不含 `_` 或解析失败	`MsgHandlerAspect`	推送 `taskId格式错误!`，不执行 handler
同任务重复提交（INIT 状态）	`MsgHandlerAspect`	推送 `任务正在处理中`，不执行 handler
`img2video` 抛异常	`CreateReferenceVideoHandler.handle` catch	推送错误消息 + 发布 `TaskCompletionEvent.failure`
Seedance API 返回 taskId 为空	`SeedanceMultipleImg2VideoImpl.img2video`	抛 `RuntimeException`，走失败路径
任务落库 `aisp_generate_video` 失败	`saveGenerateVideo` catch	不影响主流程（任务已提交给 Seedance），仅记录错误日志

7. 数据落库

表	触发点	关键字段
`aisp_websocket_task`	`MsgHandlerAspect`（任务创建）	`msgType`、`msg`(消息体JSON)、`userId`、`clientId`、`delFlag=INIT`
`aisp_generate_video`	`SeedanceMultipleImg2VideoImpl.saveGenerateVideo`	`taskId`(Seedance ID)、`storyboardId`、`refImages`、`prompt`、`status=1(进行中)` 等；后续轮询更新

8. 相关代码位置

角色	路径
Handler	`b2v-web/src/main/java/com/star/b2v/web/socket/handler/CreateReferenceVideoHandler.java`
消息体	`b2v-api/src/main/java/com/star/b2v/api/message/CreateReferenceVideoMessage.java`
消息基类	`b2v-api/src/main/java/com/star/b2v/api/message/SocketMessage.java`
处理器接口	`b2v-web/src/main/java/com/star/b2v/web/socket/handler/MessageHandler.java`
业务实现	`b2v-core/src/main/java/com/star/b2v/core/service/video/SeedanceMultipleImg2VideoImpl.java`
事件发布	`b2v-api/src/main/java/com/star/b2v/api/service/ws/TaskEventPublisher.java`
切面	`b2v-web/src/main/java/com/star/b2v/web/socket/aspect/MsgHandlerAspect.java`
WS 入口	`b2v-web/src/main/java/com/star/b2v/web/socket/websocket/ApiWebSocketHandler.java`
路由工厂	`b2v-web/src/main/java/com/star/b2v/web/socket/websocket/MessageMappingFactory.java`

生成章节分镜视频

CreateReferenceVideoHandler.handle 接口文档#

1. 接口概述#

业务说明#

2. 调用链路#

3. WebSocket 连接#

4. 请求消息（客户端 → 服务端）#

4.1 报文结构#

4.2 业务字段（CreateReferenceVideoMessage）#

4.3 业务规则与限制#

4.4 请求示例#

5. 响应消息（服务端 → 客户端）#

5.1 任务提交成功（瞬时确认）#

5.2 最终结果 - 成功#

5.3 最终结果 - 失败#

5.4 任务重复（防重拦截）#

5.5 taskId 格式错误（切面校验失败）#

6. 异常与错误码#

7. 数据落库#

8. 相关代码位置#

Request