Chuyển đến nội dung chính
Các agent OpenClaw tạo video từ câu lệnh văn bản, hình ảnh tham chiếu hoặc video hiện có thông qua video_generate. Mười sáu backend nhà cung cấp được hỗ trợ; agent tự động chọn backend phù hợp dựa trên cấu hình và các khóa API hiện có.
video_generate chỉ xuất hiện khi có ít nhất một nhà cung cấp tạo video khả dụng. Nếu công cụ này không có trong các công cụ của agent, hãy đặt khóa API của nhà cung cấp hoặc cấu hình agents.defaults.videoGenerationModel.
video_generate có ba chế độ runtime, được xác định từ các đầu vào tham chiếu trong lệnh gọi:
  • generate - không có nội dung đa phương tiện tham chiếu (văn bản thành video).
  • imageToVideo - một hoặc nhiều hình ảnh tham chiếu.
  • videoToVideo - một hoặc nhiều video tham chiếu.
Các nhà cung cấp có thể hỗ trợ bất kỳ tập hợp con nào của những chế độ đó. Công cụ xác thực chế độ đang hoạt động trước khi gửi và báo cáo các chế độ được hỗ trợ trong action=list.

​
Bắt đầu nhanh

1

Cấu hình xác thực

Đặt khóa API cho bất kỳ nhà cung cấp nào được hỗ trợ:
2

Chọn mô hình mặc định (không bắt buộc)

3

Yêu cầu agent

Tạo một video điện ảnh dài 5 giây về một chú tôm hùm thân thiện lướt sóng lúc hoàng hôn.
Agent tự động gọi video_generate. Không cần đưa công cụ vào danh sách cho phép.

​
Cách hoạt động của quá trình tạo bất đồng bộ

Quá trình tạo video diễn ra bất đồng bộ:
  1. OpenClaw gửi yêu cầu đến nhà cung cấp và ngay lập tức trả về một mã tác vụ.
  2. Nhà cung cấp xử lý tác vụ trong nền (thường từ 30 giây đến vài phút tùy thuộc vào nhà cung cấp và độ phân giải; các nhà cung cấp chậm sử dụng hàng đợi có thể chạy đến hết thời gian chờ đã cấu hình).
  3. Khi video sẵn sàng, OpenClaw đánh thức cùng phiên bằng một sự kiện hoàn tất nội bộ.
  4. Agent báo cáo video thông qua chế độ phản hồi hiển thị thông thường của phiên: phản hồi cuối tự động hoặc message(action="send") khi phiên yêu cầu công cụ nhắn tin. Nếu phiên của bên yêu cầu không hoạt động, hoặc việc đánh thức phiên thất bại và nội dung đa phương tiện đã tạo vẫn không có trong phản hồi hoàn tất, OpenClaw sẽ gửi một phương án dự phòng trực tiếp có tính lũy đẳng kèm nội dung đa phương tiện.
Trong khi một tác vụ đang được xử lý, các lệnh gọi video_generate trùng lặp trong cùng phiên sẽ trả về trạng thái tác vụ hiện tại thay vì bắt đầu một quá trình tạo khác. Sử dụng action: "status" để kiểm tra mà không kích hoạt quá trình tạo mới, hoặc openclaw tasks list / openclaw tasks show <lookup> từ CLI (xem Tác vụ nền). Bên ngoài các lần chạy agent có phiên hỗ trợ (ví dụ: gọi công cụ trực tiếp), công cụ chuyển sang tạo nội tuyến và trả về đường dẫn nội dung đa phương tiện cuối cùng trong cùng lượt. Các tệp video được tạo sẽ được lưu trong kho lưu trữ nội dung đa phương tiện do OpenClaw quản lý khi nhà cung cấp trả về dữ liệu byte. Giới hạn mặc định là 16MB (giới hạn nội dung đa phương tiện video dùng chung); agents.defaults.mediaMaxMb tăng giới hạn này cho các bản kết xuất lớn hơn. Khi nhà cung cấp cũng trả về URL đầu ra được lưu trữ, OpenClaw sẽ phân phối URL đó thay vì làm tác vụ thất bại nếu quá trình lưu cục bộ từ chối một tệp quá lớn.

​
Vòng đời tác vụ

Kiểm tra trạng thái từ CLI:

​
Các nhà cung cấp được hỗ trợ

Một số nhà cung cấp chấp nhận các biến môi trường khóa API bổ sung hoặc thay thế. Xem các trang về nhà cung cấp riêng lẻ để biết chi tiết. Chạy video_generate action=list để kiểm tra các nhà cung cấp, mô hình và chế độ runtime khả dụng trong lúc chạy.

​
Ma trận khả năng

Hợp đồng chế độ tường minh được sử dụng bởi video_generate, các kiểm thử hợp đồng và đợt quét trực tiếp dùng chung:

​
Tham số công cụ

​
Bắt buộc

​
prompt
string
bắt buộc
Mô tả bằng văn bản về video cần tạo. Bắt buộc đối với action: "generate".

​
Đầu vào nội dung

​
image
string
Một hình ảnh tham chiếu (đường dẫn hoặc URL).
​
images
string[]
Nhiều hình ảnh tham chiếu (tối đa 9).
​
imageRoles
string[]
Các gợi ý vai trò tùy chọn theo từng vị trí, tương ứng với danh sách hình ảnh đã kết hợp. Các giá trị chuẩn: first_frame, last_frame, reference_image.
​
video
string
Một video tham chiếu (đường dẫn hoặc URL).
​
videos
string[]
Nhiều video tham chiếu (tối đa 4).
​
videoRoles
string[]
Các gợi ý vai trò tùy chọn theo từng vị trí, tương ứng với danh sách video đã kết hợp. Giá trị chuẩn: reference_video.
​
audioRef
string
Một tệp âm thanh tham chiếu (đường dẫn hoặc URL). Dùng làm nhạc nền hoặc tham chiếu giọng nói khi nhà cung cấp hỗ trợ đầu vào âm thanh.
​
audioRefs
string[]
Nhiều tệp âm thanh tham chiếu (tối đa 3).
​
audioRoles
string[]
Các gợi ý vai trò tùy chọn theo từng vị trí, tương ứng với danh sách âm thanh đã kết hợp. Giá trị chuẩn: reference_audio.
Các gợi ý vai trò được chuyển nguyên trạng đến nhà cung cấp. Các giá trị chuẩn đến từ hợp VideoGenerationAssetRole, nhưng nhà cung cấp có thể chấp nhận thêm các chuỗi vai trò khác. Mảng *Roles không được có nhiều mục hơn danh sách tham chiếu tương ứng; lỗi lệch một vị trí sẽ thất bại với thông báo lỗi rõ ràng. Dùng chuỗi rỗng để bỏ trống một vị trí. Với xAI, đặt mọi vai trò hình ảnh thành reference_image để dùng chế độ tạo reference_images; bỏ qua vai trò hoặc dùng first_frame cho chế độ chuyển một hình ảnh thành video.

​
Điều khiển kiểu dáng

​
aspectRatio
string
Gợi ý tỷ lệ khung hình như 1:1, 16:9, 9:16, adaptive hoặc một giá trị dành riêng cho nhà cung cấp. OpenClaw chuẩn hóa hoặc bỏ qua các giá trị không được hỗ trợ tùy theo nhà cung cấp.
​
resolution
string
Gợi ý độ phân giải như 360P, 480P, 540P, 720P, 768P, 1080P, 4K hoặc một giá trị dành riêng cho nhà cung cấp. OpenClaw chuẩn hóa hoặc bỏ qua các giá trị không được hỗ trợ tùy theo nhà cung cấp.
​
durationSeconds
number
Thời lượng mục tiêu tính bằng giây (được làm tròn đến giá trị gần nhất mà nhà cung cấp hỗ trợ).
​
size
string
Gợi ý kích thước khi nhà cung cấp hỗ trợ.
​
audio
boolean
Bật âm thanh được tạo trong đầu ra khi được hỗ trợ. Khác với audioRef* (đầu vào).
​
watermark
boolean
Bật hoặc tắt hình mờ của nhà cung cấp khi được hỗ trợ.
adaptive là một giá trị canh gác dành riêng cho nhà cung cấp: giá trị này được chuyển nguyên trạng đến các nhà cung cấp khai báo adaptive trong khả năng của họ (ví dụ: BytePlus Seedance dùng giá trị này để tự động phát hiện tỷ lệ từ kích thước hình ảnh đầu vào). Các nhà cung cấp không khai báo giá trị này sẽ hiển thị giá trị qua details.ignoredOverrides trong kết quả công cụ để việc loại bỏ có thể nhận biết được.

​
Nâng cao

​
action
"generate" | "status" | "list"
mặc định:"generate"
"status" trả về tác vụ của phiên hiện tại; "list" kiểm tra các nhà cung cấp.
​
model
string
Ghi đè nhà cung cấp/mô hình (ví dụ: runway/gen4.5).
​
filename
string
Gợi ý tên tệp đầu ra.
​
timeoutMs
number
Thời gian chờ tùy chọn cho thao tác của nhà cung cấp, tính bằng mili giây. Khi bỏ qua, OpenClaw dùng agents.defaults.videoGenerationModel.timeoutMs nếu đã định cấu hình; nếu không, dùng giá trị mặc định của nhà cung cấp do tác giả plugin thiết lập khi có.
​
providerOptions
object
Các tùy chọn dành riêng cho nhà cung cấp dưới dạng đối tượng JSON (ví dụ: {"seed": 42, "draft": true}). Những nhà cung cấp khai báo lược đồ có kiểu sẽ xác thực các khóa và kiểu; các khóa không xác định hoặc không khớp kiểu sẽ khiến ứng viên bị bỏ qua trong quá trình dự phòng. Các nhà cung cấp không có lược đồ được khai báo sẽ nhận nguyên trạng các tùy chọn. Chạy video_generate action=list để xem từng nhà cung cấp chấp nhận những gì.
Không phải mọi nhà cung cấp đều hỗ trợ tất cả tham số. OpenClaw chuẩn hóa thời lượng thành giá trị gần nhất mà nhà cung cấp hỗ trợ và ánh xạ lại các gợi ý hình học đã chuyển đổi, chẳng hạn từ kích thước sang tỷ lệ khung hình, khi nhà cung cấp dự phòng cung cấp một bề mặt điều khiển khác. Các giá trị ghi đè thực sự không được hỗ trợ sẽ bị bỏ qua theo nguyên tắc nỗ lực tối đa và được báo cáo dưới dạng cảnh báo trong kết quả công cụ. Các giới hạn cứng về khả năng (chẳng hạn quá nhiều đầu vào tham chiếu) sẽ gây lỗi trước khi gửi. Kết quả công cụ báo cáo các thiết lập đã áp dụng; details.normalization ghi lại mọi chuyển đổi từ giá trị được yêu cầu sang giá trị được áp dụng.
Các đầu vào tham chiếu xác định chế độ thời gian chạy:
  • Không có phương tiện tham chiếu -> generate
  • Có bất kỳ hình ảnh tham chiếu nào -> imageToVideo
  • Có bất kỳ video tham chiếu nào -> videoToVideo
  • Đầu vào âm thanh tham chiếu không thay đổi chế độ đã phân giải; chúng được áp dụng bổ sung trên chế độ do các tham chiếu hình ảnh/video lựa chọn và chỉ hoạt động với các nhà cung cấp khai báo maxInputAudios.
Kết hợp tham chiếu hình ảnh và video không phải là một bề mặt khả năng dùng chung ổn định. Nên dùng một loại tham chiếu cho mỗi yêu cầu.

​
Dự phòng và các tùy chọn có kiểu

Một số bước kiểm tra khả năng được áp dụng tại lớp dự phòng thay vì ranh giới công cụ, vì vậy một yêu cầu vượt quá giới hạn của nhà cung cấp chính vẫn có thể chạy trên một nhà cung cấp dự phòng đủ khả năng:
  • Ứng viên đang hoạt động không khai báo maxInputAudios (hoặc 0) sẽ bị bỏ qua khi yêu cầu chứa tham chiếu âm thanh; ứng viên tiếp theo sẽ được thử. Cơ chế bảo vệ tương tự áp dụng cho số lượng tham chiếu hình ảnh và video so với maxInputImages/maxInputVideos.
  • maxDurationSeconds của ứng viên đang hoạt động thấp hơn durationSeconds được yêu cầu và không có danh sách supportedDurationSeconds được khai báo -> bị bỏ qua.
  • Yêu cầu chứa providerOptions và ứng viên đang hoạt động khai báo rõ ràng một lược đồ providerOptions có kiểu -> bị bỏ qua nếu các khóa được cung cấp không có trong lược đồ hoặc kiểu giá trị không khớp. Các nhà cung cấp không có lược đồ được khai báo sẽ nhận nguyên trạng các tùy chọn (truyền thẳng tương thích ngược). Nhà cung cấp có thể từ chối mọi tùy chọn của nhà cung cấp bằng cách khai báo một lược đồ rỗng (capabilities.providerOptions: {}), điều này dẫn đến việc bị bỏ qua tương tự như khi không khớp kiểu.
Lý do bỏ qua đầu tiên trong một yêu cầu được ghi nhật ký ở warn để người vận hành biết khi nào nhà cung cấp chính của họ bị bỏ qua; các lần bỏ qua tiếp theo được ghi ở debug để giữ im lặng cho các chuỗi dự phòng dài. Nếu mọi ứng viên đều bị bỏ qua, lỗi tổng hợp sẽ bao gồm lý do bỏ qua của từng ứng viên.

​
Hành động

​
Lựa chọn mô hình

OpenClaw phân giải mô hình theo thứ tự sau:
  1. Tham số công cụ model - nếu tác nhân chỉ định một tham số trong lệnh gọi.
  2. videoGenerationModel.primary từ cấu hình.
  3. videoGenerationModel.fallbacks theo thứ tự.
  4. Tự động phát hiện - các nhà cung cấp có thông tin xác thực hợp lệ, bắt đầu bằng nhà cung cấp mặc định hiện tại, sau đó là các nhà cung cấp còn lại theo thứ tự bảng chữ cái.
Nếu một nhà cung cấp thất bại, ứng viên tiếp theo sẽ tự động được thử. Nếu tất cả ứng viên đều thất bại, lỗi sẽ bao gồm chi tiết từ từng lần thử. Đặt agents.defaults.mediaGenerationAutoProviderFallback: false để chỉ dùng các mục model, primary và fallbacks rõ ràng.

​
Ghi chú về nhà cung cấp

Dùng điểm cuối bất đồng bộ của DashScope / Model Studio. Hình ảnh và video tham chiếu phải là URL http(s) từ xa.
ID nhà cung cấp: byteplus.Các mô hình: seedance-1-0-pro-250528 (mặc định), seedance-1-5-pro-251215.Dùng API content[] hợp nhất. Hỗ trợ tối đa 2 hình ảnh đầu vào (first_frame + last_frame). Truyền hình ảnh theo vị trí hoặc đặt rõ ràng role của từng hình ảnh.Các khóa providerOptions được hỗ trợ: seed (số), draft (boolean - buộc dùng 480p), camera_fixed (boolean).
Yêu cầu plugin @openclaw/byteplus-modelark (bên ngoài, không đi kèm). ID nhà cung cấp: byteplus-seedance15. Mô hình: seedance-1-5-pro-251215.Dùng API content[] hợp nhất. Hỗ trợ tối đa 2 hình ảnh đầu vào (first_frame + last_frame). Mọi đầu vào phải là URL https:// từ xa. Đặt role: "first_frame" / "last_frame" trên từng hình ảnh hoặc truyền hình ảnh theo vị trí.aspectRatio: "adaptive" tự động phát hiện tỷ lệ từ hình ảnh đầu vào. audio: true ánh xạ tới generate_audio. providerOptions.seed (số) được chuyển tiếp.
Yêu cầu plugin @openclaw/byteplus-modelark (bên ngoài, không đi kèm). ID nhà cung cấp: byteplus-seedance2. Các mô hình: dreamina-seedance-2-0-260128, dreamina-seedance-2-0-fast-260128.Dùng API content[] hợp nhất. Hỗ trợ tối đa 9 hình ảnh tham chiếu, 3 video tham chiếu và 3 tệp âm thanh tham chiếu. Mọi đầu vào phải là URL https:// từ xa. Đặt role trên từng nội dung - các giá trị được hỗ trợ: "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio".aspectRatio: "adaptive" tự động phát hiện tỷ lệ từ hình ảnh đầu vào. audio: true ánh xạ tới generate_audio. providerOptions.seed (số) được chuyển tiếp.
Thực thi cục bộ hoặc trên đám mây theo quy trình làm việc. Hỗ trợ chuyển văn bản thành video và hình ảnh thành video thông qua đồ thị đã cấu hình.
Sử dụng luồng dựa trên hàng đợi cho các tác vụ chạy dài. Theo mặc định, OpenClaw chờ tối đa 20 phút trước khi coi một tác vụ hàng đợi fal đang xử lý là hết thời gian chờ. Hầu hết các mô hình video fal chấp nhận một tham chiếu hình ảnh duy nhất. Các mô hình chuyển tham chiếu thành video Seedance 2.0 chấp nhận tối đa 9 hình ảnh, 3 video và 3 tham chiếu âm thanh, với tổng cộng không quá 12 tệp tham chiếu.
Hỗ trợ một tham chiếu hình ảnh hoặc một tham chiếu video. Các yêu cầu tạo âm thanh bị bỏ qua kèm cảnh báo trên đường dẫn API Gemini vì API đó từ chối tham số generateAudio đối với tính năng tạo video Veo hiện tại.
Chỉ hỗ trợ một tham chiếu hình ảnh. MiniMax chấp nhận các độ phân giải 768P và 1080P; các yêu cầu như 720P được chuẩn hóa thành giá trị được hỗ trợ gần nhất trước khi gửi.
Chỉ giá trị ghi đè size được chuyển tiếp. Các giá trị ghi đè kiểu khác (aspectRatio, resolution, audio, watermark) bị bỏ qua kèm cảnh báo.
Sử dụng API /videos bất đồng bộ của OpenRouter. OpenClaw gửi tác vụ, thăm dò polling_url và tải xuống unsigned_urls hoặc điểm cuối nội dung tác vụ được ghi trong tài liệu. Giá trị mặc định google/veo-3.1-fast đi kèm công bố thời lượng 4/6/8 giây, độ phân giải 720P/1080P và tỷ lệ khung hình 16:9/9:16.
Dùng cùng phần phụ trợ DashScope như Alibaba. Đầu vào tham chiếu phải là URL http(s) từ xa; các tệp cục bộ bị từ chối ngay từ đầu.
Hỗ trợ tệp cục bộ thông qua URI dữ liệu. Chuyển video thành video yêu cầu runway/gen4_aleph. Các lần chạy chỉ dùng văn bản cung cấp tỷ lệ khung hình 16:9 và 9:16.
Chỉ hỗ trợ một tham chiếu hình ảnh.
Sử dụng trực tiếp https://www.vydra.ai/api/v1 để tránh các chuyển hướng làm mất thông tin xác thực. veo3 được tích hợp chỉ để chuyển văn bản thành video; kling yêu cầu URL hình ảnh từ xa.
Mô hình grok-imagine-video mặc định hỗ trợ chuyển văn bản thành video, chuyển một hình ảnh khung hình đầu tiên thành video, tối đa 7 đầu vào reference_image thông qua reference_images của xAI và các luồng chỉnh sửa/mở rộng video từ xa. Theo mặc định, quá trình tạo dùng 480P; thao tác chuyển một hình ảnh thành video kế thừa tỷ lệ nguồn khi bỏ qua aspectRatio. Chỉnh sửa/mở rộng video kế thừa kích thước hình học đầu vào và không chấp nhận giá trị ghi đè tỷ lệ khung hình hoặc độ phân giải. Thao tác mở rộng chấp nhận 2-10 giây.grok-imagine-video-1.5 chỉ hỗ trợ chuyển hình ảnh thành video: hãy cung cấp chính xác một hình ảnh. Mô hình này hỗ trợ 1-15 giây và 480P, 720P hoặc 1080P, với giá trị mặc định là 480P; bỏ qua aspectRatio để kế thừa tỷ lệ hình ảnh nguồn. Các mã định danh bản xem trước và bản 1.5 có ngày nhận cùng quy trình xác thực và được chuyển tiếp mà không thay đổi.

​
Chế độ khả năng của nhà cung cấp

Hợp đồng tạo video dùng chung hỗ trợ các khả năng theo từng chế độ thay vì chỉ các giới hạn tổng hợp dạng phẳng. Các triển khai nhà cung cấp mới nên ưu tiên các khối chế độ rõ ràng:
Các trường tổng hợp dạng phẳng như maxInputImages và maxInputVideos không đủ để công bố khả năng hỗ trợ chế độ chuyển đổi. Nhà cung cấp nên khai báo rõ ràng generate, imageToVideo và videoToVideo để các bài kiểm thử trực tiếp, bài kiểm thử hợp đồng và công cụ video_generate dùng chung có thể xác thực khả năng hỗ trợ chế độ một cách xác định. Khi một mô hình trong một nhà cung cấp hỗ trợ đầu vào tham chiếu rộng hơn các mô hình còn lại, hãy dùng maxInputImagesByModel, maxInputVideosByModel hoặc maxInputAudiosByModel thay vì tăng giới hạn cho toàn bộ chế độ.

​
Kiểm thử trực tiếp

Phạm vi kiểm thử trực tiếp tùy chọn cho các nhà cung cấp tích hợp dùng chung:
Trình bao bọc của kho mã:
Theo mặc định, tệp kiểm thử trực tiếp này ưu tiên các biến môi trường đã xuất của nhà cung cấp hơn các hồ sơ xác thực đã lưu và chạy một bài kiểm tra nhanh an toàn cho bản phát hành theo mặc định:
  • generate cho mọi nhà cung cấp không phải FAL trong lượt kiểm tra.
  • Lời nhắc lobster dài một giây.
  • Giới hạn thao tác cho mỗi nhà cung cấp từ OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (mặc định là 180000).
FAL là tùy chọn vì độ trễ hàng đợi phía nhà cung cấp có thể chiếm phần lớn thời gian phát hành:
Đặt OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 để cũng chạy các chế độ chuyển đổi đã khai báo mà lượt kiểm tra dùng chung có thể thực hiện an toàn với nội dung đa phương tiện cục bộ:
  • imageToVideo khi capabilities.imageToVideo.enabled.
  • videoToVideo khi capabilities.videoToVideo.enabled và nhà cung cấp/mô hình chấp nhận đầu vào video cục bộ dựa trên bộ đệm trong lượt kiểm tra dùng chung.
Hiện tại, làn kiểm thử trực tiếp videoToVideo dùng chung chỉ bao phủ runway khi bạn chọn runway/gen4_aleph.

​
Cấu hình

Đặt mô hình tạo video mặc định trong cấu hình OpenClaw:
Hoặc thông qua CLI:

​
Liên quan