diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index 5976ad5c8..f3d968990 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -2,33 +2,34 @@ read_when: - 通过智能体生成视频 - 配置视频生成提供商和模型 - - 理解 `video_generate` 工具参数 -summary: 使用 12 个提供商后端，从文本、图片或现有视频生成视频 + - 了解 `video_generate` 工具参数 +summary: 使用 14 个提供商后端，从文本、图像或现有视频生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-11T01:59:36Z" + generated_at: "2026-04-11T09:24:44Z" model: gpt-5.4 provider: openai - source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245 + source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263 source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -OpenClaw 智能体可以根据文本提示、参考图片或现有视频生成视频。当前支持 12 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 +OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。当前支持 14 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 -只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你在智能体工具中没有看到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。 +只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你在智能体工具中看不到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。 OpenClaw 将视频生成视为三种运行时模式： - `generate`：用于没有参考媒体的文生视频请求 -- `imageToVideo`：当请求包含一个或多个参考图片时使用 +- `imageToVideo`：当请求包含一个或多个参考图像时使用 - `videoToVideo`：当请求包含一个或多个参考视频时使用 -提供商可以支持这些模式中的任意子集。工具会在提交前校验当前活动模式，并在 `action=list` 中报告支持的模式。 +提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前 +模式，并在 `action=list` 中报告支持的模式。 ## 快速开始 @@ -46,33 +47,33 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. 向智能体发出请求： -> 生成一个 5 秒长、电影感十足的视频，内容是一只友好的龙虾在日落时分冲浪。 +> 生成一个 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。 -智能体会自动调用 `video_generate`。不需要配置工具允许列表。 +智能体会自动调用 `video_generate`。不需要配置工具白名单。 ## 生成视频时会发生什么 -视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时： +视频生成是异步的。当智能体在某个会话中调用 `video_generate` 时： 1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。 -2. 提供商会在后台处理该任务（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 -3. 当视频准备就绪后，OpenClaw 会通过内部完成事件唤醒同一个会话。 -4. 智能体会将生成完成的视频发回原始对话中。 +2. 提供商在后台处理该任务（通常需要 30 秒到 5 分钟，取决于提供商和分辨率）。 +3. 视频准备就绪后，OpenClaw 会通过内部完成事件唤醒同一个会话。 +4. 智能体会将最终生成的视频发布回原始对话中。 -当某个任务正在处理中时，同一会话中的重复 `video_generate` 调用不会启动新的生成任务，而是返回当前任务状态。你可以使用 `openclaw tasks list` 或 `openclaw tasks show ` 在 CLI 中查看进度。 +当某个任务正在处理中时，同一会话中的重复 `video_generate` 调用不会再次启动新的生成任务，而是返回当前任务状态。你可以使用 `openclaw tasks list` 或 `openclaw tasks show ` 在 CLI 中检查进度。 -在没有会话支撑的智能体运行之外（例如，直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 +在不依赖会话的智能体运行场景之外（例如，直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 ### 任务生命周期 -每个 `video_generate` 请求都会经过四个状态： +每个 `video_generate` 请求都会经历四种状态： -1. **queued** -- 任务已创建，等待提供商接受。 -2. **running** -- 提供商正在处理中（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 +1. **queued** -- 任务已创建，正在等待提供商接受。 +2. **running** -- 提供商正在处理（通常需要 30 秒到 5 分钟，取决于提供商和分辨率）。 3. **succeeded** -- 视频已准备就绪；智能体会被唤醒并将其发布到对话中。 4. **failed** -- 提供商错误或超时；智能体会携带错误详情被唤醒。 -通过 CLI 检查状态： +可通过 CLI 检查状态： ```bash openclaw tasks list @@ -80,101 +81,151 @@ openclaw tasks show openclaw tasks cancel ``` -防止重复：如果当前会话已经有一个状态为 `queued` 或 `running` 的视频任务，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式查询状态，而不会触发新的生成。 +防止重复：如果当前会话中已经有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成。 ## 支持的提供商 -| 提供商 | 默认模型 | 文本 | 图片参考 | 视频参考 | API 密钥 | -| -------- | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | -| BytePlus（国际版） | `seedance-1-0-lite-t2v-250428` | 是 | 1 张图片 | 否 | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | 是 | 1 张图片 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图片 | 否 | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图片 | 1 个视频 | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图片 | 否 | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | 是 | 1 张图片 | 1 个视频 | `OPENAI_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` | 是 | 1 张图片 | 否 | `TOGETHER_API_KEY` | -| Vydra | `veo3` | 是 | 1 张图片（`kling`） | 否 | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | 是 | 1 张图片 | 1 个视频 | `XAI_API_KEY` | +| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 | +| ------ | -------- | ---- | -------- | -------- | -------- | +| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | +| BytePlus（1.0） | `seedance-1-0-pro-250528` | 是 | 最多 2 张图像（仅限 I2V 模型；首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 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` | +| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图像 | 否 | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_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` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` | +| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 个视频 | `XAI_API_KEY` | -某些提供商接受额外的或替代的 API 密钥环境变量。详情请参阅各个[提供商页面](#related)。 +某些提供商还接受额外或替代的 API 密钥环境变量。详见各个[提供商页面](#related)。 -运行 `video_generate action=list` 可在运行时查看可用的提供商、模型和运行模式。 +运行 `video_generate action=list` 以在运行时检查可用的提供商、模型和 +运行时模式。 ### 声明的能力矩阵 -这是 `video_generate`、契约测试以及共享实时扫描所使用的显式模式契约。 +这是 `video_generate`、契约测试 +以及共享实时扫描所使用的显式模式契约。 | 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时通道 | -| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL | -| BytePlus（国际版） | 是 | 是 | 否 | `generate`、`imageToVideo` | -| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；与工作流相关的覆盖由 Comfy 测试提供 | -| fal | 是 | 是 | 否 | `generate`、`imageToVideo` | -| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 | -| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` | -| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前这个组织/输入路径需要提供商侧的 inpaint/remix 访问 | -| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL | -| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 仅在所选模型为 `runway/gen4_aleph` 时运行 | -| Together | 是 | 是 | 否 | `generate`、`imageToVideo` | -| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 被跳过，因为内置的 `veo3` 仅支持文本，而内置的 `kling` 需要远程图片 URL | -| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商当前需要远程 MP4 URL | +| ------ | ---------- | -------------- | -------------- | ---------------- | +| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL | +| BytePlus | 是 | 是 | 否 | `generate`、`imageToVideo` | +| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；特定于 workflow 的覆盖由 Comfy 测试承担 | +| fal | 是 | 是 | 否 | `generate`、`imageToVideo` | +| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 | +| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` | +| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前此组织/输入路径需要提供商侧的 inpaint/remix 访问能力 | +| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL | +| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时才运行 `videoToVideo` | +| Together | 是 | 是 | 否 | `generate`、`imageToVideo` | +| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 被跳过，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL | +| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商当前需要远程 MP4 URL | ## 工具参数 ### 必填 | 参数 | 类型 | 说明 | -| --------- | ------ | ----------------------------------------------------------------------------- | -| `prompt` | string | 要生成的视频的文本描述（当 `action: "generate"` 时必填） | +| ---- | ---- | ---- | +| `prompt` | string | 要生成的视频的文本描述（`action: "generate"` 时必填） | ### 内容输入 | 参数 | 类型 | 说明 | -| --------- | -------- | ------------------------------------ | -| `image` | string | 单个参考图片（路径或 URL） | -| `images` | string[] | 多个参考图片（最多 5 张） | -| `video` | string | 单个参考视频（路径或 URL） | -| `videos` | string[] | 多个参考视频（最多 4 个） | +| ---- | ---- | ---- | +| `image` | string | 单个参考图像（路径或 URL） | +| `images` | string[] | 多个参考图像（最多 9 张） | +| `imageRoles` | string[] | 与合并后图像列表按位置对应的可选角色提示。规范值：`first_frame`、`last_frame`、`reference_image` | +| `video` | string | 单个参考视频（路径或 URL） | +| `videos` | string[] | 多个参考视频（最多 4 个） | +| `videoRoles` | string[] | 与合并后视频列表按位置对应的可选角色提示。规范值：`reference_video` | +| `audioRef` | string | 单个参考音频（路径或 URL）。例如，当提供商支持音频输入时，可用于背景音乐或语音参考 | +| `audioRefs` | string[] | 多个参考音频（最多 3 个） | +| `audioRoles` | string[] | 与合并后音频列表按位置对应的可选角色提示。规范值：`reference_audio` | + +角色提示会按原样转发给提供商。规范值来自 +`VideoGenerationAssetRole` 联合类型，但提供商也可能接受额外的 +角色字符串。`*Roles` 数组的条目数不能多于对应的 +参考列表；如果出现数量偏差，会返回清晰的错误。 +使用空字符串可使某个位置保持未设置。 ### 风格控制 | 参数 | 类型 | 说明 | -| ----------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | `480P`、`720P`、`768P` 或 `1080P` | -| `durationSeconds` | number | 目标时长（秒）（会四舍五入到最接近的提供商支持值） | -| `size` | string | 当提供商支持时使用的尺寸提示 | -| `audio` | boolean | 在支持时启用生成音频 | -| `watermark` | boolean | 在支持时切换提供商水印 | +| ---- | ---- | ---- | +| `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` 或 `adaptive` | +| `resolution` | string | `480P`、`720P`、`768P` 或 `1080P` | +| `durationSeconds` | number | 目标时长（秒）（会四舍五入到最接近的提供商支持值） | +| `size` | string | 当提供商支持时使用的尺寸提示 | +| `audio` | boolean | 在支持时为输出启用生成音频。与 `audioRef*`（输入）不同 | +| `watermark` | boolean | 在支持时切换提供商水印 | + +`adaptive` 是一个提供商特定的哨兵值：它会被原样转发给 +在其能力声明中包含 `adaptive` 的提供商（例如 BytePlus +Seedance 会使用它根据输入图像 +尺寸自动检测比例）。对于未声明该值的提供商， +该值会通过工具结果中的 +`details.ignoredOverrides` 暴露出来，以便明确看到它被忽略。 ### 高级 | 参数 | 类型 | 说明 | -| ---------- | ------ | ----------------------------------------------- | -| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | -| `model` | string | 提供商/模型覆盖值（例如 `runway/gen4.5`） | +| ---- | ---- | ---- | +| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | +| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） | | `filename` | string | 输出文件名提示 | +| `providerOptions` | object | 以 JSON 对象形式传递的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。声明了类型化 schema 的提供商会验证键名和类型；未知键名或类型不匹配会导致该候选项在回退时被跳过。未声明 schema 的提供商会按原样接收这些选项。运行 `video_generate action=list` 可查看各提供商接受哪些选项 | -并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为最接近的提供商支持值，还会在回退提供商暴露不同控制界面时，将类似 size 到宽高比之类的几何提示重新映射。真正不支持的覆盖项会尽力忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 +并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为最接近的提供商支持值，也会在回退提供商暴露不同控制面时，重新映射像 size 到 aspect-ratio 这样的几何提示。真正不受支持的覆盖项会尽力忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值会反映实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 -参考输入还会决定运行时模式： +参考输入也会决定运行时模式： - 没有参考媒体：`generate` -- 任何图片参考：`imageToVideo` -- 任何视频参考：`videoToVideo` +- 存在任意图像参考：`imageToVideo` +- 存在任意视频参考：`videoToVideo` +- 参考音频输入不会改变已解析的模式；它们会叠加应用在图像/视频参考所选择的模式之上，并且仅适用于声明了 `maxInputAudios` 的提供商 -图片和视频混合引用并不是稳定的共享能力接口。 -每次请求最好只使用一种参考类型。 +图像和视频参考混用并不是一个稳定的共享能力面。 +建议每次请求只使用一种参考类型。 + +#### 回退与类型化选项 + +某些能力检查是在回退层而不是 +工具边界层应用的，这样即使请求超出了主提供商的限制， +仍然可以在具备相应能力的回退提供商上运行： + +- 如果当前候选项未声明 `maxInputAudios`（或将其声明为 + `0`），并且请求包含音频参考， + 则会跳过该候选项，并尝试下一个候选项。 +- 如果当前候选项的 `maxDurationSeconds` 低于请求的 + `durationSeconds`，且该候选项未声明 + `supportedDurationSeconds` 列表，则会跳过该候选项。 +- 如果请求包含 `providerOptions`，且当前候选项 + 明确声明了类型化的 `providerOptions` schema， + 当提供的键名不在 schema 中或值类型 + 不匹配时，该候选项会被跳过。尚未声明 schema 的提供商会按原样接收 + 这些选项（向后兼容透传）。提供商可以 + 通过声明一个空 schema + （`capabilities.providerOptions: {}`）来显式禁用所有 provider options， + 这会导致与类型不匹配相同的跳过行为。 + +请求中的第一个跳过原因会以 `warn` 级别记录，这样操作人员可以看到 +为何他们的主提供商被跳过；后续跳过则以 +`debug` 级别记录，以避免冗长的回退链产生过多噪音。如果所有候选项都被跳过， +聚合错误会包含每个候选项的跳过原因。 ## 操作 -- **generate** -- 根据给定提示和可选参考输入生成视频。 -- **status** -- 查询当前会话中正在进行的视频任务状态，而不启动新的生成。 +- **generate**（默认） -- 根据给定提示和可选参考输入创建视频。 +- **status** -- 检查当前会话中正在进行的视频任务状态，而不会启动新的生成。 - **list** -- 显示可用的提供商、模型及其能力。 ## 模型选择 @@ -184,11 +235,13 @@ openclaw tasks cancel 1. **`model` 工具参数** -- 如果智能体在调用中指定了它。 2. **`videoGenerationModel.primary`** -- 来自配置。 3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。 -4. **自动检测** -- 使用具有有效身份验证的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。 +4. **自动检测** -- 使用具有有效鉴权的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。 -如果某个提供商失败，系统会自动尝试下一个候选项。如果所有候选项都失败，错误信息会包含每次尝试的详细信息。 +如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。 -如果你希望视频生成只使用显式配置的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 +如果你希望 +视频生成仅使用显式的 `model`、`primary` 和 `fallbacks` +条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 ```json5 { @@ -203,54 +256,30 @@ openclaw tasks cancel } ``` -可以通过以下方式固定使用 fal 上的 HeyGen video-agent： - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", - }, - }, - }, -} -``` - -可以通过以下方式固定使用 fal 上的 Seedance 2.0： - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", - }, - }, - }, -} -``` - ## 提供商说明 | 提供商 | 说明 | -| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图片和视频必须是远程 `http(s)` URL。 | -| BytePlus（国际版） | 仅支持单张参考图片。 | -| ComfyUI | 由工作流驱动的本地或云端执行。通过已配置的图形支持文生视频和图生视频。 | -| fal | 对长时间运行的任务使用基于队列的流程。仅支持单张参考图片。包含 HeyGen video-agent 以及 Seedance 2.0 文生视频和图生视频模型引用。 | -| Google | 使用 Gemini/Veo。支持一张参考图片或一个参考视频。 | -| MiniMax | 仅支持单张参考图片。 | -| OpenAI | 只会转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并附带警告。 | -| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `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 | 支持文生视频、图生视频，以及基于远程视频的编辑/扩展流程。 | +| ------ | ---- | +| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | +| BytePlus（1.0） | 提供商 ID 为 `byteplus`。模型：`seedance-1-0-pro-250528`（默认）、`seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、`seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和通用 `*-pro-*` 模型支持单张参考图像（首帧）。你可以按位置传入图像，或设置 `role: "first_frame"`。当提供图像时，T2V 模型 ID 会自动切换为对应的 I2V 变体。支持的 `providerOptions` 键名：`seed`（number）、`draft`（boolean，会强制 480p）、`camera_fixed`（boolean）。 | +| BytePlus Seedance 1.5 | 需要安装 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@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 | 由 workflow 驱动的本地或云端执行。通过已配置的图表支持文生视频和图生视频。 | +| fal | 对长时间运行任务使用基于队列的流程。仅支持单张图像参考。 | +| Google | 使用 Gemini/Veo。支持一张图像或一个视频参考。 | +| MiniMax | 仅支持单张图像参考。 | +| OpenAI | 只会转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并发出警告。 | +| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `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 | 支持文生视频、图生视频，以及基于远程视频的编辑/扩展流程。 | ## 提供商能力模式 -共享视频生成契约现在允许提供商声明特定模式的能力，而不再仅仅使用扁平的聚合限制。新的提供商实现应优先使用显式模式块： +共享的视频生成契约现在允许提供商声明特定于模式的 +能力，而不再只使用扁平的聚合限制。新的提供商 +实现应优先使用显式模式块： ```typescript capabilities: { @@ -274,7 +303,11 @@ capabilities: { } ``` -像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以声明变换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、契约测试以及共享的 `video_generate` 工具才能以确定性的方式校验模式支持。 +像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段 +不足以声明转换模式支持。提供商应显式声明 +`generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、 +契约测试以及共享的 `video_generate` 工具能够以确定性的方式 +验证模式支持。 ## 实时测试 @@ -290,15 +323,18 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境变量 API 密钥，而不是已存储的身份验证配置文件，并运行它可以安全地通过本地媒体执行的声明模式： +该实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用 +实时/环境变量中的 API 密钥，而不是已存储的鉴权配置文件，并运行其能够安全使用本地媒体执行的 +已声明模式： -- 对扫描中的每个提供商运行 `generate` -- 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo` -- 当 `capabilities.videoToVideo.enabled` 且提供商/模型在共享扫描中接受基于缓冲区的本地视频输入时运行 `videoToVideo` +- 对扫描中的每个提供商执行 `generate` +- 当 `capabilities.imageToVideo.enabled` 为真时执行 `imageToVideo` +- 当 `capabilities.videoToVideo.enabled` 为真且提供商/模型 + 在共享扫描中接受基于缓冲区的本地视频输入时执行 `videoToVideo` -当前共享的 `videoToVideo` 实时通道覆盖： +目前共享的 `videoToVideo` 实时通道覆盖： -- 仅 `runway`，并且仅当你选择 `runway/gen4_aleph` 时 +- 仅 `runway`，并且前提是你选择了 `runway/gen4_aleph` ## 配置