视频生成

OpenClaw 智能体可通过 video_generate，根据文本提示词、参考图像或现有视频生成视频。支持十六个提供商后端；智能体会根据配置和可用的 API key 自动选择合适的后端。

仅当至少有一个视频生成提供商可用时，才会显示 video_generate。如果你的智能体工具中没有该工具，请设置提供商 API key 或配置 agents.defaults.mediaModels.video。

video_generate 有三种运行时模式，具体模式根据调用中的参考输入确定：

generate - 无参考媒体（文生视频）。
imageToVideo - 一张或多张参考图像。
videoToVideo - 一个或多个参考视频。

提供商可支持这些模式的任意子集。该工具会在提交前验证当前模式，并在 action=list 中报告支持的模式。

快速开始

配置身份验证

为任意受支持的提供商设置 API key：

export GEMINI_API_KEY="your-key"

选择默认模型（可选）

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

向智能体发出请求

生成一段 5 秒的电影感视频，内容是一只友好的龙虾在日落时分冲浪。

智能体会自动调用 video_generate。无需将工具加入允许列表。

异步生成的工作方式

视频生成是异步的：

OpenClaw 向提供商提交请求，并立即返回任务 ID。
提供商在后台处理任务（通常需要 30 秒到几分钟，具体取决于提供商和分辨率；由慢速队列支持的提供商最长可运行至所配置的超时时间）。
视频就绪后，OpenClaw 会通过内部完成事件唤醒同一会话。
智能体会通过该会话正常的可见回复模式进行报告：自动发送最终回复；如果会话要求使用消息工具，则使用 message(action="send")。如果请求者会话处于非活动状态，或唤醒失败且完成回复中仍缺少生成的媒体， OpenClaw 会以幂等方式直接回退发送该媒体。

任务进行期间，同一会话中重复调用 video_generate 会返回当前任务状态，而不会启动另一次生成。使用 action: "status" 可在不触发新生成的情况下检查状态，或从 CLI 使用 openclaw tasks list / openclaw tasks show <lookup>（参阅后台任务）。在不依赖会话的智能体运行之外（例如直接调用工具），该工具会回退到内联生成，并在同一轮中返回最终媒体路径。当提供商返回字节数据时，生成的视频文件会保存到 OpenClaw 管理的媒体存储中。默认上限为 16MB（共享视频媒体限制）；agents.defaults.mediaMaxMb 可为较大的渲染结果提高此限制。当提供商还返回托管输出 URL 时，如果本地持久化因文件过大而拒绝保存，OpenClaw 会改为交付该 URL，而不会使任务失败。

任务生命周期

状态	含义
`queued`	任务已创建，正在等待提供商接受。
`running`	提供商正在处理（通常需要 30 秒到几分钟，具体取决于提供商和分辨率）。
`succeeded`	视频已就绪；智能体会唤醒并将其发送到对话中。
`failed`	提供商出错或超时；智能体会唤醒并提供错误详情。

从 CLI 检查状态：

openclaw tasks list
openclaw tasks show <lookup>
openclaw tasks cancel <lookup>

支持的提供商

提供商	默认模型	文本	图像参考	视频参考	身份验证
Alibaba	`wan2.6-t2v`	✓	是（远程 URL）	是（远程 URL）	`MODELSTUDIO_API_KEY`
BytePlus（内置）	`seedance-1-0-pro-250528`	✓	最多 2 张图像（首帧 + 尾帧）	-	`BYTEPLUS_API_KEY`
BytePlus 1.5 插件	`seedance-1-5-pro-251215`	✓	最多 2 张图像（通过角色指定首帧 + 尾帧）	-	`BYTEPLUS_API_KEY`
BytePlus Seedance 2.0	`dreamina-seedance-2-0-260128`	✓	最多 9 张参考图像	最多 3 个视频	`BYTEPLUS_API_KEY`
ComfyUI	`workflow`	✓	1 张图像	-	`COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`
DeepInfra	`Pixverse/Pixverse-T2V`	✓	-	-	`DEEPINFRA_API_KEY`
fal	`fal-ai/minimax/video-01-live`	✓	1 张图像；使用 Seedance 参考转视频时最多 9 张	使用 Seedance 参考转视频时最多 3 个视频	`FAL_KEY`
Google	`veo-3.1-fast-generate-preview`	✓	1 张图像	1 个视频	`GEMINI_API_KEY`
MiniMax	`MiniMax-Hailuo-2.3`	✓	1 张图像	-	`MINIMAX_API_KEY` 或 MiniMax OAuth
OpenAI	`sora-2`	✓	1 张图像	1 个视频	`OPENAI_API_KEY`
OpenRouter	`google/veo-3.1-fast`	✓	最多 4 张图像（首帧/尾帧或参考图像）	-	`OPENROUTER_API_KEY`
Qwen	`wan2.6-t2v`	✓	是（远程 URL）	是（远程 URL）	`QWEN_API_KEY`
Runway	`gen4.5`	✓	1 张图像	1 个视频	`RUNWAYML_API_SECRET`
Together	`Wan-AI/Wan2.2-T2V-A14B`	✓	仅限 `Wan-AI/Wan2.2-I2V-A14B`	-	`TOGETHER_API_KEY`
Vydra	`veo3`	✓	1 张图像（`kling`）	-	`VYDRA_API_KEY`
xAI	`grok-imagine-video`	✓	Classic：1 个首帧或 7 张参考图像；1.5：1 帧	Classic：1 个视频	`XAI_API_KEY`

部分提供商接受其他或备用的 API key 环境变量。有关详情，请参阅各个提供商页面。运行 video_generate action=list 可在运行时查看可用的提供商、模型和运行时模式。

能力矩阵

video_generate、契约测试和共享实时扫描使用的显式模式契约：

提供商	`generate`	`imageToVideo`	`videoToVideo`	当前共享实时测试通道
Alibaba	✓	✓	✓	`generate`、`imageToVideo`；跳过 `videoToVideo`，因为该提供商需要远程 `http(s)` 视频 URL
BytePlus	✓	✓	-	`generate`、`imageToVideo`
ComfyUI	✓	✓	-	不在共享扫描中；工作流专用覆盖由 Comfy 测试提供
DeepInfra	✓	-	-	`generate`；插件契约中的原生 DeepInfra 视频 schema 为文生视频
fal	✓	✓	✓	`generate`、`imageToVideo`；仅在使用 Seedance 参考转视频时支持 `videoToVideo`
Google	✓	✓	✓	`generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入
MiniMax	✓	✓	-	`generate`、`imageToVideo`
OpenAI	✓	✓	✓	`generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为此组织/输入路径目前需要提供商侧视频编辑访问权限
OpenRouter	✓	✓	-	`generate`、`imageToVideo`
Qwen	✓	✓	✓	`generate`、`imageToVideo`；跳过 `videoToVideo`，因为该提供商需要远程 `http(s)` 视频 URL
Runway	✓	✓	✓	`generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时运行 `videoToVideo`
Together	✓	✓	-	`generate`、`imageToVideo`
Vydra	✓	✓	-	`generate`；跳过共享 `imageToVideo`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
xAI	✓	✓	✓	Classic 支持所有模式；Video 1.5 仅支持图生视频；远程 MP4 输入使 `videoToVideo` 未纳入共享扫描

工具参数

必填

string

必填

要生成的视频的文本描述。对于 action: "generate"，此项为必填。

内容输入

string

单张参考图像（路径或 URL）。

string[]

多张参考图像（最多 9 张）。

string[]

可选的逐位置角色提示，与合并后的图像列表一一对应。规范值：first_frame、last_frame、reference_image。

string

单个参考视频（路径或 URL）。

string[]

多个参考视频（最多 4 个）。

string[]

可选的逐位置角色提示，与合并后的视频列表一一对应。规范值：reference_video。

string

单个参考音频（路径或 URL）。当提供商支持音频输入时，用作背景音乐或语音参考。

string[]

多个参考音频（最多 3 个）。

string[]

可选的逐位置角色提示，与合并后的音频列表一一对应。规范值：reference_audio。

角色提示会原样转发给提供商。规范值来自 VideoGenerationAssetRole 联合类型，但提供商可能接受其他角色字符串。*Roles 数组的条目数不得超过对应参考列表的条目数；差一错误会导致操作失败并给出明确错误。使用空字符串可将相应位置保留为未设置状态。对于 xAI，将每个图像角色设为 reference_image 以使用其 reference_images 生成模式；对于单图图生视频，请省略角色或使用 first_frame。

样式控制

string

宽高比提示，例如 1:1、16:9、9:16、adaptive，或提供商特定值。OpenClaw 会根据提供商规范化或忽略不支持的值。

string

分辨率提示，例如 360P、480P、540P、720P、768P、1080P、4K，或提供商特定值。OpenClaw 会根据提供商规范化或忽略不支持的值。

number

目标时长，以秒为单位（舍入到最接近的提供商支持值）。

string

提供商支持时使用的尺寸提示。

boolean

在支持时为输出启用生成的音频。与 audioRef*（输入）不同。

boolean

在支持时切换提供商水印。

adaptive 是提供商特定的哨兵值：对于在能力中声明 adaptive 的提供商，该值会原样转发（例如 BytePlus Seedance 使用它根据输入图像尺寸自动检测宽高比）。未声明该能力的提供商会通过工具结果中的 details.ignoredOverrides 显示该值，以便明确看出它已被丢弃。

高级选项

"generate" | "status" | "list"

默认值:"generate"

"status" 返回当前会话任务；"list" 检查提供商。

string

覆盖提供商/模型（例如 runway/gen4.5）。

string

输出文件名提示。

number

可选的提供商操作超时时间，以毫秒为单位。省略时，OpenClaw 会使用已配置的 agents.defaults.mediaModels.video.timeoutMs；否则，如果存在插件编写者设置的提供商默认值，则使用该默认值。

object

JSON 对象形式的提供商特定选项（例如 {"seed": 42, "draft": true}）。声明了类型化 schema 的提供商会验证键和类型；遇到未知键或类型不匹配时，将在回退期间跳过该候选提供商。未声明 schema 的提供商会原样接收选项。运行 video_generate action=list 可查看每个提供商接受的选项。

并非所有提供商都支持所有参数。OpenClaw 会将时长规范化为最接近的提供商支持值；当回退提供商提供不同的控制接口时，还会重新映射转换后的几何提示，例如将尺寸映射为宽高比。真正不支持的覆盖项会尽力忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前导致失败。工具结果会报告已应用的设置；details.normalization 会记录所有从请求值到应用值的转换。

参考输入决定运行时模式：

无参考媒体 -> generate
存在任意图像参考 -> imageToVideo
存在任意视频参考 -> videoToVideo
参考音频输入不会改变解析出的模式；它们会应用于图像/视频参考所选模式之上，并且仅适用于声明了 maxInputAudios 的提供商。

混合使用图像和视频参考并非稳定的共享能力接口。每次请求最好只使用一种参考类型。

回退和类型化选项

某些能力检查在回退层而非工具边界执行，因此即使请求超出主要提供商的限制，仍可在能力足够的回退提供商上运行：

当请求包含音频参考时，如果当前候选提供商未声明 maxInputAudios（或 0），则跳过该候选并尝试下一个候选。对照 maxInputImages/maxInputVideos 检查图像和视频参考数量时，也应用相同的保护机制。
当前候选提供商的 maxDurationSeconds 低于请求的 durationSeconds，且未声明 supportedDurationSeconds 列表 -> 跳过。
请求包含 providerOptions，且当前候选提供商明确声明了类型化 providerOptions schema -> 如果提供的键不在 schema 中或值类型不匹配，则跳过。未声明 schema 的提供商会原样接收选项（向后兼容的透传）。提供商可通过声明空 schema （capabilities.providerOptions: {}）选择不接受任何提供商选项，这会像类型不匹配一样导致跳过。

请求中的第一个跳过原因会以 warn 级别记录，使操作员可以看到主要提供商何时被跳过；后续跳过原因会以 debug 级别记录，以免过长的回退链产生过多日志。如果所有候选提供商都被跳过，汇总错误会包含每个候选提供商的跳过原因。

操作

操作	作用
`generate`	默认。根据给定提示词和可选参考输入创建视频。
`status`	检查当前会话中正在进行的视频任务状态，而不启动另一次生成。
`list`	显示可用的提供商、模型及其能力。

模型选择

OpenClaw 按以下顺序解析模型：

model 工具参数 - 如果智能体在调用中指定了该参数。
配置中的 videoGenerationModel.primary。
按顺序使用 videoGenerationModel.fallbacks。
自动检测 - 从当前默认提供商开始，然后按字母顺序检查其余提供商，选择具有有效身份验证的提供商。

如果提供商失败，将自动尝试下一个候选提供商。如果所有候选提供商均失败，错误会包含每次尝试的详细信息。始终启用跨已验证身份提供商的自动回退。每次调用指定的 model 仍具有最终决定权。

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
        timeoutMs: 180000, // 可选的每工具提供商请求超时覆盖值
      },
    },
  },
}

提供商说明

Alibaba

使用 DashScope / Model Studio 异步端点。参考图像和视频必须是远程 http(s) URL。

BytePlus（内置）

提供商 ID：byteplus。模型：seedance-1-0-pro-250528（默认）、 seedance-1-5-pro-251215。使用统一的 content[] API。最多支持 2 张输入图像（first_frame + last_frame）。按位置传递图像，或显式设置每张图像的 role。支持的 providerOptions 键：seed（数字）、draft（布尔值 - 强制使用 480p）、camera_fixed（布尔值）。

BytePlus Seedance 1.5 插件

需要 @openclaw/byteplus-modelark 插件（外部插件，非内置）。提供商 ID：byteplus-seedance15。模型： seedance-1-5-pro-251215。使用统一的 content[] API。最多支持 2 张输入图像（first_frame + last_frame）。所有输入都必须是远程 https:// URL。在每张图像上设置 role: "first_frame" / "last_frame"，或按位置传递图像。aspectRatio: "adaptive" 会根据输入图像自动检测宽高比。 audio: true 映射到 generate_audio。providerOptions.seed （数字）会被转发。

BytePlus Seedance 2.0

需要 @openclaw/byteplus-modelark 插件（外部插件，非内置）。提供商 ID：byteplus-seedance2。模型： dreamina-seedance-2-0-260128、 dreamina-seedance-2-0-fast-260128。使用统一的 content[] API。最多支持 9 张参考图像、 3 个参考视频和 3 个参考音频。所有输入都必须是远程 https:// URL。在每项资源上设置 role - 支持的值： "first_frame"、"last_frame"、"reference_image"、 "reference_video"、"reference_audio"。aspectRatio: "adaptive" 会根据输入图像自动检测宽高比。 audio: true 映射到 generate_audio。providerOptions.seed （数字）会被转发。

ComfyUI

工作流驱动的本地或云端执行。通过配置的图支持文本生成视频和图像生成视频。

fal

对长时间运行的作业使用队列支持的流程。默认情况下，OpenClaw 最多等待 20 分钟，之后会将仍在进行中的 fal 队列作业视为超时。大多数 fal 视频模型接受单个图像引用。Seedance 2.0 引用生成视频模型最多接受 9 个图像、3 个视频和 3 个音频引用，引用文件总数最多为 12 个。

Google (Gemini / Veo)

支持一个图像或一个视频引用。在 Gemini API 路径中，生成音频的请求会被忽略并发出警告，因为该 API 会拒绝当前 Veo 视频生成使用的 generateAudio 参数。

MiniMax

仅支持单个图像引用。MiniMax 接受 768P 和 1080P 分辨率；提交前，720P 等请求会被规范化为最接近的支持值。

OpenAI

仅转发 size 覆盖项。其他样式覆盖项（aspectRatio、resolution、audio、watermark）会被忽略并发出警告。

OpenRouter

使用 OpenRouter 的异步 /videos API。OpenClaw 提交作业、轮询 polling_url，然后下载 unsigned_urls 或文档中说明的作业内容端点。内置的 google/veo-3.1-fast 默认值声明支持 4/6/8 秒时长、720P/1080P 分辨率以及 16:9/9:16 宽高比。

Qwen

使用与 Alibaba 相同的 DashScope 后端。引用输入必须是远程 http(s) URL；本地文件会被预先拒绝。

Runway

通过数据 URI 支持本地文件。视频生成视频需要 runway/gen4_aleph。纯文本运行提供 16:9 和 9:16 宽高比。

Together

仅支持单个图像引用。

Vydra

直接使用 https://www.vydra.ai/api/v1，以避免重定向导致身份验证信息丢失。内置的 veo3 仅支持文本生成视频；kling 需要远程图像 URL。

xAI

默认的 grok-imagine-video 模型支持文本生成视频、单个首帧图像生成视频、通过 xAI reference_images 输入最多 7 个 reference_image，以及远程视频编辑/扩展流程。生成默认使用 480P；省略 aspectRatio 时，单图像生成视频会继承源图像比例。视频编辑/扩展会继承输入几何尺寸，并且不接受宽高比或分辨率覆盖。扩展接受 2-10 秒。grok-imagine-video-1.5 仅支持图像生成视频：必须恰好提供一个图像。它支持 1-15 秒以及 480P、720P 或 1080P，默认值为 480P；省略 aspectRatio 可继承源图像比例。预览版和带日期的 1.5 标识符会接受相同的验证，并保持不变地转发。

提供商能力模式

共享视频生成契约支持特定于模式的能力，而不仅是扁平的聚合限制。新的提供商实现应优先使用显式模式块：

capabilities: {
  generate: {
    maxVideos: 1,
    maxDurationSeconds: 10,
    supportsResolution: true,
  },
  imageToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputImages: 1,
    maxInputImagesByModel: { "provider/reference-to-video": 9 },
    maxDurationSeconds: 5,
  },
  videoToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputVideos: 1,
    maxDurationSeconds: 5,
  },
}

maxInputImages 和 maxInputVideos 等扁平聚合字段 不足以声明对转换模式的支持。提供商应显式声明 generate、imageToVideo 和 videoToVideo，使实时测试、契约测试以及共享的 video_generate 工具能够以确定性方式验证模式支持。当提供商中的某个模型比其他模型支持更多引用输入时，请使用 maxInputImagesByModel、maxInputVideosByModel 或 maxInputAudiosByModel，而不是提高整个模式的限制。

实时测试

共享内置提供商的选择性实时覆盖：

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts

仓库封装命令：

pnpm test:live:media video

默认情况下，此实时测试文件优先使用已导出的提供商环境变量，而不是已存储的身份验证配置文件，并默认运行适用于发布的冒烟测试：

扫描中的每个非 FAL 提供商均使用 generate。
一秒钟的龙虾提示词。
来自 OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS 的每提供商操作上限（默认为 180000）。

FAL 需要选择启用，因为提供商侧的队列延迟可能主导发布耗时：

pnpm test:live:media video --video-providers fal

设置 OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 后，还会运行已声明的转换模式；共享扫描可以使用本地媒体安全地测试这些模式：

当 capabilities.imageToVideo.enabled 时运行 imageToVideo。
当 capabilities.videoToVideo.enabled 且提供商/模型在共享扫描中接受缓冲区支持的本地视频输入时，运行 videoToVideo。

目前，仅当选择 runway/gen4_aleph 时，共享的 videoToVideo 实时通道才会覆盖 runway。

配置

在 OpenClaw 配置中设置默认视频生成模型：

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-r2v-flash"],
      },
    },
  },
}

或通过 CLI 设置：

openclaw config set agents.defaults.mediaModels.video.primary "qwen/wan2.6-t2v"

概览

Plugins

扩展

Building plugins

技能

自动化与任务

内置工具

代理协作

快速开始

异步生成的工作方式

任务生命周期

支持的提供商

能力矩阵

工具参数

必填

内容输入

样式控制

高级选项

回退和类型化选项

操作

模型选择

提供商说明

提供商能力模式

实时测试

配置

相关内容

​快速开始

​异步生成的工作方式

​任务生命周期

​支持的提供商

​能力矩阵

​工具参数

​必填

​内容输入

​样式控制

​高级选项

​回退和类型化选项

​操作

​模型选择

​提供商说明

​提供商能力模式

​实时测试

​配置

​相关内容

快速开始

异步生成的工作方式

任务生命周期

支持的提供商

能力矩阵

工具参数

必填

内容输入

样式控制

高级选项

回退和类型化选项

操作

模型选择

提供商说明

提供商能力模式

实时测试

配置

相关内容