Перейти до основного вмісту
Агенти OpenClaw можуть генерувати відео з текстових запитів, референсних зображень або наявних відео. Підтримуються шістнадцять бекендів провайдерів, кожен із різними параметрами моделей, режимами вводу та наборами функцій. Агент автоматично вибирає відповідного провайдера на основі вашої конфігурації та доступних ключів API.
Інструмент video_generate з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, задайте ключ API провайдера або налаштуйте agents.defaults.videoGenerationModel.
OpenClaw розглядає генерацію відео як три режими виконання:
  • generate - запити text-to-video без референсних медіа.
  • imageToVideo - запит містить одне або кілька референсних зображень.
  • videoToVideo - запит містить одне або кілька референсних відео.
Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний режим перед надсиланням і повідомляє підтримувані режими в action=list.

​
Швидкий старт

1

Налаштуйте автентифікацію

Задайте ключ API для будь-якого підтримуваного провайдера:
export GEMINI_API_KEY="your-key"
2

Виберіть стандартну модель (необов’язково)

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

Попросіть агента

Згенеруй 5-секундне кінематографічне відео дружнього лобстера, який серфить на заході сонця.
Агент автоматично викликає video_generate. Додавати інструмент до списку дозволених не потрібно.

​
Як працює асинхронна генерація

Генерація відео є асинхронною. Коли агент викликає video_generate у сеансі:
  1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання.
  2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до кількох хвилин залежно від провайдера та роздільної здатності; повільні провайдери з чергами можуть працювати до налаштованого тайм-ауту).
  3. Коли відео готове, OpenClaw пробуджує той самий сеанс внутрішньою подією завершення.
  4. Агент повідомляє користувача через звичайний для сеансу режим видимої відповіді: доставку фінальної відповіді в автоматичному режимі або message(action="send"), коли сеанс вимагає інструмент повідомлень. Якщо сеанс запитувача неактивний або його активне пробудження не вдається, а частина згенерованого відео все ще відсутня у відповіді завершення, 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", щоб перевірити явно без запуску нової генерації.

​
Підтримувані провайдери

ПровайдерСтандартна модельТекстРеф. зображенняРеф. відеоАвтентифікація
Alibabawan2.6-t2v✓Так (віддалена URL-адреса)Так (віддалена URL-адреса)MODELSTUDIO_API_KEY
BytePlus (1.0)seedance-1-0-pro-250528✓До 2 зображень (лише моделі I2V; перший + останній кадр)-BYTEPLUS_API_KEY
BytePlus Seedance 1.5seedance-1-5-pro-251215✓До 2 зображень (перший + останній кадр через роль)-BYTEPLUS_API_KEY
BytePlus Seedance 2.0dreamina-seedance-2-0-260128✓До 9 референсних зображеньДо 3 відеоBYTEPLUS_API_KEY
ComfyUIworkflow✓1 зображення-COMFY_API_KEY або COMFY_CLOUD_API_KEY
DeepInfraPixverse/Pixverse-T2V✓--DEEPINFRA_API_KEY
falfal-ai/minimax/video-01-live✓1 зображення; до 9 із Seedance reference-to-videoДо 3 відео із Seedance reference-to-videoFAL_KEY
Googleveo-3.1-fast-generate-preview✓1 зображення1 відеоGEMINI_API_KEY
MiniMaxMiniMax-Hailuo-2.3✓1 зображення-MINIMAX_API_KEY або MiniMax OAuth
OpenAIsora-2✓1 зображення1 відеоOPENAI_API_KEY
OpenRoutergoogle/veo-3.1-fast✓До 4 зображень (перший/останній кадр або референси)-OPENROUTER_API_KEY
Qwenwan2.6-t2v✓Так (віддалена URL-адреса)Так (віддалена URL-адреса)QWEN_API_KEY
Runwaygen4.5✓1 зображення1 відеоRUNWAYML_API_SECRET
TogetherWan-AI/Wan2.2-T2V-A14B✓лише Wan-AI/Wan2.2-I2V-A14B-TOGETHER_API_KEY
Vydraveo3✓1 зображення (kling)-VYDRA_API_KEY
xAIgrok-imagine-video✓1 зображення першого кадру або до 7 reference_images1 відеоXAI_API_KEY
Деякі провайдери приймають додаткові або альтернативні змінні середовища для ключів API. Див. окремі сторінки провайдерів для деталей. Запустіть video_generate action=list, щоб перевірити доступних провайдерів, моделі та режими виконання під час роботи.

​
Матриця можливостей

Явний контракт режимів, який використовують video_generate, контрактні тести та спільний живий обхід:
ПровайдерgenerateimageToVideovideoToVideoСпільні живі лінії сьогодні
Alibaba✓✓✓generate, imageToVideo; videoToVideo пропущено, бо цьому провайдеру потрібні віддалені URL-адреси відео http(s)
BytePlus✓✓-generate, imageToVideo
ComfyUI✓✓-Не входить до спільного обходу; покриття, специфічне для робочих процесів, живе з тестами Comfy
DeepInfra✓--generate; нативні відеосхеми DeepInfra є text-to-video у контракті Plugin
fal✓✓✓generate, imageToVideo; videoToVideo лише під час використання Seedance reference-to-video
Google✓✓✓generate, imageToVideo; спільний videoToVideo пропущено, бо поточний обхід Gemini/Veo на основі буферів не приймає такий ввід
MiniMax✓✓-generate, imageToVideo
OpenAI✓✓✓generate, imageToVideo; спільний videoToVideo пропущено, бо цьому шляху організації/вводу наразі потрібен доступ до редагування відео на боці провайдера
OpenRouter✓✓-generate, imageToVideo
Qwen✓✓✓generate, imageToVideo; videoToVideo пропущено, бо цьому провайдеру потрібні віддалені URL-адреси відео http(s)
Runway✓✓✓generate, imageToVideo; videoToVideo виконується лише коли вибрана модель — runway/gen4_aleph
Together✓✓-generate, imageToVideo
Vydra✓✓-generate; спільний imageToVideo пропущено, бо вбудований veo3 підтримує лише текст, а вбудований kling потребує віддаленої URL-адреси зображення
xAI✓✓✓generate, imageToVideo; videoToVideo пропущено, бо цьому провайдеру наразі потрібна віддалена URL-адреса MP4

​
Параметри інструмента

​
Обов’язкові

​
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, якщо налаштовано, інакше стандартне значення провайдера, задане Plugin, коли воно існує.
​
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 визначає модель у такому порядку:
  1. Параметр інструмента model - якщо агент указує його у виклику.
  2. videoGenerationModel.primary з конфігурації.
  3. videoGenerationModel.fallbacks по порядку.
  4. Автовиявлення - провайдери, які мають дійсну автентифікацію, починаючи з поточного стандартного провайдера, потім решта провайдерів в алфавітному порядку.
Якщо провайдер зазнає невдачі, наступний кандидат пробується автоматично. Якщо всі кандидати зазнають невдачі, помилка містить подробиці з кожної спроби. Задайте 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"],
      },
    },
  },
}

​
Нотатки щодо провайдерів

Використовує асинхронну кінцеву точку DashScope / Model Studio. Еталонні образи та відео мають бути віддаленими URL http(s).
Ідентифікатор провайдера: 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 автоматично перемикаються на відповідний варіант I2V, коли надано образ.Підтримувані ключі providerOptions: seed (число), draft (булеве значення - примусово 480p), camera_fixed (булеве значення).
Потребує Plugin @openclaw/byteplus-modelark. Ідентифікатор провайдера: byteplus-seedance15. Модель: seedance-1-5-pro-251215.Використовує уніфікований API content[]. Підтримує щонайбільше 2 вхідні образи (first_frame + last_frame). Усі вхідні дані мають бути віддаленими URL https://. Задайте role: "first_frame" / "last_frame" для кожного образу або передайте образи позиційно.aspectRatio: "adaptive" автоматично визначає співвідношення з вхідного образу. audio: true зіставляється з generate_audio. providerOptions.seed (число) передається далі.
Потребує Plugin @openclaw/byteplus-modelark. Ідентифікатор провайдера: byteplus-seedance2. Моделі: dreamina-seedance-2-0-260128, dreamina-seedance-2-0-fast-260128.Використовує уніфікований API content[]. Підтримує до 9 еталонних образів, 3 еталонних відео та 3 еталонних аудіофайлів. Усі вхідні дані мають бути віддаленими URL https://. Задайте role для кожного ресурсу - підтримувані значення: "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio".aspectRatio: "adaptive" автоматично визначає співвідношення з вхідного образу. audio: true зіставляється з generate_audio. providerOptions.seed (число) передається далі.
Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф.
Використовує потік на основі черги для довготривалих завдань. OpenClaw за замовчуванням чекає до 20 хвилин, перш ніж вважати завдання черги fal, що виконується, таким, що перевищило час очікування. Більшість відеомоделей fal приймають одне посилання на зображення. Моделі Seedance 2.0 reference-to-video приймають до 9 зображень, 3 відео та 3 аудіопосилань, але не більше 12 файлів-посилань загалом.
Підтримує одне посилання на зображення або одне посилання на відео. Запити на згенероване аудіо ігноруються з попередженням у шляху Gemini API, оскільки цей API відхиляє параметр generateAudio для поточної генерації відео Veo.
Лише одне посилання на зображення. MiniMax приймає роздільні здатності 768P і 1080P; запити на кшталт 720P нормалізуються до найближчого підтримуваного значення перед надсиланням.
Передається лише перевизначення size. Інші перевизначення стилю (aspectRatio, resolution, audio, watermark) ігноруються з попередженням.
Використовує асинхронний API /videos OpenRouter. OpenClaw надсилає завдання, опитує polling_url і завантажує або unsigned_urls, або задокументований endpoint вмісту завдання. Вбудоване типове значення google/veo-3.1-fast оголошує тривалості 4/6/8 секунд, роздільні здатності 720P/1080P та співвідношення сторін 16:9/9:16.
Той самий backend DashScope, що й Alibaba. Вхідні посилання мають бути віддаленими URL-адресами http(s); локальні файли відхиляються наперед.
Підтримує локальні файли через data URI. Для video-to-video потрібен runway/gen4_aleph. Запуски лише з текстом надають співвідношення сторін 16:9 і 9:16.
Лише одне посилання на зображення.
Використовує https://www.vydra.ai/api/v1 напряму, щоб уникнути редиректів, які скидають автентифікацію. veo3 вбудовано лише як text-to-video; для kling потрібна віддалена URL-адреса зображення.
Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7 вхідних reference_image через xAI reference_images, а також віддалені потоки редагування/розширення відео.

​
Режими можливостей провайдера

Спільний контракт генерації відео підтримує можливості, специфічні для режимів, замість лише плоских сукупних обмежень. Новим реалізаціям провайдерів слід надавати перевагу явним блокам режимів: 
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
Цей живий файл за замовчуванням використовує вже експортовані змінні середовища провайдера перед збереженими профілями автентифікації та за замовчуванням запускає перевірку базової працездатності, безпечну для релізу:
  • generate для кожного провайдера не FAL у перевірці.
  • Односекундна підказка з лобстером.
  • Обмеження операції для кожного провайдера з OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 за замовчуванням).
FAL є опційним, оскільки затримка черги на боці провайдера може домінувати над часом релізу: 
pnpm test:live:media video --video-providers fal
Установіть OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1, щоб також запускати оголошені режими трансформації, які спільна перевірка може безпечно виконувати з локальними медіа:
  • imageToVideo, коли capabilities.imageToVideo.enabled.
  • videoToVideo, коли capabilities.videoToVideo.enabled і провайдер/модель приймає локальне відео на основі буфера у спільній перевірці.
Наразі спільний живий шлях videoToVideo охоплює лише runway, коли ви вибираєте runway/gen4_aleph.

​
Конфігурація

Установіть типову модель генерації відео у вашій конфігурації 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"

​
Пов’язане