在聊天里生成视频：文字、图片与异步回传

来源与验证状态

这个案例能帮你做什么

• 在 OpenClaw 对话中直接生成短片，无需自己编写提交任务和轮询脚本。
• 把已有产品图、插画或角色图作为视频参考输入。
• 提交任务后继续对话，生成完成时回到发起请求的会话收取媒体。

这适合先做一个 5 秒创意样片。长片拼接、配音、剪辑和投放仍是后续制作步骤；本页只覆盖原生视频生成。

开始前需要什么

工具只有在视频提供者可用时才出现。聊天模型能看图片，并不等于已经配置视频生成服务。

官方区分三个模式：纯文字 generate、图片参考 imageToVideo、视频参考 videoToVideo。各提供者支持的模式、时长、比例和素材位置不同，应先检查 action: "list" 的结果。

最小设置

官方快速开始使用 Gemini/Veo 作为示例。先让 Gateway 能读取授权，再按自己的账户权限选择模型。

如果 Gateway 由 launchd／systemd 托管，终端里的 export GEMINI_API_KEY="your-key" 不会自动传给它；该写法适用于从同一 shell 启动的前台 Gateway。官方推荐把提供者密钥放在 Gateway 实际运行用户的 ~/.openclaw/.env；使用其他状态目录或 profile 时，放在对应的 $OPENCLAW_STATE_DIR/.env。不要放在项目工作区的 .env，该位置的提供者凭证会被忽略。

用编辑器打开已有全局 .env，保留其他变量与已有密钥；仅补充缺少的 GEMINI_API_KEY。下面是文件内容示意，your-key 必须由你在本机替换，不是可执行命令：

GEMINI_API_KEY=your-key

已有可用密钥时直接复用，不覆盖文件。全局 .env 也不会普遍覆盖 Gateway 已有的进程环境；如果服务自身配置了同名密钥，应先核对实际使用的来源。保存后设置模型并重启对应 Gateway，让新授权生效：

openclaw config set agents.defaults.mediaModels.video.primary "google/veo-3.1-fast-generate-preview"
openclaw gateway restart

your-key 是占位符。不要把真实凭证贴到聊天或提交到仓库。上面的模型来自官方文档示例，仍需账户实际可用。

如果已有其他受支持的提供者，可保留它的设置。Gateway 重启完成后，在对应会话让 Agent 用 action: "list" 检查视频能力，确认提供者与模型出现，并核对输入模式与参数限制：

请用 video_generate 的 action=list 检查可用提供者。
只列出：模型、支持的输入模式、时长/比例限制、是否支持生成音频。
本轮不要提交生成任务。

快速体验：一句话生成一个短片

请生成一个 5 秒视频：一只友善的龙虾在日落海面冲浪。
先检查当前视频模型是否支持该时长；不支持时说明可选值。
确认可用后只提交一个任务，不重复生成。
完成后回传视频，并说明实际使用的模型与参数。

最低输入就是一句场景描述。建议第一次只要求一个视频，便于判断工具接通和输出是否符合预期。

第二轮：把产品图变成动态样片

将自己可使用的一张图片上传到会话，再发：

请用刚才上传的产品图做图片到视频的样片。
构思：产品保持主体不变，镜头缓慢靠近，背景出现柔和光线变化。
先检查当前提供者是否接受这张图片的存储位置和大小。
输出一个受支持时长的视频；只提交一次。
不要声称文字、商标或产品外观能够完全保持一致。

这是本页提出的创作组合，未做实际生成。提供者可能改变细节，结果需要人工检查。

如果需要首尾相接的循环，官方支持使用图片角色 first_frame 与 last_frame；只有所选提供者支持这些角色时才使用。不能把一种提供者的多图能力套用到全部模型。

异步任务怎么处理

1. 工具提交请求，返回任务标识和当前状态。
2. 提供者在后台处理，等待时间取决于模型、分辨率和队列。
3. 完成事件唤醒原会话，Agent 按该会话的回复方式交付媒体。
4. 等待期间检查状态，使用 action: "status"，避免另开一轮生成。

同一聊天已有生成任务时，重复调用会返回当前状态。普通会话与直接工具调用的执行方式不同：没有会话的直接调用可能等待最终结果后才返回。

你应该收到什么

• 一个实际视频文件或提供者返回的视频 URL。
• 使用的提供者、模型、实际时长与输出状态。
• 若某个请求参数被忽略或规范化，应说明实际采用的值。

可按下面的格式验收：

任务状态：成功 / 失败 / 仍在处理
模型：
输入模式：文字 / 图片 / 视频
实际输出：文件或 URL
参数变化或限制：

常见失败与边界

• 找不到工具： 检查视频提供者授权和 agents.defaults.mediaModels.video，不要只检查聊天模型。
• 图片被拒绝： 核对该提供者是否支持本地文件、远程 URL、图片数量和文件大小。
• 视频参考不可用： Kie AI、Z.AI、Novita 不接受视频参考；不要据此改成反复重试。
• 等待太久： 先查原任务状态；超时不证明提供者没有完成，更不能把新请求当成查询。
• 文件太大： 官方文档默认媒体上限为 16 MB；存在有效托管 URL 时可能通过 URL 交付。提高上限前先确认渠道也能接收。
• 音频与费用： 生成音频依赖提供者能力；视频服务有独立计费，不以聊天订阅是否可用推断免费额度。

引用来源

• 固定版本：视频生成工具与提供者限制
• 固定版本：Gateway 环境变量来源与全局 .env
• 固定版本：Gateway 重启
• 官方在线指南：Video generation
• 2026.9.7 更新说明：新增视频提供者
• v2026.10.1 发布记录