视频生成

OpenClaw 代理通过 video_generate 从文本提示、参考图像或现有视频生成视频。支持十八个提供商后端；代理会根据配置和可用的 API 密钥自动选择正确的后端。18 个提供商 ID 涵盖 17 个插件；MiniMax 分别注册了 API 密钥（minimax）和 OAuth（minimax-portal）后端。

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，而不是让任务失败。

任务生命周期¶

支持的提供商¶

部分提供商支持额外的或替代的 API 密钥环境变量。有关详细信息，请参阅各个提供商页面。

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

能力矩阵¶

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

工具参数¶

必需¶

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。

样式控制¶

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 是提供商特定的哨兵值：它会原样转发给 在 capabilities 中声明 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；否则，如果存在插件编写的提供商默认值，则使用该默认值。

providerOptions object (path)

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

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

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

混合图像和视频引用不是稳定且共享的能力接口。建议每个请求仅使用一种引用类型。

回退与类型化选项¶

某些能力检查应用于回退层而不是工具边界，因此超出主要提供者限制的请求仍然可以在有能力处理该请求的回退提供者上运行：

• 当请求包含音频引用时，声明没有 maxInputAudios（或为 0）的当前候选会被跳过，然后尝试下一个候选。图像和视频的引用数量也会依据 maxInputImages/maxInputVideos 进行同样的检查。
• 当前候选的 maxDurationSeconds 低于请求的 durationSeconds，且未声明 supportedDurationSeconds 列表 -> 跳过。
• 请求包含 providerOptions，且当前候选明确声明了带类型的 providerOptions 模式 -> 如果所提供的键不在模式中或值的类型不匹配，则跳过。未声明模式的提供者会按原样接收选项（向后兼容的透传）。提供者可以通过声明空模式（capabilities.providerOptions: {}）选择退出所有提供者选项，这会触发与类型不匹配相同的跳过。

请求中的第一个跳过原因会在 warn 级别记录日志，以便操作员了解其主要提供者何时被略过；后续的跳过会在 debug 级别记录日志，以保持较长的回退链安静。如果所有候选都被跳过，聚合错误会包含每个候选的跳过原因。如果某个候选在生成过程中失败，其提供者、模型和错误会在尝试下一个候选之前以 warn 级别记录日志。

操作¶

模型选择¶

对于 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
        },
      },
    },
  },
}

提供者说明¶

提供商能力模式¶

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

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"

相关¶

• Alibaba Model Studio
• BytePlus
• ComfyUI
• 配置参考
• fal
• Google (Gemini)
• Kie AI
• MiniMax
• 模型
• NovitaAI
• OpenRouter
• PixVerse
• Qwen
• Runway
• Together AI
• 工具概览
• Vydra
• xAI
• Z.AI
• 媒体概览 - 媒体工具如何协同工作