跳转至

视频生成

OpenClaw 智能体通过 video_generate 根据文本提示、参考图像或现有视频生成视频。支持 18 个提供商后端;智能体会根据配置和可用的 API 密钥自动选择正确的后端。这 18 个提供商 ID 涵盖 17 个插件;MiniMax 注册了 API 密钥(minimax)和 OAuth(minimax-portal)两个独立后端。

Note

video_generate 仅在至少有一个视频生成提供商可用时才会出现。如果它不在你的智能体工具中,请设置提供商 API 密钥或配置 agents.defaults.mediaModels.video。

video_generate 有三种运行时模式,根据调用中的参考输入解析:

  • generate - 无参考媒体(文本生成视频)。
  • imageToVideo - 一个或多个参考图像。
  • videoToVideo - 一个或多个参考视频。

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

快速开始

1. 配置认证

为任何受支持的提供商设置 API 密钥:

export GEMINI_API_KEY="your-key"

2. 选择默认模型(可选)

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

3. 询问智能体

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

智能体会自动调用 video_generate。无需工具白名单。

异步生成的工作原理

视频生成是异步的:

  1. OpenClaw 将请求提交给提供商,并立即返回任务 ID。
  2. 提供商在后台处理任务(通常需要 30 秒到几分钟,具体取决于提供商和分辨率;慢速队列型提供商最长可运行至配置的超时时间)。
  3. 当视频准备好时,OpenClaw 使用内部完成事件唤醒同一会话。
  4. 智能体通过会话正常的可见回复模式报告结果:自动最终回复,或者当会话需要消息工具时使用 message(action="send")。如果请求方会话处于非活动状态,或其唤醒失败且完成回复中仍缺少生成的媒体,OpenClaw 会发送一条附带该媒体的幂等直接回退消息。

当任务正在进行中时,同一聊天中重复的 video_generate 调用会返回当前任务状态,而不会开始另一次生成。使用 action: "status" 检查状态,而不会触发新的生成。直接聊天即使共享主会话记录,也会保留各自独立的任务;完成结果会返回给请求方。

在非会话型智能体运行之外(例如直接工具调用),该工具会回退到内联生成,并在同一轮次中返回最终媒体路径。

当提供商以字节形式返回结果时,生成的视频文件会保存到 OpenClaw 管理的媒体存储中。默认上限为 16MB(共享视频媒体限制);agents.defaults.mediaMaxMb 可提高该上限以支持更大的渲染。当提供商同时返回托管输出 URL 时,如果本地持久化拒绝保存过大的文件,OpenClaw 会传递该 URL,而不是让任务失败。

任务生命周期

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

支持的提供商

提供商 默认模型 文本 图像参考 视频参考 认证
Alibaba wan2.6-t2v ✓ 本地或远程(i2v 和 Wan 2.7) 支持(远程 URL) MODELSTUDIO_API_KEY
BytePlus 插件 seedance-1-0-pro-250528 ✓ 最多 2 张图像(首帧 + 末帧) - BYTEPLUS_API_KEY
BytePlus 1.5 插件 seedance-1-5-pro-251215 ✓ 最多 2 张图像(通过 role 指定首帧 + 末帧) - 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
提供商 默认模型 文本 图像参考 视频参考 认证
Kie AI kling-2.6/text-to-video ✓ 1 个本地或远程图像 - KIE_API_KEY
MiniMax MiniMax-Hailuo-2.3 ✓ 1 个图像 - MINIMAX_API_KEY 或 MiniMax OAuth
Novita wan2.6-t2v ✓ 1 个图像(URL 或本地文件) - NOVITA_API_KEY
OpenRouter google/veo-3.1-fast ✓ 最多 4 个图像(首帧/尾帧或参考图) - OPENROUTER_API_KEY
PixVerse v6 ✓ 1 个本地或远程图像 - PIXVERSE_API_KEY
Qwen wan2.6-t2v ✓ 本地或远程(i2v 和 Wan 2.7) 是(远程 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
Z.AI cogvideox-3 ✓ 1 个图像(URL 或本地文件) - ZAI_API_KEY

部分提供商接受额外的或替代的 API 密钥环境变量。有关详细信息,请参见各个提供商页面。

运行 video_generate action=list 可在运行时检查可用的提供商、模型和运行时模式。

功能矩阵

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

提供商 generate imageToVideo videoToVideo 共享实时通道
Alibaba ✓ ✓ ✓ generate、本地 imageToVideo(默认路由到 wan2.6-i2v);videoToVideo 需要远程 http(s) 视频 URL
BytePlus ✓ ✓ - generate、imageToVideo
ComfyUI ✓ ✓ - 不在共享扫描中;工作流特定覆盖位于 Comfy 测试中
DeepInfra ✓ - - generate;原生 DeepInfra 视频模式在插件契约中为文本生成视频
fal ✓ ✓ ✓ generate、imageToVideo;仅在使用 Seedance 参考生成视频时支持 videoToVideo
Google ✓ ✓ ✓ generate、imageToVideo;共享 videoToVideo 被跳过,因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入
Kie AI ✓ ✓ - generate、imageToVideo
MiniMax ✓ ✓ - generate、imageToVideo
Novita ✓ ✓ - generate、imageToVideo
OpenRouter ✓ ✓ - generate、imageToVideo
PixVerse ✓ ✓ - generate、imageToVideo
Qwen ✓ ✓ ✓ generate、本地 imageToVideo(默认路由到 wan2.6-i2v);videoToVideo 需要远程 http(s) 视频 URL
Runway ✓ ✓ ✓ generate、imageToVideo;仅当所选模型为 runway/gen4_aleph 时运行 videoToVideo
提供商 generate imageToVideo videoToVideo 共享实时通道
Together ✓ ✓ - generate, imageToVideo
Vydra ✓ ✓ - generate;共享 imageToVideo 被跳过,因为 veo3 仅支持文本,且 kling 需要远程图像 URL
xAI ✓ ✓ ✓ Classic 支持所有模式;Video 1.5 仅支持图像转视频;远程 MP4 输入使 videoToVideo 不进入共享扫描
Z.AI ✓ ✓ - generate, imageToVideo

工具参数

必需

prompt string (path) 必需
要生成的视频的文字描述。action: "generate" 时必填。

内容输入

image string (path)
单个参考图像(路径或 URL)。
images string[] (path)
多个参考图像(最多 9 个)。
imageRoles string[] (path)
可选的按位置角色提示,与合并后的图像列表一一对应。 规范值:first_frame、last_frame、reference_image。
video string (path)
单个参考视频(路径或 URL)。
videos string[] (path)
多个参考视频(最多 4 个)。
videoRoles string[] (path)
可选的按位置角色提示,与合并后的视频列表一一对应。 规范值:reference_video。
audioRef string (path)
单个参考音频(路径或 URL)。当提供商支持音频输入时,用于背景音乐或语音 参考。
audioRefs string[] (path)
多个参考音频(最多 3 个)。
audioRoles string[] (path)
可选的按位置角色提示,与合并后的音频列表一一对应。 规范值:reference_audio。

Note

角色提示会按原样转发给提供商。规范值来自 VideoGenerationAssetRole 联合类型,但提供商可能接受额外的 角色字符串。*Roles 数组的条目数不得超过对应参考列表;差一错误会以清晰的错误失败。 使用空字符串表示保留某个槽位未设置。对于 xAI,将所有图像角色设置为 reference_image 以使用其 reference_images 生成模式;对于单图像转视频,省略角色 或使用 first_frame。 重复的参考会保留其位置,因此同一图像可以同时为循环片段提供 first_frame 和 last_frame。

样式控制

aspectRatio string (path)
宽高比提示,例如 1:1、16:9、9:16、adaptive 或提供商特定值。OpenClaw 会按提供商规范化或忽略不支持的值。
resolution string (path)
分辨率提示,例如 360P、480P、540P、720P、768P、1080P、4K 或提供商特定值。OpenClaw 会按提供商规范化或忽略不支持的值。
durationSeconds number (path)
目标时长(秒)(四舍五入到提供商支持的最接近值)。
size string (path)
当提供商支持时,尺寸提示。
audio boolean (path)
在支持时启用输出中的生成音频。与 audioRef*(输入)不同。
watermark boolean (path)
在支持时切换提供商水印。

adaptive 是提供商特定的哨兵值:它会按原样转发给 在能力中声明 adaptive 的提供商(例如 BytePlus Seedance 使用它根据输入图像尺寸自动检测比例)。未声明该能力的提供商会通过 工具结果中的 details.ignoredOverrides 暴露该值,以便可见该值被丢弃。

高级

action "generate" | "status" | "list" (path) 默认:generate
"status" 返回当前会话任务;"list" 检查提供商。
model string (path)
提供商/模型覆盖(例如 runway/gen4.5)。
filename string (path)
输出文件名提示。
timeoutMs number (path)
可选的提供商操作超时(毫秒)。省略时,如果已配置,OpenClaw 使用 agents.defaults.mediaModels.video.timeoutMs;否则,如果存在插件编写的提供商默认值,则使用该默认值。

对于 Runway 和 Together,显式超时会同时覆盖提交、轮询和 下载。单个 HTTP 请求仍保留 120 秒限制。 如果没有显式超时,它们的 120 秒轮询预算从提交后开始;请求和下载限制仍分别计算。

providerOptions object (path)
提供商特定选项,作为 JSON 对象(例如 {"seed": 42, "draft": true})。 声明了类型化 schema 的提供商会验证键和类型;未知键或类型不匹配会在回退期间跳过该候选项。未声明 schema 的提供商会按原样接收选项。运行 video_generate action=list 可查看每个提供商接受哪些选项。

Note

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

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

  • 无参考媒体 -> generate
  • 任意图像参考 -> imageToVideo
  • 任意视频参考 -> videoToVideo
  • 参考音频输入不会改变解析出的模式;它们叠加在 图像/视频参考所选定的模式之上,并且仅对声明了 maxInputAudios 的提供商有效。

混合图像和视频引用不是稳定的共享能力面。 每个请求优先使用一种引用类型。

回退与类型化选项

一些能力检查在回退层而不是工具边界处应用,因此超出主提供商限制的请求仍可在有能力的回退上运行:

  • 当请求包含音频引用时,声明没有 maxInputAudios(或 0)的当前候选会被跳过;然后尝试下一个候选。相同的保护也适用于针对 maxInputImages/maxInputVideos 的图像和视频引用数量。
  • 当前候选的 maxDurationSeconds 低于请求的 durationSeconds,且未声明 supportedDurationSeconds 列表 -> 跳过。
  • 请求包含 providerOptions,且当前候选显式声明了类型化的 providerOptions schema -> 如果提供的键不在 schema 中或值类型不匹配,则跳过。未声明 schema 的提供商会按原样接收选项(向后兼容的直通)。提供商可以通过声明空 schema(capabilities.providerOptions: {})来退出所有提供商选项,这会导致与类型不匹配相同的跳过。

请求中的第一个跳过原因会以 warn 级别记录日志,以便操作员看到其主提供商被跳过的情况;后续跳过以 debug 级别记录日志,以保持较长的回退链安静。如果所有候选都被跳过,聚合错误会包含每个候选的跳过原因。 如果某个候选在生成期间失败,其提供商、模型和错误会在尝试下一个候选之前以 warn 级别记录日志。

操作

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

模型选择

对于 video_generate,OpenClaw 按以下顺序解析模型:

  1. model 工具参数 - 设置时,仅尝试该模型。
  2. 配置中的 agents.defaults.mediaModels.video.primary。
  3. 按顺序使用 agents.defaults.mediaModels.video.fallbacks。
  4. 自动检测 - 仅当未配置主模型或回退模型时使用,采用已配置的提供商默认值。当前默认提供商排在第一位,然后其余提供商按字母顺序排列。

如果某个提供商失败,会自动尝试下一个候选。如果所有候选都失败,错误会包含每次尝试的详细信息。

显式视频模型配置会将回退限制在已配置列表中;OpenClaw 不会追加自动检测到的提供商。

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "google/veo-3.1-fast-generate-preview",
          fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
          timeoutMs: 180000, // optional per-tool provider request timeout override
        },
      },
    },
  },
}

提供商说明

Alibaba

使用 DashScope / Model Studio 异步端点。图生视频和 Wan 2.7 参考图像接受本地文件或远程 URL;本地图像 以 data URI 发送,编码前每张图像最多 20 MB。 具有恰好一个图像且没有视频的文本生视频模型,如果该模型在已知目录中,会使用其 同代图生视频对应模型,例如从 wan2.6-t2v 到 wan2.6-i2v。结果会报告 解析后的模型。参考视频和 Wan 2.6 参考生视频图像 仍需要远程 http(s) URL。

BytePlus 插件

需要官方 @openclaw/byteplus-provider 插件。 提供商 id:byteplus。

模型:seedance-1-0-pro-250528(默认)、 seedance-1-5-pro-251215。

使用统一的 content[] API。支持最多 2 张输入图像 (first_frame + last_frame)。按位置传递图像,或显式设置每张图像的 role。

支持的 providerOptions 键:seed(number)、draft(boolean - 强制 480p)、camera_fixed(boolean)。

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 (number)会被转发。

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 (number)会被转发。

ComfyUI

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

fal

使用基于队列的流程处理长时间运行的任务。OpenClaw 默认最多等待 20 分钟,才将正在进行的 fal 队列任务视为超时。大多数 fal 视频模型 接受单个图像引用。Seedance 2.0 参考生视频 模型接受最多 9 张图像、3 个视频和 3 个音频引用,且 参考文件总数最多为 12 个。

Google (Gemini / Veo)

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

Kie AI

使用 Kie 的市场任务 API 来支持 Kling、Grok Imagine、Wan、Hailuo 和 Seedance。单个参考图像会自动选择该系列的图生视频变体。本地图像通过 Kie 文档中的 base64 上传 API 上传。生成可能需要几分钟;提供商默认最多等待十分钟。有关模型特定限制,请参阅 Kie AI。

MiniMax

仅支持单个图像参考。MiniMax 接受 768P 和 1080P 分辨率;诸如 720P 的请求会在提交前规范化为最接近的支持值。

Novita

使用原生 Wan 2.6 和 Hailuo 2.3 异步路由。当使用 -t2v 模型并提供一个图像时,会选择该系列的 -i2v 路由。两个系列都接受本地图像作为 data URI。Wan 默认输出静音;设置 audio: true 以生成音频。Hailuo 仅在 6 秒时支持 1080P。有关模型 ID 和提供商选项,请参阅 NovitaAI。

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 后端。图生视频和 Wan 2.7 图像参考接受编码前最大 20 MB 的本地文件或远程 URL。当恰好有一个图像且没有视频时,wan2.6-t2v 会自动使用 wan2.6-i2v,并在结果中报告该模型。参考视频以及 Wan 2.6 参考生视频所需的图像需要远程 http(s) URL。

Runway

支持通过 data 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 标识符接受相同的验证,并原样转发。

Z.AI

CogVideoX-3 支持文本或一个 PNG/JPEG 图像,包括以 data URI 发送的、最大 5 MB 的本地文件。时长会规范化为 5 或 10 秒;audio: true 启用声音。视频使用已配置的全局或中国区域中的通用 API 端点,包括当聊天使用 Coding Plan 端点时。有关尺寸和提供商选项,请参阅 Z.AI。

提供商能力模式

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

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。

在共享扫描中,基于缓冲区的 videoToVideo 仅对 runway 使用 runway/gen4_aleph 时运行,并且仅对 fal 使用 reference-to-video 模型时运行。

配置

在你的 OpenClaw 配置中设置默认视频生成模型:

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

或通过 CLI:

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw