企业官网建设流程全解析

Agents-Flex是一个轻量级 Java AI Agent 开发框架，内置 Image（文生图）与 Video（文生视频）多模态模型模块：一套统一的 Java API 即可对接 OpenAI、Gemini、阿里云百炼、火山引擎、Gitee AI 等服务商，新手无需逐个学习各家 SDK 的协议差异。🚀

一图看懂：Agents-Flex 多模态模块能力

核心设计思路（详见 图片模块核心设计）：

• 图片模块只有一个入口ImageModel.generate()。文生图、参考图生成、多图融合、图片编辑都由请求内容表达；若服务商是异步接口，适配器会在内部自动完成"提交 → 轮询 → 解析结果"，应用层拿到的永远是最终图片或明确错误。
• 视频模块因生成耗时通常达数十秒到数分钟，采用异步任务设计：先generate()提交任务获得taskId，再getResult(taskId)查询；脚本类场景可直接用generateAndWait()一步阻塞等待（详见 视频生成开发文档）。

快速上手文生图：5 分钟生成第一张图

完整步骤参考 图片生成快速开始，以 Gitee AI 为例：

1. 添加依赖（切换服务商只需换 artifactId，见上表）：

<dependency> <groupId>com.agentsflex</groupId> <artifactId>agents-flex-image-gitee</artifactId> <version>${agents-flex.version}</version> </dependency>

2. 配置密钥（建议用环境变量，不要硬编码）：

export GITEE_AI_API_KEY="your-token"

3. 生成并保存图片：

GiteeImageModelConfig config = new GiteeImageModelConfig(); config.setApiKey(System.getenv("GITEE_AI_API_KEY")); config.setModel("flux-1-schnell"); GenerateImageRequest request = new GenerateImageRequest(); request.setPrompt("雨后的竹林小路，柔和自然光，电影感"); request.setSize(1024, 1024); ImageResponse response = new GiteeImageModel(config).generate(request); response.getImages().get(0).writeToFile(new File("output/generated-image.png"));

各服务商的模型与参数细节可查官方文档：OpenAI 图片生成、火山引擎图片生成，以及 agents-flex-image/ 下的各适配模块源码。

图片请求常用参数速查

统一请求GenerateImageRequest的常用字段：

⚠️ 每个模型只接受特定的像素尺寸或档位，例如有的模型用setSize(1024, 1024)，阿里云部分模型用setSizeString("1k")，切换模型后需重新核对尺寸参数。

快速上手文生视频：从提示词到 MP4 文件

以阿里云百炼为例，完整步骤参考 视频生成快速开始：

1. 添加依赖并配置密钥：

<dependency> <groupId>com.agentsflex</groupId> <artifactId>agents-flex-video-aliyun</artifactId> <version>${agents-flex.version}</version> </dependency>

export DASHSCOPE_API_KEY="your-dashscope-api-key"

2. 创建请求、提交并等待结果：

AliyunWanVideoModelConfig config = new AliyunWanVideoModelConfig(); config.setApiKey(System.getenv("DASHSCOPE_API_KEY")); config.setTimeoutMillis(10 * 60_000L); // 最多等待 10 分钟 config.setPollIntervalMillis(10_000L); // 每 10 秒查询一次 GenerateVideoRequest request = new GenerateVideoRequest(); request.setPrompt("一架红色纸飞机飞过日出时的未来城市，电影感广角镜头"); request.setNegativePrompt("模糊，抖动，畸变，低质量"); request.setSize(1280, 720); request.setDuration(5); request.setWatermark(false); VideoResponse response = new AliyunWanVideoModel(config).generateAndWait(request); if (response.getStatus() == VideoTaskStatus.SUCCEEDED) { response.getVideo().writeToFile(new File("output/generated-video.mp4")); }

火山引擎 Seedance 模型可参考 火山引擎视频生成，阿里云 Wan / HappyHorse 模型常量与参数映射见 阿里云视频生成；核心类源码位于 agents-flex-core/src/main/java/com/agentsflex/core/model/video/。

视频任务状态与异步最佳实践

VideoTaskStatus把不同服务商的任务状态统一为一套枚举：QUEUED（排队）→RUNNING（生成中）→SUCCEEDED（成功）/FAILED（失败）/CANCELED（取消）。

在 Web 服务中不建议长时间阻塞线程，推荐"提交 + 轮询"流程：

客户端提交请求 → generate() 保存 taskId → 后台定时 getResult(taskId) → 成功后下载视频 → 通知客户端

💡TIMED_OUT只表示本地等待超时，不代表云端任务失败，可继续用taskId查询结果。

进阶玩法：图生视频、首尾帧与参考图

除了纯文生视频，Agents-Flex 视频模块还支持多种多模态输入（能力取决于具体模型）：

图生视频只需给请求补一张首帧图，适配器会自动转换成服务商需要的 URL 或 Data URI：

request.setFirstFrame(Image.ofUrl("https://example.com/first-frame.png")); // 或使用内存字节 request.setFirstFrame(Image.ofBytes(imageBytes, "image/png"));

图片、视频、音频的"输入 → 输出"模型能力矩阵可参考 火山引擎 Seedance 文档中的输入输出说明，以及测试资源中的模型输入输出示例图：

常见问题（FAQ）

图片/视频 URL 为什么不能长期访问？云服务商通常返回临时签名 URL（一般 24 小时左右有效）。任务成功后请及时调用writeToFile()下载到本地，或转存到自己的对象存储。

TIMED_OUT是云端任务失败吗？不是。它只表示本地generateAndWait()达到等待上限，云端任务可能仍在执行，继续用任务 ID 调用getResult()即可。

为什么生成的视频耗时波动很大？视频生成时间受模型、分辨率、时长和服务商队列负载影响。生产环境应采用异步任务，不要假定固定的生成时间。

为什么设置的参数没有生效？不同模型支持的参数不同。先检查 Config 的能力字段和时长/分辨率等限制，再确认参数应放在统一请求还是服务商options中。

可以直接切换模型 ID 吗？可以，通过config.setModel(...)设置默认模型，或request.setModel(...)仅对单次请求覆盖。但参数能力不会自动转换，切换后需重新核对尺寸、时长等生成选项。

下一步

• 图片生成核心概念：统一请求、同步语义与模型能力配置
• 视频生成开发文档：异步任务设计、请求字段全表
• 快速开始（图片） / 快速开始（视频）
• 源码入口：agents-flex-image/、agents-flex-video/

从一张图到一段视频，Agents-Flex 用同一套简洁的 Java API 帮 Java 开发者把多模态模型能力快速落到生产系统里。🎬