diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 2ee8403c4..8612723c0 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -6,26 +6,26 @@ read_when: summary: 使用已配置的提供商（OpenAI、Google Gemini、fal、MiniMax、ComfyUI、Vydra）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-06T03:19:55Z" + generated_at: "2026-04-06T22:24:48Z" model: gpt-5.4 provider: openai - source_hash: 903cc522c283a8da2cbd449ae3e25f349a74d00ecfdaf0f323fd8aa3f2107aea + source_hash: 359ee3d697658cf783891c615e2901b6edaf160aa17dc8e6ffac326ccab76060 source_path: tools/image-generation.md workflow: 15 --- # 图像生成 -`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件包含在智能体的回复中。 +`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件附加在智能体的回复中。 -只有在至少有一个图像生成提供商可用时，该工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`）。 -2. 可选：设置你的首选模型： +2. 可选：设置你偏好的模型： ```json5 { @@ -39,20 +39,20 @@ x-i18n: } ``` -3. 向智能体提问：_“生成一张友好的龙虾吉祥物图像。”_ +3. 向智能体提出请求：_“生成一张友好的龙虾吉祥物图像。”_ -智能体会自动调用 `image_generate`。不需要工具允许列表——当有提供商可用时，它默认启用。 +智能体会自动调用 `image_generate`。无需将其加入工具允许列表 —— 只要提供商可用，它默认启用。 ## 支持的提供商 -| 提供商 | 默认模型 | 编辑支持 | API 密钥 | -| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------ | -| OpenAI | `gpt-image-1` | 是（最多 5 张图像） | `OPENAI_API_KEY` | -| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | -| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | -| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | `COMFY_API_KEY` 或用于云端的 `COMFY_CLOUD_API_KEY` | -| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | +| 提供商 | 默认模型 | 编辑支持 | API 密钥 | +| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------- | +| OpenAI | `gpt-image-1` | 是（最多 5 张图像） | `OPENAI_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | +| MiniMax| `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | +| ComfyUI| `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | +| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | 使用 `action: "list"` 可在运行时查看可用的提供商和模型： @@ -67,15 +67,15 @@ x-i18n: | `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） | | `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | | `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-1` | -| `image` | string | 编辑模式下的单张参考图像路径或 URL | -| `images` | string[] | 编辑模式下的多张参考图像（最多 5 张） | +| `image` | string | 编辑模式下的单个参考图像路径或 URL | +| `images` | string[] | 编辑模式下的多个参考图像（最多 5 张） | | `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`1024x1792`、`1792x1024` | | `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | | `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` | | `count` | number | 要生成的图像数量（1–4） | | `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。工具会传递各提供商支持的参数，忽略其余参数，并在工具结果中报告被丢弃的覆盖项。 +并非所有提供商都支持全部参数。当回退提供商支持的是接近的几何选项而不是你精确请求的选项时，OpenClaw 会在提交前重映射到最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。 ## 配置 @@ -101,16 +101,17 @@ x-i18n: 1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** 3. 按顺序使用 **`imageGenerationModel.fallbacks`** -4. **自动检测**——仅使用有认证支持的提供商默认值： - - 先使用当前默认提供商 - - 再按提供商 ID 顺序使用其余已注册的图像生成提供商 +4. **自动检测** —— 仅使用有凭证支持的提供商默认值： + - 当前默认提供商优先 + - 其余已注册的图像生成提供商，按 provider-id 顺序 -如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 +如果某个提供商失败（凭证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 说明： -- 自动检测会感知认证状态。只有当 OpenClaw 实际能够验证该提供商时，提供商默认值才会进入候选列表。 -- 使用 `action: "list"` 可查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。 +- 自动检测会感知凭证状态。只有当 OpenClaw 实际能够验证该提供商时，该提供商默认值才会进入候选列表。 +- 自动检测默认启用。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 +- 使用 `action: "list"` 查看当前已注册的提供商、它们的默认模型以及凭证环境变量提示。 ### 图像编辑 @@ -122,7 +123,7 @@ OpenAI、Google、fal、MiniMax 和 ComfyUI 支持编辑参考图像。传入参 OpenAI 和 Google 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 -MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： +MiniMax 图像生成可通过两种内置的 MiniMax 凭证路径使用： - `minimax/image-01`，用于 API 密钥配置 - `minimax-portal/image-01`，用于 OAuth 配置 @@ -131,7 +132,7 @@ MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） | | 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | | 尺寸控制 | 是 | 是 | 是 | 否 | 否 | 否 | | 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | @@ -139,12 +140,12 @@ MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： ## 相关内容 -- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 -- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 -- [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 -- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 -- [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置 -- [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置 -- [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置 -- [模型](/zh-CN/concepts/models) — 模型配置和故障切换 +- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具 +- [fal](/zh-CN/providers/fal) —— fal 图像和视频提供商设置 +- [ComfyUI](/zh-CN/providers/comfy) —— 本地 ComfyUI 和 Comfy Cloud 工作流设置 +- [Google (Gemini)](/zh-CN/providers/google) —— Gemini 图像提供商设置 +- [MiniMax](/zh-CN/providers/minimax) —— MiniMax 图像提供商设置 +- [OpenAI](/zh-CN/providers/openai) —— OpenAI Images 提供商设置 +- [Vydra](/zh-CN/providers/vydra) —— Vydra 图像、视频和语音设置 +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— `imageGenerationModel` 配置 +- [模型](/zh-CN/concepts/models) —— 模型配置和故障切换 diff --git a/docs/zh-CN/tools/music-generation.md b/docs/zh-CN/tools/music-generation.md index c59d4476d..ee7047630 100644 --- a/docs/zh-CN/tools/music-generation.md +++ b/docs/zh-CN/tools/music-generation.md @@ -3,25 +3,25 @@ read_when: - 通过智能体生成音乐或音频 - 配置音乐生成提供商和模型 - 了解 `music_generate` 工具参数 -summary: 使用共享提供商生成音乐，包括基于工作流的插件 +summary: 通过共享提供商生成音乐，包括基于工作流的插件 title: 音乐生成 x-i18n: - generated_at: "2026-04-06T18:17:26Z" + generated_at: "2026-04-06T22:24:58Z" model: gpt-5.4 provider: openai - source_hash: a7af06f64efde518934e1408837a9c4bfc52710a6b5d39225eee9889d7b86030 + source_hash: 3b45ce03388e26e2e332851d2460bdf88661bf584d156f5f0b25aac4cde4d059 source_path: tools/music-generation.md workflow: 15 --- # 音乐生成 -`music_generate` 工具让智能体能够通过共享音乐生成能力，结合已配置的提供商（如 Google、MiniMax 以及通过工作流配置的 ComfyUI）来创建音乐或音频。 +`music_generate` 工具让智能体能够通过共享音乐生成能力，借助已配置的提供商（例如 Google、MiniMax 和通过工作流配置的 ComfyUI）创建音乐或音频。 -对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务台账中跟踪它，然后在音轨准备就绪时再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。 +对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务台账中跟踪它，然后在音轨准备就绪后再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。 -仅当至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 @@ -43,13 +43,13 @@ x-i18n: } ``` -3. 向智能体提问：_“生成一段关于夜间驾驶穿越霓虹城市的欢快 synthpop 音轨。”_ +3. 向智能体提问：_“生成一段关于夜晚驾驶穿过霓虹都市的欢快 synthpop 音轨。”_ -智能体会自动调用 `music_generate`。无需为工具配置允许列表。 +智能体会自动调用 `music_generate`。不需要工具允许列表。 对于没有会话支持的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。 -示例提示词： +提示词示例： ```text Generate a cinematic piano track with soft strings and no vocals. @@ -59,13 +59,13 @@ Generate a cinematic piano track with soft strings and no vocals. Generate an energetic chiptune loop about launching a rocket at sunrise. ``` -### 工作流驱动的 Comfy 生成 +### 由工作流驱动的 Comfy 生成 -内置的 `comfy` 插件通过音乐生成提供商注册表接入共享的 `music_generate` 工具。 +内置的 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。 -1. 为 `models.providers.comfy.music` 配置工作流 JSON 以及提示词/输出节点。 +1. 使用工作流 JSON 以及提示词/输出节点配置 `models.providers.comfy.music`。 2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。 -3. 向智能体请求音乐，或直接调用该工具。 +3. 向智能体请求生成音乐，或直接调用该工具。 示例： @@ -75,29 +75,29 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 共享内置提供商支持 -| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 | -| ------ | ---------------------- | -------------- | --------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | 最多 1 张图片 | 工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 | +| ------ | ---------------------- | ------------- | --------------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | 最多 1 张图片 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | | Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` | +| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` | -### 声明式能力矩阵 +### 已声明的能力矩阵 -这是 `music_generate`、契约测试以及共享实时扫描所使用的显式模式契约。 +这是 `music_generate`、契约测试和共享实时扫描所使用的显式模式契约。 -| 提供商 | `generate` | `edit` | 编辑上限 | 共享实时测试通道 | -| ------ | ---------- | ------ | ---------- | ------------------------------------------------------------------------ | -| ComfyUI | 是 | 是 | 1 张图片 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 | -| Google | 是 | 是 | 10 张图片 | `generate`、`edit` | -| MiniMax | 是 | 否 | 无 | `generate` | +| 提供商 | `generate` | `edit` | 编辑上限 | 共享实时测试通道 | +| ------ | ---------- | ------ | ---------- | ---------------------------------------------------------------------- | +| ComfyUI | 是 | 是 | 1 张图片 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 | +| Google | 是 | 是 | 10 张图片 | `generate`、`edit` | +| MiniMax | 是 | 否 | 无 | `generate` | -使用 `action: "list"` 可在运行时查看可用的共享提供商和模型： +使用 `action: "list"` 可在运行时检查可用的共享提供商和模型： ```text /tool music_generate action=list ``` -使用 `action: "status"` 可查看当前由会话支持的音乐任务状态： +使用 `action: "status"` 可检查当前由会话支持的活动音乐任务： ```text /tool music_generate action=status @@ -111,41 +111,41 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 内置工具参数 -| 参数 | 类型 | 说明 | -| ----------------- | -------- | -------------------------------------------------------------------- | -| `prompt` | string | 音乐生成提示词（`action: "generate"` 时为必填） | -| `action` | string | `"generate"`（默认）、当前会话任务的 `"status"`，或用于查看提供商的 `"list"` | -| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` | -| `lyrics` | string | 当提供商支持显式歌词输入时的可选歌词 | -| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 | -| `image` | string | 单个参考图片路径或 URL | -| `images` | string[] | 多个参考图片（最多 10 张） | -| `durationSeconds` | number | 当提供商支持时长提示时，以秒为单位的目标时长 | -| `format` | string | 当提供商支持时的输出格式提示（`mp3` 或 `wav`） | -| `filename` | string | 输出文件名提示 | +| 参数 | 类型 | 描述 | +| ----------------- | -------- | ------------------------------------------------------------------------------------------------ | +| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）、当前会话任务的 `"status"`，或用于检查提供商的 `"list"` | +| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` | +| `lyrics` | string | 当提供商支持显式歌词输入时，可选的歌词 | +| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 | +| `image` | string | 单个参考图片路径或 URL | +| `images` | string[] | 多个参考图片（最多 10 张） | +| `durationSeconds` | number | 当提供商支持时长提示时，以秒为单位的目标时长 | +| `format` | string | 当提供商支持时，输出格式提示（`mp3` 或 `wav`） | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。OpenClaw 在提交前仍会验证输入数量等硬性限制，但当所选提供商或模型无法满足时，不支持的可选提示会被忽略，并附带警告。 +并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长但其最大值短于请求值时，OpenClaw 会自动限制到最接近的受支持时长。对于真正不支持的可选提示，如果所选提供商或模型无法满足，会在给出警告后忽略。 ## 共享提供商支持路径的异步行为 -- 由会话支持的智能体运行：`music_generate` 会创建一个后台任务，立即返回 started/task 响应，并在稍后的智能体后续消息中发布完成的音轨。 -- 防重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是再次启动新的生成。 -- 状态查询：使用 `action: "status"` 可在不启动新任务的情况下查看当前由会话支持的音乐任务。 -- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show ` 查看该生成任务的排队、运行和终态状态。 -- 完成唤醒：OpenClaw 会将内部完成事件重新注入到同一会话中，以便模型自行编写面向用户的后续回复。 -- 提示词提示：当同一会话中已有音乐任务在进行时，后续用户/手动轮次会获得一个小型运行时提示，避免模型盲目再次调用 `music_generate`。 -- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮中返回最终音频结果。 +- 由会话支持的智能体运行：`music_generate` 会创建一个后台任务，立即返回 started/task 响应，并稍后在后续智能体消息中发布完成的音轨。 +- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动另一次生成。 +- 状态查询：使用 `action: "status"` 可检查当前由会话支持的活动音乐任务，而不会启动新任务。 +- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show ` 检查生成任务的排队、运行中和终态状态。 +- 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，让模型自行写出面向用户的后续回复。 +- 提示词提醒：当某个音乐任务已经在处理中时，同一会话中的后续用户/手动轮次会收到一个小型运行时提示，这样模型就不会盲目再次调用 `music_generate`。 +- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一轮中返回最终音频结果。 ### 任务生命周期 -每个 `music_generate` 请求会经历四种状态： +每个 `music_generate` 请求都会经历四个状态： 1. **queued** -- 任务已创建，等待提供商接受。 2. **running** -- 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。 -3. **succeeded** -- 音轨已准备好；智能体被唤醒并将其发布到对话中。 -4. **failed** -- 提供商错误或超时；智能体被唤醒并附带错误详情。 +3. **succeeded** -- 音轨已就绪；智能体被唤醒并将其发布到对话中。 +4. **failed** -- 提供商错误或超时；智能体会带着错误详情被唤醒。 -通过 CLI 查看状态： +从 CLI 检查状态： ```bash openclaw tasks list @@ -153,7 +153,7 @@ openclaw tasks show openclaw tasks cancel ``` -防重复：如果当前会话的音乐任务已处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新的任务。使用 `action: "status"` 可在不触发新生成的情况下显式查看状态。 +防止重复：如果当前会话的音乐任务已处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查，而不触发新的生成。 ## 配置 @@ -176,27 +176,29 @@ openclaw tasks cancel 生成音乐时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 `model` 参数（如果智能体指定了它） +1. 工具调用中的 `model` 参数（如果智能体指定了该参数） 2. 配置中的 `musicGenerationModel.primary` 3. 按顺序使用 `musicGenerationModel.fallbacks` -4. 仅使用基于凭证支持的提供商默认值进行自动检测： +4. 仅使用基于凭证的提供商默认值进行自动检测： - 当前默认提供商优先 - - 其余已注册的音乐生成提供商，按 provider id 顺序 + - 剩余已注册的音乐生成提供商，按 provider-id 顺序 -如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 +如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详情。 + +如果你希望音乐生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 ## 提供商说明 - Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图片。 - MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制和 mp3 输出。 -- ComfyUI 支持由工作流驱动，取决于已配置的图以及提示词/输出字段的节点映射。 +- ComfyUI 支持由工作流驱动，并取决于已配置的图以及提示词/输出字段的节点映射。 ## 提供商能力模式 共享音乐生成契约现在支持显式模式声明： - `generate` 用于仅基于提示词的生成 -- 当请求包含一张或多张参考图片时使用 `edit` +- 当请求包含一个或多个参考图片时，使用 `edit` 新的提供商实现应优先使用显式模式块： @@ -216,17 +218,17 @@ capabilities: { } ``` -旧版扁平字段（如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat`）不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够确定性地验证模式支持。 +像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的旧版平面字段，不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够以确定性的方式验证模式支持。 -## 选择正确的路径 +## 选择合适的路径 -- 当你希望获得模型选择、提供商故障转移以及内置异步任务/状态流程时，请使用共享提供商支持的路径。 +- 当你需要模型选择、提供商故障切换以及内置异步任务/状态流时，请使用共享提供商支持路径。 - 当你需要自定义工作流图，或需要使用不属于共享内置音乐能力的提供商时，请使用插件路径，例如 ComfyUI。 -- 如果你正在调试 ComfyUI 特有行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。 +- 如果你在调试 ComfyUI 特定行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你在调试共享提供商行为，请从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。 ## 实时测试 -共享内置提供商的选择加入式实时覆盖： +共享内置提供商的可选实时覆盖： ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts @@ -238,21 +240,21 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv pnpm test:live:media music ``` -此实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥而不是已存储的凭证配置，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。 +该实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥而不是已存储的认证配置文件，并在提供商启用编辑模式时运行 `generate` 和已声明的 `edit` 覆盖。 当前这意味着： -- `google`: `generate` 加 `edit` -- `minimax`: 仅 `generate` -- `comfy`: 单独的 Comfy 实时覆盖，不属于共享提供商扫描 +- `google`：`generate` 加 `edit` +- `minimax`：仅 `generate` +- `comfy`：单独的 Comfy 实时覆盖，不属于共享提供商扫描 -内置 ComfyUI 音乐路径的选择加入式实时覆盖： +内置 ComfyUI 音乐路径的可选实时覆盖： ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Comfy 实时测试文件在相关部分已配置时，也会覆盖 comfy 图像和视频工作流。 +如果相关部分已配置，Comfy 实时测试文件还会覆盖 comfy 图片和视频工作流。 ## 相关内容 @@ -261,5 +263,5 @@ Comfy 实时测试文件在相关部分已配置时，也会覆盖 comfy 图像 - [ComfyUI](/zh-CN/providers/comfy) - [Google (Gemini)](/zh-CN/providers/google) - [MiniMax](/zh-CN/providers/minimax) -- [Models](/zh-CN/concepts/models) - 模型配置和故障转移 +- [模型](/zh-CN/concepts/models) - 模型配置和故障切换 - [工具概览](/zh-CN/tools) diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index be363e2f5..dd11c3a3e 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -3,32 +3,33 @@ read_when: - 通过智能体生成视频 - 配置视频生成提供商和模型 - 了解 `video_generate` 工具参数 -summary: 使用 12 个提供商后端，通过文本、图像或现有视频生成视频 +summary: 使用 12 个提供商后端，从文本、图片或现有视频生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-06T18:17:37Z" + generated_at: "2026-04-06T22:25:20Z" model: gpt-5.4 provider: openai - source_hash: fc8984dfc718a3558b66089b37aea718f3da1ec8cf4f846a017201413c9be6a2 + source_hash: 59f65bf406cbf2b858523f94461251ee93c1f270cdd63dbe796e55f620574951 source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 12 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 +OpenClaw 智能体可以根据文本提示、参考图片或现有视频生成视频。支持 12 个提供商后端，每个后端具有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 -仅当至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。 +仅当至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你在智能体工具中看不到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。 OpenClaw 将视频生成视为三种运行时模式： -- `generate` 用于不包含参考媒体的文生视频请求 -- 当请求包含一个或多个参考图像时使用 `imageToVideo` -- 当请求包含一个或多个参考视频时使用 `videoToVideo` +- `generate` 用于没有参考媒体的文生视频请求 +- `imageToVideo` 用于请求包含一个或多个参考图片时 +- `videoToVideo` 用于请求包含一个或多个参考视频时 -提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。 +提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前 +模式，并在 `action=list` 中报告支持的模式。 ## 快速开始 @@ -38,7 +39,7 @@ OpenClaw 将视频生成视为三种运行时模式： export GEMINI_API_KEY="your-key" ``` -2. 可选：固定一个默认模型： +2. 可选：固定默认模型： ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" @@ -46,29 +47,29 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. 向智能体发出请求： -> 生成一段 5 秒钟、富有电影感的友善龙虾在日落时分冲浪的视频。 +> 生成一个 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。 -智能体会自动调用 `video_generate`。不需要将工具加入允许列表。 +智能体会自动调用 `video_generate`。无需配置工具 allowlist。 ## 生成视频时会发生什么 -视频生成是异步的。当智能体在会话中调用 `video_generate` 时： +视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时： -1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。 -2. 提供商在后台处理该任务（通常为 30 秒到 5 分钟，取决于提供商和分辨率）。 -3. 当视频准备就绪后，OpenClaw 会通过内部完成事件唤醒同一个会话。 -4. 智能体会将最终生成的视频发布回原始对话中。 +1. OpenClaw 会将请求提交给提供商，并立即返回一个任务 ID。 +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** -- 提供商错误或超时；智能体会被唤醒并附带错误详情。 @@ -80,98 +81,100 @@ 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（国际版） | `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 密钥环境变量。详见各个[提供商页面](#related)。 +某些提供商接受额外或替代的 API 密钥环境变量。详情请参阅各个[提供商页面](#related)。 -运行 `video_generate action=list` 可在运行时查看可用的提供商、模型和运行时模式。 +运行 `video_generate action=list` 可在运行时检查可用的提供商、模型和 +运行时模式。 ### 声明的能力矩阵 -这是 `video_generate`、契约测试以及共享实时扫描使用的显式模式契约。 +这是 `video_generate`、契约测试 +以及共享 live sweep 使用的显式模式契约。 -| 提供商 | `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` 已跳过，因为当前组织/输入路径需要提供商侧的修补/混剪访问 | -| 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 | +| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享 live 通道 | +| ------ | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 被跳过，因为该提供商需要远程 `http(s)` 视频 URL | +| BytePlus（国际版） | 是 | 是 | 否 | `generate`、`imageToVideo` | +| ComfyUI | 是 | 是 | 否 | 不在共享 sweep 中；特定于 workflow 的覆盖位于 Comfy 测试中 | +| fal | 是 | 是 | 否 | `generate`、`imageToVideo` | +| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 被跳过，因为当前基于 buffer 的 Gemini/Veo sweep 不接受该输入 | +| 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[] | 多个参考图片（最多 5 张） | +| `video` | string | 单个参考视频（路径或 URL） | +| `videos` | string[] | 多个参考视频（最多 4 个） | -### 风格控制 +### 样式控制 -| 参数 | 类型 | 说明 | -| ----------------- | ------- | ------------------------------------------------------------------------ | +| 参数 | 类型 | 说明 | +| ---- | ------- | ------------------------------------------------------------------------ | | `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 | 目标时长（单位：秒，会四舍五入到提供商支持的最近值） | +| `durationSeconds` | number | 目标时长（秒）（会四舍五入到最接近的提供商支持值） | | `size` | string | 当提供商支持时使用的尺寸提示 | | `audio` | boolean | 在支持时启用生成音频 | | `watermark` | boolean | 在支持时切换提供商水印 | ### 高级 -| 参数 | 类型 | 说明 | -| ---------- | ------ | ---------------------------------------------- | -| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | +| 参数 | 类型 | 说明 | +| ---- | ------ | ----------------------------------------------- | +| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | | `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） | | `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。不支持的覆盖项会尽力忽略，并在工具结果中以警告形式报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 +并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化到最接近的提供商支持值，并且当回退提供商暴露出不同的控制面时，它也会重新映射已转换的几何提示，例如从 size 到 aspect-ratio。真正不受支持的覆盖项会尽力忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前失败。 -参考输入还会决定运行时模式： +参考输入还会选择运行时模式： - 无参考媒体：`generate` -- 任意图像参考：`imageToVideo` +- 任意图片参考：`imageToVideo` - 任意视频参考：`videoToVideo` -混合使用图像和视频参考并不是稳定的共享能力表面。 -建议每个请求只使用一种参考类型。 +混合图片和视频参考并不是稳定的共享能力表面。 +每次请求最好仅使用一种参考类型。 ## 操作 -- **generate**（默认）-- 根据给定提示和可选参考输入创建视频。 +- **generate**（默认）-- 根据给定提示和可选参考输入生成视频。 - **status** -- 检查当前会话中正在进行的视频任务状态，而不启动新的生成。 - **list** -- 显示可用的提供商、模型及其能力。 @@ -179,13 +182,16 @@ openclaw tasks cancel 生成视频时，OpenClaw 会按以下顺序解析模型： -1. **`model` 工具参数** -- 如果智能体在调用中指定了它。 +1. **`model` 工具参数** -- 如果智能体在调用中指定了该参数。 2. **`videoGenerationModel.primary`** -- 来自配置。 3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。 4. **自动检测** -- 使用具有有效身份验证的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。 如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。 +如果你希望视频生成仅使用显式的 `model`、`primary` 和 `fallbacks` +条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 + ```json5 { agents: { @@ -201,24 +207,26 @@ openclaw tasks cancel ## 提供商说明 -| 提供商 | 说明 | -| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | -| BytePlus | 仅支持单个图像参考。 | -| ComfyUI | 由工作流驱动的本地或云端执行。通过已配置的图支持文生视频和图生视频。 | -| 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 | 支持文生视频、图生视频以及远程视频编辑/扩展流程。 | +| 提供商 | 说明 | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图片和视频必须是远程 `http(s)` URL。 | +| BytePlus（国际版） | 仅支持单张参考图片。 | +| 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: { @@ -242,11 +250,15 @@ capabilities: { } ``` -像 `maxInputImages` 和 `maxInputVideos` 这样的平铺聚合字段，不足以声明转换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、契约测试和共享 `video_generate` 工具能够以确定方式验证模式支持。 +像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段 +不足以声明变换模式支持。提供商应显式声明 +`generate`、`imageToVideo` 和 `videoToVideo`，以便 live 测试、 +契约测试以及共享 `video_generate` 工具能够以确定性的方式 +验证模式支持。 -## 实时测试 +## Live 测试 -共享内置提供商的可选加入实时覆盖： +为共享内置提供商启用可选的 live 覆盖： ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -258,13 +270,16 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥，而不是已存储的认证配置文件，并运行它能够安全地通过本地媒体执行的声明模式： +这个 live 文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用 +live/env API 密钥，而不是已存储的身份验证配置文件，并运行它能够使用本地媒体安全执行的 +声明模式： -- 对扫描中的每个提供商运行 `generate` +- 为 sweep 中的每个提供商运行 `generate` - 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo` -- 当 `capabilities.videoToVideo.enabled` 且提供商/模型在共享扫描中接受基于缓冲区的本地视频输入时运行 `videoToVideo` +- 当 `capabilities.videoToVideo.enabled` 且提供商/模型 + 在共享 sweep 中接受基于 buffer 的本地视频输入时运行 `videoToVideo` -当前共享 `videoToVideo` 实时通道涵盖： +目前共享 `videoToVideo` live 通道涵盖： - `runway`，且仅当你选择 `runway/gen4_aleph` 时 @@ -296,10 +311,10 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 - [工具概览](/zh-CN/tools) - [后台任务](/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) +- [Google（Gemini）](/zh-CN/providers/google) - [MiniMax](/zh-CN/providers/minimax) - [OpenAI](/zh-CN/providers/openai) - [Qwen](/zh-CN/providers/qwen)