影片生成 - OpenClaw

OpenClaw 代理可以從文字提示、參照圖片或既有影片產生影片。支援十六個供應商後端，每個後端都有不同的模型選項、輸入模式與功能集。代理會根據你的設定與可用的 API 金鑰，自動選擇合適的供應商。

video_generate 工具只會在至少有一個影片生成供應商可用時出現。如果你在代理工具中看不到它，請設定供應商 API 金鑰，或設定 agents.defaults.videoGenerationModel。

OpenClaw 將影片生成視為三種執行階段模式：

generate - 沒有參照媒體的文字轉影片請求。
imageToVideo - 請求包含一張或多張參照圖片。
videoToVideo - 請求包含一個或多個參照影片。

供應商可以支援這些模式的任意子集。工具會在提交前驗證作用中的模式，並在 action=list 中回報支援的模式。

快速開始

設定驗證

為任何支援的供應商設定 API 金鑰：

export GEMINI_API_KEY="your-key"

選擇預設模型（選用）

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

詢問代理

產生一段 5 秒的電影感影片，內容是一隻友善的龍蝦在夕陽下衝浪。

代理會自動呼叫 video_generate。不需要工具允許清單。

非同步生成如何運作

影片生成是非同步的。當代理在工作階段中呼叫 video_generate 時：

OpenClaw 會將請求提交給供應商，並立即傳回任務 ID。
供應商會在背景處理工作（通常需要 30 秒到數分鐘，取決於供應商與解析度；較慢的佇列式供應商可能會執行到設定的逾時時間）。
影片準備好後，OpenClaw 會以內部完成事件喚醒同一個工作階段。
代理會告知使用者並附上完成的影片。在使用僅訊息工具可見傳遞的群組/頻道聊天中，代理會透過訊息工具轉送結果，而不是由 OpenClaw 直接張貼。

當工作正在執行時，同一個工作階段中的重複 video_generate 呼叫會傳回目前任務狀態，而不是啟動另一個生成。使用 openclaw tasks list 或 openclaw tasks show <taskId> 從 CLI 檢查進度。在沒有工作階段支援的代理執行之外（例如直接工具叫用），工具會退回到內嵌生成，並在同一輪中傳回最終媒體路徑。當供應商傳回位元組時，產生的影片檔案會儲存在 OpenClaw 管理的媒體儲存空間下。預設的產生影片儲存上限會遵循影片媒體限制，而 agents.defaults.mediaMaxMb 會提高此上限以支援較大的渲染。當供應商也傳回託管輸出 URL 時，如果本機持久化因檔案過大而拒絕，OpenClaw 可以傳遞該 URL，而不是讓任務失敗。

任務生命週期

狀態	意義
`queued`	任務已建立，正在等待供應商接受。
`running`	供應商正在處理（通常需要 30 秒到數分鐘，取決於供應商與解析度）。
`succeeded`	影片已準備好；代理會被喚醒並將其張貼到對話中。
`failed`	供應商錯誤或逾時；代理會被喚醒並收到錯誤詳細資料。

從 CLI 檢查狀態：

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

如果目前工作階段已有影片任務處於 queued 或 running， video_generate 會傳回既有任務狀態，而不是啟動新的任務。使用 action: "status" 可明確檢查，而不觸發新的生成。

支援的供應商

供應商	預設模型	文字	圖片參照	影片參照	驗證
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 張圖片（透過角色提供首幀 + 末幀）	-	`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`
MiniMax	`MiniMax-Hailuo-2.3`	✓	1 張圖片	-	`MINIMAX_API_KEY` 或 MiniMax OAuth
OpenAI	`sora-2`	✓	1 張圖片	1 個影片	`OPENAI_API_KEY`
OpenRouter	`google/veo-3.1-fast`	✓	最多 4 張圖片（首幀/末幀或參照）	-	`OPENROUTER_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 張首幀圖片或最多 7 個 `reference_image`	1 個影片	`XAI_API_KEY`

有些供應商接受額外或替代的 API 金鑰環境變數。詳情請參閱個別供應商頁面。執行 video_generate action=list 以在執行階段檢查可用的供應商、模型和執行階段模式。

功能矩陣

video_generate、合約測試與共用即時掃描使用的明確模式合約：

供應商	`generate`	`imageToVideo`	`videoToVideo`	目前的共用即時通道
Alibaba	✓	✓	✓	`generate`、`imageToVideo`；已略過 `videoToVideo`，因為此供應商需要遠端 `http(s)` 影片 URL
BytePlus	✓	✓	-	`generate`、`imageToVideo`
ComfyUI	✓	✓	-	不在共用掃描中；工作流程特定涵蓋範圍由 Comfy 測試負責
DeepInfra	✓	-	-	`generate`；原生 DeepInfra 影片架構在隨附合約中是文字轉影片
fal	✓	✓	✓	`generate`、`imageToVideo`；只有使用 Seedance 參照轉影片時才支援 `videoToVideo`
Google	✓	✓	✓	`generate`、`imageToVideo`；已略過共用 `videoToVideo`，因為目前以緩衝區為基礎的 Gemini/Veo 掃描不接受該輸入
MiniMax	✓	✓	-	`generate`、`imageToVideo`
OpenAI	✓	✓	✓	`generate`、`imageToVideo`；已略過共用 `videoToVideo`，因為此組織/輸入路徑目前需要供應商端的 inpaint/remix 存取權限
OpenRouter	✓	✓	-	`generate`、`imageToVideo`
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" 必填。

內容輸入

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 陣列的項目數不得多於對應的參考清單；差一錯誤會以清楚錯誤失敗。使用空字串可讓某個位置保持未設定。對於 xAI，請將每個圖片角色設為 reference_image，以使用其 reference_images 生成模式；若要使用單張圖片的圖像轉影片，請省略角色或使用 first_frame。

樣式控制

aspectRatio

string

外觀比例提示，例如 1:1、16:9、9:16、adaptive，或提供者專屬值。OpenClaw 會依提供者正規化或忽略不支援的值。

resolution

string

解析度提示，例如 480P、720P、768P、1080P、4K，或提供者專屬值。OpenClaw 會依提供者正規化或忽略不支援的值。

durationSeconds

number

目標時長，以秒為單位（四捨五入至最接近的提供者支援值）。

size

string

提供者支援時使用的尺寸提示。

audio

boolean

支援時，在輸出中啟用生成音訊。這與 audioRef*（輸入）不同。

watermark

boolean

支援時切換提供者浮水印。

adaptive 是提供者專屬哨兵值：它會原樣轉送給在能力中宣告 adaptive 的提供者（例如 BytePlus Seedance 會用它從輸入圖片尺寸自動偵測比例）。未宣告它的提供者會透過工具結果中的 details.ignoredOverrides 顯示該值，讓捨棄行為可見。

進階

action

"generate" | "status" | "list"

預設值:"generate"

"status" 回傳目前工作階段任務；"list" 檢查提供者。

model

string

提供者/模型覆寫（例如 runway/gen4.5）。

filename

string

輸出檔名提示。

timeoutMs

number

選用的提供者操作逾時，以毫秒為單位。省略時，若已設定，OpenClaw 會使用 agents.defaults.videoGenerationModel.timeoutMs。

providerOptions

object

以 JSON 物件表示的提供者專屬選項（例如 {"seed": 42, "draft": true}）。宣告型別化結構描述的提供者會驗證鍵與型別；未知鍵或不相符會在備援期間略過該候選項。沒有宣告結構描述的提供者會原樣接收選項。執行 video_generate action=list 可查看每個提供者接受的內容。

不是所有提供者都支援所有參數。OpenClaw 會將時長正規化為最接近的提供者支援值，並在備援提供者暴露不同控制表面時，重新對應已轉譯的幾何提示，例如尺寸轉外觀比例。真正不支援的覆寫會盡力忽略，並在工具結果中回報為警告。硬性能力限制（例如過多參考輸入）會在提交前失敗。工具結果會回報已套用的設定；details.normalization 會擷取任何請求到已套用的轉譯。

參考輸入會選擇執行階段模式：

沒有參考媒體 → generate
任何圖片參考 → imageToVideo
任何影片參考 → videoToVideo
參考音訊輸入不會變更已解析模式；它們會套用在圖片/影片參考所選模式之上，且只會在宣告 maxInputAudios 的提供者上運作。

混用圖片與影片參考不是穩定的共用能力表面。建議每個請求只使用一種參考類型。

備援與型別化選項

某些能力檢查會在備援層套用，而不是在工具邊界套用，因此超出主要提供者限制的請求仍可在具備能力的備援上執行：

當請求包含音訊參考時，宣告沒有 maxInputAudios（或 0）的作用中候選項會被略過；接著嘗試下一個候選項。
作用中候選項的 maxDurationSeconds 低於請求的 durationSeconds，且未宣告 supportedDurationSeconds 清單 → 略過。
請求包含 providerOptions，且作用中候選項明確宣告型別化 providerOptions 結構描述 → 若提供的鍵不在結構描述中，或值型別不相符，則略過。沒有宣告結構描述的提供者會原樣接收選項（向後相容透傳）。提供者可透過宣告空結構描述（capabilities.providerOptions: {}）選擇退出所有提供者選項，這會造成與型別不相符相同的略過。

請求中的第一個略過原因會以 warn 記錄，讓操作員看到其主要提供者何時被跳過；後續略過會以 debug 記錄，以避免冗長備援鏈過於吵雜。如果每個候選項都被略過，彙總錯誤會包含每個項目的略過原因。

動作

動作	作用
`generate`	預設。從給定提示和選用參考輸入建立影片。
`status`	在不啟動另一個生成的情況下，檢查目前工作階段中進行中影片任務的狀態。
`list`	顯示可用提供者、模型及其能力。

模型選擇

OpenClaw 會依此順序解析模型：

model 工具參數 - 如果代理在呼叫中指定。
設定中的 videoGenerationModel.primary。
依序使用 videoGenerationModel.fallbacks。
自動偵測 - 具有有效驗證的提供者，從目前預設提供者開始，然後依字母順序處理其餘提供者。

如果某個提供者失敗，會自動嘗試下一個候選項。如果所有候選項都失敗，錯誤會包含每次嘗試的詳細資料。設定 agents.defaults.mediaGenerationAutoProviderFallback: false，即可只使用明確的 model、primary 和 fallbacks 項目。

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
      },
    },
  },
}

提供者備註

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（數字）、draft（布林 - 強制 480p）、camera_fixed（布林）。

BytePlus Seedance 1.5

需要 @openclaw/byteplus-modelark Plugin。提供者 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 （數字）會被轉送。

BytePlus Seedance 2.0

需要 @openclaw/byteplus-modelark Plugin。提供者 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 （數字）會被轉送。

ComfyUI

以工作流程驅動的本機或雲端執行。透過設定的圖表支援文字轉影片和圖片轉影片。

fal

對長時間執行的工作使用佇列支援流程。OpenClaw 預設最多等待 20 分鐘，之後會將進行中的 fal 佇列工作視為逾時。多數 fal 影片模型接受單一圖片參照。Seedance 2.0 reference-to-video 模型最多接受 9 張圖片、3 個影片和 3 個音訊參照，且參照檔案總數最多為 12 個。

Google (Gemini / Veo)

支援一個圖片或一個影片參照。在 Gemini API 路徑上，產生音訊的請求會以警告略過，因為該 API 會拒絕目前 Veo 影片生成的 generateAudio 參數。

MiniMax

僅支援單一圖片參照。MiniMax 接受 768P 和 1080P 解析度；像 720P 這類請求會在提交前正規化為最接近的支援值。

OpenAI

只會轉送 size 覆寫。其他樣式覆寫 (aspectRatio, resolution, audio, watermark) 會以警告略過。

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 後端。參照輸入必須是遠端 http(s) URL；本機檔案會預先遭到拒絕。

Runway

透過資料 URI 支援本機檔案。影片轉影片需要 runway/gen4_aleph。純文字執行會公開 16:9 和 9:16 外觀比例。

Together

僅支援單一圖片參照。

Vydra

直接使用 https://www.vydra.ai/api/v1，以避免重新導向時捨棄驗證。veo3 內建為僅支援文字轉影片；kling 需要遠端圖片 URL。

xAI

支援文字轉影片、單一首影格圖片轉影片、透過 xAI reference_images 傳入最多 7 個 reference_image 輸入，以及遠端影片編輯/延伸流程。

提供者能力模式

共用影片生成合約支援特定模式的能力，而不只是扁平彙總限制。新的提供者實作應優先使用明確的模式區塊：

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

這個即時檔案會從 ~/.profile 載入缺少的提供者環境變數，預設優先使用即時/環境 API 金鑰，而非已儲存的驗證設定檔，並且預設執行適合發布的煙霧測試：

對掃描中的每個非 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。

目前，只有在你選擇 runway/gen4_aleph 時，共用 videoToVideo 即時路徑才會涵蓋 runway。

設定

在你的 OpenClaw 設定中設定預設影片生成模型：

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

或透過 CLI：

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

Documentation Index

​快速開始

​非同步生成如何運作

​任務生命週期

​支援的供應商

​功能矩陣

​工具參數

​必填

​內容輸入

​樣式控制

​進階

​備援與型別化選項

​動作

​模型選擇

​提供者備註

​提供者能力模式

​即時測試

​設定

​相關

快速開始

非同步生成如何運作

任務生命週期

支援的供應商

功能矩陣

工具參數

必填

內容輸入

樣式控制

進階

備援與型別化選項

動作

模型選擇

提供者備註

提供者能力模式

即時測試

設定

相關