openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-14 14:04:31 +00:00
parent 956d83632e
commit bf8a9a215d
2 changed files with 485 additions and 522 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

779
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff

228
docs/zh-CN/tools/video-generation.md
View File

@ -3,23 +3,23 @@ read_when:
- 通过智能体生成视频
- 配置视频生成提供商和模型
- 了解 `video_generate` 工具参数
summary: 使用 14 个提供商后端，从文本、图像或现有视频生成视频
summary: 使用 14 个提供商后端从文本、图像或现有视频生成视频
title: 视频生成
x-i18n:
generated_at: "2026-04-11T09:24:44Z"
generated_at: "2026-04-14T14:00:54Z"
model: gpt-5.4
provider: openai
source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263
source_hash: c182f24b25e44f157a820e82a1f7422247f26125956944b5eb98613774268cfe
source_path: tools/video-generation.md
workflow: 15
---
# 视频生成
OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。当前支持 14 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。
OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 14 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。
<Note>
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你在智能体工具中看不到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。
</Note>
OpenClaw 将视频生成视为三种运行时模式：
@ -28,18 +28,17 @@ OpenClaw 将视频生成视为三种运行时模式：
- `imageToVideo`：当请求包含一个或多个参考图像时使用
- `videoToVideo`：当请求包含一个或多个参考视频时使用
提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前
模式，并在 `action=list` 中报告支持的模式。
提供商可以支持这些模式中的任意子集。工具会在提交前校验当前激活的模式，并在 `action=list` 中报告支持的模式。
## 快速开始
1. 为任一受支持的提供商设置 API 密钥：
1. 为任意受支持的提供商设置 API 密钥：
```bash
export GEMINI_API_KEY="your-key"
```
2. 可选：固定一个默认模型：
2. 可选：固定默认模型：
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
@ -49,31 +48,31 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
> 生成一个 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。
智能体会自动调用 `video_generate`。不需要配置工具白名单。
智能体会自动调用 `video_generate`。不需要进行工具 allowlist 配置。
## 生成视频时会发生什么
## 当你生成视频时会发生什么
视频生成是异步的。当智能体在某个会话中调用 `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 <taskId>` 在 CLI 中检查进度。
当任务正在进行时，同一会话中的重复 `video_generate` 调用会返回当前任务状态，而不是再次启动生成。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可从 CLI 检查进度。
在不依赖会话的智能体运行场景之外（例如，直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。
在不依赖会话的智能体运行之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。
### 任务生命周期
每个 `video_generate` 请求都会经历四种状态：
每个 `video_generate` 请求会经历四个状态：
1. **queued** -- 任务已创建，正在等待提供商接受。
2. **running** -- 提供商正在处理（通常需要 30 秒到 5 分钟，取决于提供商和分辨率）。
3. **succeeded** -- 视频已准备就绪；智能体会被唤醒并将其发布到对话中。
4. **failed** -- 提供商错误或超时；智能体会携带错误详情被唤醒。
1. **queued** -- 任务已创建，等待提供商接受。
2. **running** -- 提供商正在处理（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。
3. **succeeded** -- 视频已准备好；智能体被唤醒并将其发送到对话中。
4. **failed** -- 提供商错误或超时；智能体被唤醒并附带错误详情。
可通过 CLI 检查状态：
通过 CLI 检查状态：
```bash
openclaw tasks list
@ -81,7 +80,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防止重复：如果当前会话中已经有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成。
重复防护：如果当前会话已经存在一个 `queued` 或 `running` 状态的视频任务，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成。
## 支持的提供商
@ -102,130 +101,103 @@ openclaw tasks cancel <taskId>
| 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 |
| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| BytePlus | 是 | 是 | 否 | `generate`、`imageToVideo` |
| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；特定于 workflow 的覆盖由 Comfy 测试承担 |
| ComfyUI | 是 | 是 | 否 | 不在共享扫测中；特定于 workflow 的覆盖由 Comfy 测试负责 |
| fal | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前基于缓冲区的 Gemini/Veo 扫测不接受该输入 |
| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前此组织/输入路径需要提供商侧的 inpaint/remix 访问能力 |
| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| 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 |
| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 已跳过，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL |
| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商当前需要远程 MP4 URL |
## 工具参数
### 必填
| 参数 | 类型 | 说明 |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `prompt` | string | 要生成的视频的文本描述（`action: "generate"` 时必填） |
### 内容输入
| 参数 | 类型 | 说明 |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `image` | string | 单个参考图像（路径或 URL） |
| `images` | string[] | 多个参考图像（最多 9 张） |
| `imageRoles` | string[] | 与合并后图像列表按位置对应的可选角色提示。规范值：`first_frame`、`last_frame`、`reference_image` |
| `imageRoles` | string[] | 与合并后图像列表按位置一一对应的可选角色提示。规范值：`first_frame`、`last_frame`、`reference_image` |
| `video` | string | 单个参考视频（路径或 URL） |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| `videoRoles` | string[] | 与合并后视频列表按位置对应的可选角色提示。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。例如，当提供商支持音频输入时，可用于背景音乐或语音参考 |
| `videoRoles` | string[] | 与合并后视频列表按位置一一对应的可选角色提示。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。例如在提供商支持音频输入时，用于背景音乐或声音参考 |
| `audioRefs` | string[] | 多个参考音频（最多 3 个） |
| `audioRoles` | string[] | 与合并后音频列表按位置对应的可选角色提示。规范值：`reference_audio` |
| `audioRoles` | string[] | 与合并后音频列表按位置一一对应的可选角色提示。规范值：`reference_audio` |
角色提示会按原样转发给提供商。规范值来自
`VideoGenerationAssetRole` 联合类型，但提供商也可能接受额外的
角色字符串。`*Roles` 数组的条目数不能多于对应的
参考列表；如果出现数量偏差，会返回清晰的错误。
使用空字符串可使某个位置保持未设置。
角色提示会按原样转发给提供商。规范值来自 `VideoGenerationAssetRole` 联合类型，但提供商也可能接受额外的角色字符串。`*Roles` 数组的条目数不得多于对应的参考列表；如果出现数量偏差，系统会返回清晰的错误。使用空字符串可让某个位置保持未设置。
### 风格控制
| 参数 | 类型 | 说明 |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `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 | 目标时长（秒）（会四舍五入到最接近的提供商支持值） |
| `durationSeconds` | number | 目标时长（秒），会四舍五入到最接近的提供商支持值 |
| `size` | string | 当提供商支持时使用的尺寸提示 |
| `audio` | boolean | 在支持时为输出启用生成音频。与 `audioRef*`（输入）不同 |
| `audio` | boolean | 在支持时为输出启用生成的音频。与 `audioRef*`（输入）不同 |
| `watermark` | boolean | 在支持时切换提供商水印 |
`adaptive` 是一个提供商特定的哨兵值：它会被原样转发给
在其能力声明中包含 `adaptive` 的提供商（例如 BytePlus
Seedance 会使用它根据输入图像
尺寸自动检测比例）。对于未声明该值的提供商，
该值会通过工具结果中的
`details.ignoredOverrides` 暴露出来，以便明确看到它被忽略。
`adaptive` 是一个提供商特定的哨兵值：对于在其能力声明中包含 `adaptive` 的提供商，该值会按原样转发（例如 BytePlus Seedance 会用它根据输入图像尺寸自动检测比例）。对于未声明该值的提供商，工具结果会通过 `details.ignoredOverrides` 暴露这个值，以便明确显示它已被忽略。
### 高级
### 高级参数
| 参数 | 类型 | 说明 |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `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` 可查看各提供商接受哪些选项 |
| `providerOptions` | object | 以 JSON 对象形式传递的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。声明了类型化 schema 的提供商会校验键名和类型；未知键名或类型不匹配会在回退时跳过该候选项。未声明 schema 的提供商会按原样接收这些选项。运行 `video_generate action=list` 可查看各提供商接受哪些选项 |
并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为最接近的提供商支持值，也会在回退提供商暴露不同控制面时，重新映射像 size 到 aspect-ratio 这样的几何提示。真正不受支持的覆盖项会尽力忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。
并非所有提供商都支持所有参数。OpenClaw 会将时长规范化为最接近的提供商支持值；当回退提供商暴露的是不同控制面时，它还会重新映射诸如尺寸到宽高比之类的几何提示。真正不受支持的覆盖项会尽力忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前直接报错。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值会反映实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值反映的是实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
参考输入也会决定运行时模式：
- 没有参考媒体：`generate`
- 存在任意图像参考：`imageToVideo`
- 存在任意视频参考：`videoToVideo`
- 参考音频输入不会改变已解析的模式；它们会叠加应用在图像/视频参考所选择的模式之上，并且仅适用于声明了 `maxInputAudios` 的提供商
- 无参考媒体：`generate`
- 任意图像参考：`imageToVideo`
- 任意视频参考：`videoToVideo`
- 参考音频输入不会改变最终解析的模式；它们会叠加到图像/视频参考所选择的模式之上，并且仅适用于声明了 `maxInputAudios` 的提供商
图像和视频参考混用并不是一个稳定的共享能力面。
建议每次请求只使用一种参考类型。
图像参考和视频参考混合使用并不是稳定的共享能力面。
建议每个请求只使用一种参考类型。
#### 回退与类型化选项
#### 回退和类型化选项
某些能力检查是在回退层而不是
工具边界层应用的，这样即使请求超出了主提供商的限制，
仍然可以在具备相应能力的回退提供商上运行：
某些能力检查是在回退层而不是工具边界上应用的，这样即使请求超出了主提供商的限制，仍然可以在支持该能力的回退提供商上运行：
- 如果当前候选项未声明 `maxInputAudios`（或将其声明为
`0`），并且请求包含音频参考，
则会跳过该候选项，并尝试下一个候选项。
- 如果当前候选项的 `maxDurationSeconds` 低于请求的
`durationSeconds`，且该候选项未声明
`supportedDurationSeconds` 列表，则会跳过该候选项。
- 如果请求包含 `providerOptions`，且当前候选项
明确声明了类型化的 `providerOptions` schema，
当提供的键名不在 schema 中或值类型
不匹配时，该候选项会被跳过。尚未声明 schema 的提供商会按原样接收
这些选项（向后兼容透传）。提供商可以
通过声明一个空 schema
（`capabilities.providerOptions: {}`）来显式禁用所有 provider options，
这会导致与类型不匹配相同的跳过行为。
- 如果当前候选项未声明 `maxInputAudios`（或将其声明为 `0`），则当请求包含音频参考时会跳过该候选项，并尝试下一个候选项。
- 如果当前候选项的 `maxDurationSeconds` 低于请求的 `durationSeconds`，且该候选项未声明 `supportedDurationSeconds` 列表，则会跳过该候选项。
- 如果请求包含 `providerOptions`，且当前候选项显式声明了类型化的 `providerOptions` schema，那么当提供的键名不在 schema 中或值类型不匹配时，会跳过该候选项。尚未声明 schema 的提供商会按原样接收这些选项（向后兼容的透传）。提供商可以通过声明空 schema（`capabilities.providerOptions: {}`）来显式拒绝所有提供商选项，这会导致与类型不匹配相同的跳过行为。
请求中的第一个跳过原因会以 `warn` 级别记录，这样操作人员可以看到
为何他们的主提供商被跳过；后续跳过则以
`debug` 级别记录，以避免冗长的回退链产生过多噪音。如果所有候选项都被跳过，
聚合错误会包含每个候选项的跳过原因。
请求中的第一个跳过原因会记录为 `warn`，以便运维人员看到他们的主提供商为何被跳过；后续跳过原因会记录为 `debug`，以避免冗长的回退链产生过多日志。如果所有候选项都被跳过，聚合错误中会包含每个候选项的跳过原因。
## 操作
- **generate**（默认） -- 根据给定提示和可选参考输入创建视频。
- **status** -- 检查当前会话中正在进行的视频任务状态，而不会启动新的生成。
- **generate**（默认）-- 根据给定的提示和可选参考输入生成视频。
- **status** -- 检查当前会话中正在进行的视频任务状态，而不启动新的生成。
- **list** -- 显示可用的提供商、模型及其能力。
## 模型选择
@ -235,13 +207,11 @@ Seedance 会使用它根据输入图像
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
{
@ -261,25 +231,23 @@ Seedance 会使用它根据输入图像
| 提供商 | 说明 |
| ------ | ---- |
| 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。 |
| 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: {
@ -303,38 +271,42 @@ capabilities: {
}
```
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段
不足以声明转换模式支持。提供商应显式声明
`generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、
契约测试以及共享的 `video_generate` 工具能够以确定性的方式
验证模式支持。
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以声明转换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、契约测试以及共享的 `video_generate` 工具才能以确定性的方式校验模式支持。
## 实时测试
为共享内置提供商启用可选的实时覆盖：
为共享内置提供商启用选择性实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
仓库封装命令：
仓库包装命令：
```bash
pnpm test:live:media video
```
该实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用
实时/环境变量中的 API 密钥，而不是已存储的鉴权配置文件，并运行其能够安全使用本地媒体执行的
已声明模式：
这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境变量 API 密钥而不是已存储的凭证配置，并且默认运行一个适合发布流程的冒烟测试：
- 对扫描中的每个提供商执行 `generate`
- 当 `capabilities.imageToVideo.enabled` 为真时执行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 为真且提供商/模型
在共享扫描中接受基于缓冲区的本地视频输入时执行 `videoToVideo`
- 对扫测中的每个非 FAL 提供商运行 `generate`
- 使用 1 秒钟的龙虾提示词
- 每个提供商的操作上限由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 控制（默认值为 `180000`）
目前共享的 `videoToVideo` 实时通道覆盖：
FAL 需要显式选择启用，因为提供商侧的队列延迟可能会显著拉长发布时间：
- 仅 `runway`，并且前提是你选择了 `runway/gen4_aleph`
```bash
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` 时才会运行
## 配置
@ -362,9 +334,9 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## 相关内容
- [工具概览](/zh-CN/tools)
- [后台任务](/zh-CN/automation/tasks) -- 异步视频生成的任务跟踪
- [后台任务](/zh-CN/automation/tasks) -- 用于异步视频生成的任务跟踪
- [Alibaba Model Studio](/zh-CN/providers/alibaba)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [BytePlus](/zh-CN/concepts/model-providers#byteplus-international)
- [ComfyUI](/zh-CN/providers/comfy)
- [fal](/zh-CN/providers/fal)
- [Google（Gemini）](/zh-CN/providers/google)