企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习

导读

本文围绕 openJiuwen agent-core-java（com.openjiuwen.core.foundation.llm.schema包）中的VideoGenerationResponse类展开，剖析它是如何封装大模型视频生成接口（文本转视频 / 图片转视频）的响应数据的：包括其继承体系、六个核心字段的语义与默认值、Jackson 序列化行为，以及从Model.generateVideo到底层DashScopeModelClient的完整调用链路。读完本文，你将掌握该响应类的每个字段在真实请求-响应流程中的来源，并能在自己的 Agent 应用中正确读取视频生成结果、判断各模型客户端的能力边界。

一、类定位：视频生成接口的统一响应模型

VideoGenerationResponse位于com.openjiuwen.core.foundation.llm.schema包，定义于 VideoGenerationResponse.java，类声明如下：

public class VideoGenerationResponse extends GenerationResponse

从源码注释可以确认，它是 Python 版openjiuwen/core/foundation/llm/schema/generation_response.py中同名类的 Java 镜像，用于"封装视频生成接口的响应数据"。

其父类GenerationResponse定义于 GenerationResponse.java，是整个多模态生成响应体系的公共基类，目前包含一个字段：

VideoGenerationResponse与同包下的ImageGenerationResponse、AudioGenerationResponse共同组成了 openJiuwen 的多模态生成响应家族——它们均继承GenerationResponse并各自扩展与模态相关的字段。

二、字段详解：六个字段的语义、来源与默认值

VideoGenerationResponse在父类model字段之上新增了五个字段，完整字段清单如下：

其中format字段带有@Builder.Default注解，默认值为"mp4"。这意味着即使构建响应时未显式指定格式，使用 Builder 方式构建出的对象也会携带format="mp4"的默认值；而直接使用无参构造或字段赋值路径时不会自动填充该默认值（由 Lombok@SuperBuilder的默认值机制决定），这一点在使用时值得留意。

2.1 字段与 JSON 键名的映射

该类对两个字段显式声明了 Jackson 序列化/反序列化时的 JSON 键名：

@JsonProperty("video_url") private String videoUrl; @JsonProperty("video_data") private byte[] videoData;

即videoUrl与 JSON 中的video_url对应，videoData与 JSON 中的video_data对应。这一命名策略与 DashScope 等厂商返回的响应结构保持一致（下文第 4 节的调用链中会看到video_url正是服务端响应体output中的键名）。

2.2 空值字段的序列化控制

类级注解@JsonInclude(JsonInclude.Include.NON_NULL)意味着：当这些字段为null时，序列化结果中不会出现对应的 JSON 键。这在实际使用中非常关键——例如videoData通常为null（视频以 URL 形式返回），若不控制则每个响应都会输出一个巨大的video_data字段，徒增负载；而该注解配合 Lombok 的@Data，使响应对象天然具备"空字段自动省略"的能力。

三、构建方式：Builder 与全参构造

类上标注了@Data、@SuperBuilder、@NoArgsConstructor、@AllArgsConstructor、@EqualsAndHashCode(callSuper = true)，因此支持以下构建方式：

// 方式一：链式 Builder（推荐，SuperBuilder 支持继承父类的 model 字段） VideoGenerationResponse response = VideoGenerationResponse.builder() .model("wan2.6-t2v") .videoUrl("https://example.com/video.mp4") .duration(6.0) .resolution("1080P") .build(); // format 自动取默认值 "mp4" // 方式二：全参构造 VideoGenerationResponse response2 = new VideoGenerationResponse( "wan2.6-t2v", // model "https://example.com/video.mp4", // videoUrl null, // videoData 6.0, // duration "1080P", // resolution "mp4" // format );

@EqualsAndHashCode(callSuper = true)表示 equals/hashCode 会连同父类model字段一起参与比较，这在测试断言和结果缓存场景下可避免"仅比较子类字段"带来的漏判。

四、调用链：从 Model 门面到底层客户端

VideoGenerationResponse是视频生成流程的"终点产物"，其完整产生链路为：

Model.generateVideo(...) → ModelClient.generateVideo(List<UserMessage>, VideoGenerationOptions) → BaseModelClient.generateVideo(12 个参数的重载) → 具体客户端实现（如 DashScopeModelClient） → 解析厂商 API 响应 → VideoGenerationResponse.builder()...build()

4.1 Model 门面：参数与默认值

在 Model.java 中，Model提供了两个generateVideo重载：

// 最简调用：除消息外全部使用默认参数 public CompletionStage<VideoGenerationResponse> generateVideo(List<UserMessage> messages) { return generateVideo(messages, null, null, null, null, null, 5, true, false, null, null, null); }

最简重载对应的默认参数为：duration=5（5 秒）、promptExtend=true（提示词扩写开启）、watermark=false（不加水印），其余参数为null。完整重载则把全部选项打包为Model.VideoGenerationOptionsrecord（定义于 Model.java）：

public record VideoGenerationOptions( String imgUrl, // 首帧图片 URL，传入则为"图片转视频" String audioUrl, // 背景音频 URL String model, // 指定模型名；为 null 时使用 ModelRequestConfig 中配置的模型 String size, // 画幅，如 "1280*720" String resolution, // 分辨率，如 "1080P" int duration, // 时长（秒） boolean promptExtend, // 是否扩写提示词 boolean watermark, // 是否加水印 String negativePrompt, // 反向提示词 Integer seed, // 随机种子 Map<String, Object> extraFields) { // 透传给厂商的额外参数 }

Model门面将List<UserMessage>经safeUserMessages处理后委托给内部持有的ModelClient，ModelClient接口中的默认实现（Model.java）会在客户端不支持视频生成时返回一个携带IllegalStateException("Model client lacks generate_video support")的失败CompletionStage。

4.2 BaseModelClient：抽象方法与异步包装

BaseModelClient.java 定义了 12 参数版本的抽象方法，并提供基于它的异步适配：

public abstract VideoGenerationResponse generateVideo( List<UserMessage> messages, String imgUrl, String audioUrl, String model, String size, String resolution, int duration, boolean promptExtend, boolean watermark, String negativePrompt, Integer seed, Map<String, Object> kwargs) throws Exception; @Override public CompletionStage<VideoGenerationResponse> generateVideo( List<UserMessage> messages, Model.VideoGenerationOptions options) { try { return CompletableFuture.completedFuture(generateVideo( messages, options.imgUrl(), options.audioUrl(), options.model(), options.size(), options.resolution(), options.duration(), options.promptExtend(), options.watermark(), options.negativePrompt(), options.seed(), options.extraFields())); } catch (Exception exception) { return CompletableFuture.failedFuture(exception); } }

所有具体模型客户端只需实现抽象版本，异步能力由基类统一提供。

五、DashScope 实现：VideoGenerationResponse 的真实生产者

在所有模型客户端中，只有DashScopeModelClient完整实现了视频生成逻辑（DashScopeModelClient.java），其余客户端的行为见第 6 节。

其内部流程可概括为"参数组装 → 接口调用 → 响应解析 → 构建响应对象"四步：

1. 消息校验：requireSingleUserMessageForVideo强制要求messages恰好包含一条且为UserMessage（DashScopeModelClient.java）；该消息的文本内容必须非空，否则抛出校验错误"Video generation requires non-empty text content."。

2. 参数组装：以api_key、model、prompt、prompt_extend、watermark为基础参数，按需追加duration、negative_prompt、seed、audio_url；随后根据是否传入imgUrl分支处理：

   • 图片转视频（传入imgUrl）：追加img_url，并优先使用resolution、其次size；
   • 文本转视频（未传imgUrl）：优先使用size、其次resolution；
   • 最后的putKwargs(apiParams, kwargs)允许透传任意额外参数。

3. 接口调用与校验：调用DashScopeApi.VIDEO_SYNTHESIS（对应路径/services/aigc/video-generation/video-synthesis，见 DashScopeModelClient.java 与第 726 行的 API 映射），并对响应做ensureOkResponse状态码校验。

4. 响应解析与响应对象构建：extractVideoPayload（DashScopeModelClient.java）从响应中提取三部分数据：

   • videoUrl：读取output.video_url；
   • duration：读取usage.duration或usage.output_video_duration；
   • resolution：读取usage.size；

   随后通过 Builder 组装响应对象：

return VideoGenerationResponse.builder() .model(resolvedModel) // 显式传入了 model，未用默认 .videoUrl(videoPayload.videoUrl()) .duration(videoPayload.duration()) .resolution(videoPayload.resolution()) .format("mp4") // 显式指定 mp4 .build();

可见VideoGenerationResponse的字段与 DashScope 响应体是一一对应的：video_url → videoUrl、时长/分辨率来自usage区段。若服务端未返回video_url，客户端会抛出"No video URL returned from DashScope API."错误（videoData字段在这一实现中保持null，为自行下载/注入二进制内容预留了扩展位）。

六、各模型客户端的能力边界

从源码结构看，generateVideo的支撑情况因客户端而异，调用前应确认目标 provider 的能力：

因此在实际应用中，视频生成能力目前主要由 DashScope 客户端承担；使用其他 provider 时应先判空，避免空指针。

七、测试验证：字段行为有据可依

仓库测试对VideoGenerationResponse的字段与参数映射做了完整断言，是理解其行为的权威参考。以 DashScopeModelClientTest.java 为例：

• 图片转视频分支：传入imgUrl、audioUrl、resolution="1080P"等参数后，断言响应对象model为配置默认模型、videoUrl与 mock 返回一致、duration为 6.0、resolution为"1080P"、format为"mp4"；同时断言请求参数中包含img_url、audio_url、resolution、prompt_extend、watermark、negative_prompt、seed及透传的style，且不含size键——印证了"有imgUrl时优先 resolution 而非 size"的分支逻辑。
• 文本转视频分支：不传imgUrl，指定model="wan2.6-t2v"、resolution="720P"，断言请求参数携带resolution与model。
• 此外 ModelTest.java 展示了最简用法：VideoGenerationResponse.builder().videoUrl("video").build()即可构造一个最小响应用于 stub。

八、使用建议与注意事项

1. 优先读取videoUrl：DashScope 链路返回的均为 URL 形式，videoData默认保持null；如需二进制数据应基于videoUrl自行下载后注入。
2. format默认值依赖 Builder：默认"mp4"由@Builder.Default保证；若通过其他方式构建且不关心格式，建议显式设置以免与预期不符。
3. 空值字段自动省略：得益于@JsonInclude(NON_NULL)，将VideoGenerationResponse直接序列化给下游（如 Web 接口返回）时，未填充字段不会出现在 JSON 中，这既减小了体积，也要求下游解析时按可选字段处理。
4. 调用前确认 provider 能力：目前仅 DashScope 客户端真正支持视频生成，其余客户端返回null或抛异常；可先用Model门面统一调用，再对返回结果做空值防护。
5. 签名以源码为准：该类的公开构造器、Builder 与字段签名，最终均以仓库中 VideoGenerationResponse.java 的实际 Java 源码为准。

小结

VideoGenerationResponse是 openJiuwen agent-core-java 多模态生成体系中对视频生成响应的标准化封装：它通过继承GenerationResponse复用model字段，以五个子类字段完整刻画视频结果（URL/二进制、时长、分辨率、格式），并以 Jackson 注解保证了与厂商响应键名的兼容和空字段省略。在调用链上，它由Model门面统一出口、BaseModelClient定义抽象、DashScopeModelClient完成真实生产，并有成体系的测试用例背书。开发者只需面向Model.generateVideo编程，即可在支持视频生成的 provider 上获得统一、类型安全的响应模型。

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习