Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

1

Configure auth

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

Pick a default model (optional)

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

Ask the agent

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

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

Генерація відео є асинхронною. Коли агент викликає video_generate у сеансі:
  1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання.
  2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до кількох хвилин залежно від провайдера та роздільної здатності; повільні провайдери з чергою можуть працювати до налаштованого тайм-ауту).
  3. Коли відео готове, OpenClaw пробуджує той самий сеанс внутрішньою подією завершення.
  4. Агент повідомляє користувача та додає готове відео. У групових/канальних чатах, які використовують видиму доставку лише через інструмент повідомлень, агент передає результат через інструмент повідомлень, замість того щоб 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✓1 зображення-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, контрактні тести та спільний live sweep:
ПровайдерgenerateimageToVideovideoToVideoСпільні live lanes сьогодні
Alibaba✓✓✓generate, imageToVideo; videoToVideo пропущено, бо цьому провайдеру потрібні віддалені http(s) URL відео
BytePlus✓✓-generate, imageToVideo
ComfyUI✓✓-Не входить до спільного sweep; покриття, специфічне для workflow, міститься в тестах Comfy
DeepInfra✓--generate; нативні відеосхеми DeepInfra є text-to-video у вбудованому контракті
fal✓✓✓generate, imageToVideo; videoToVideo лише за використання Seedance reference-to-video
Google✓✓✓generate, imageToVideo; спільний videoToVideo пропущено, бо поточний буферизований Gemini/Veo sweep не приймає такий ввід
MiniMax✓✓-generate, imageToVideo
OpenAI✓✓✓generate, imageToVideo; спільний videoToVideo пропущено, бо цей org/input path наразі потребує provider-side inpaint/remix access
OpenRouter✓✓-generate, imageToVideo
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

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

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

​
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 визначає модель у такому порядку:
  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 через налаштований graph.
Використовує потік на основі черги для тривалих завдань. 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 OpenRouter /videos. 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 через reference_images xAI, а також віддалені потоки редагування/розширення відео.

​
Режими можливостей постачальників

Спільний контракт генерації відео підтримує можливості, специфічні для режимів, а не лише плоскі сукупні обмеження. Нові реалізації постачальників мають надавати перевагу явним блокам режимів: 
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, щоб live тести, контрактні тести та спільний інструмент video_generate могли детерміновано перевіряти підтримку режимів. Коли одна модель у постачальника має ширшу підтримку вхідних посилань, ніж інші, використовуйте maxInputImagesByModel, maxInputVideosByModel або maxInputAudiosByModel замість підвищення обмеження для всього режиму.

​
Live тести

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

​
Пов’язане