Naar hoofdinhoud gaan

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-agenten kunnen video’s genereren uit tekstprompts, referentieafbeeldingen of bestaande video’s. Zestien providerbackends worden ondersteund, elk met andere modelopties, invoermodi en functiesets. De agent kiest automatisch de juiste provider op basis van je configuratie en beschikbare API-sleutels.
De tool video_generate verschijnt alleen wanneer ten minste één videogeneratieprovider beschikbaar is. Als je deze niet ziet in je agenttools, stel dan een provider-API-sleutel in of configureer agents.defaults.videoGenerationModel.
OpenClaw behandelt videogeneratie als drie runtime-modi:
  • generate - tekst-naar-videoverzoeken zonder referentiemedia.
  • imageToVideo - verzoek bevat één of meer referentieafbeeldingen.
  • videoToVideo - verzoek bevat één of meer referentievideo’s.
Providers kunnen elke subset van deze modi ondersteunen. De tool valideert de actieve modus vóór indiening en rapporteert ondersteunde modi in action=list.

Snel aan de slag

1

Authenticatie configureren

Stel een API-sleutel in voor een ondersteunde provider:
export GEMINI_API_KEY="your-key"
2

Een standaardmodel kiezen (optioneel)

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

Vraag het de agent

Genereer een filmische video van 5 seconden van een vriendelijke kreeft die surft bij zonsondergang.
De agent roept video_generate automatisch aan. Geen allowlisting van tools is nodig.

Hoe asynchrone generatie werkt

Videogeneratie is asynchroon. Wanneer de agent video_generate aanroept in een sessie:
  1. OpenClaw dient het verzoek in bij de provider en retourneert onmiddellijk een taak-id.
  2. De provider verwerkt de taak op de achtergrond (meestal 30 seconden tot enkele minuten, afhankelijk van de provider en resolutie; trage providers met wachtrijen kunnen tot de geconfigureerde time-out lopen).
  3. Wanneer de video klaar is, wekt OpenClaw dezelfde sessie met een interne voltooiingsgebeurtenis.
  4. De agent informeert de gebruiker en voegt de voltooide video toe. In groeps-/kanaalchats die zichtbare levering alleen via berichttools gebruiken, stuurt de agent het resultaat door via de berichttool in plaats van dat OpenClaw het rechtstreeks plaatst.
Terwijl een taak actief is, retourneren dubbele video_generate-aanroepen in dezelfde sessie de huidige taakstatus in plaats van een nieuwe generatie te starten. Gebruik openclaw tasks list of openclaw tasks show <taskId> om de voortgang vanuit de CLI te controleren. Buiten sessiegebonden agentruns (bijvoorbeeld directe toolaanroepen) valt de tool terug op inline generatie en retourneert het uiteindelijke mediapad in dezelfde beurt. Gegenereerde videobestanden worden opgeslagen onder door OpenClaw beheerde mediaopslag wanneer de provider bytes retourneert. De standaard opslaglimiet voor gegenereerde video’s volgt de limiet voor videomedia, en agents.defaults.mediaMaxMb verhoogt deze voor grotere renders. Wanneer een provider ook een gehoste uitvoer-URL retourneert, kan OpenClaw die URL leveren in plaats van de taak te laten mislukken als lokale persistentie een te groot bestand weigert.

Taaklevenscyclus

StatusBetekenis
queuedTaak aangemaakt, wachtend tot de provider deze accepteert.
runningProvider is bezig met verwerken (meestal 30 seconden tot enkele minuten, afhankelijk van provider en resolutie).
succeededVideo gereed; de agent wordt gewekt en plaatst deze in het gesprek.
failedProviderfout of time-out; de agent wordt gewekt met foutdetails.
Controleer de status vanuit de CLI:
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
Als een videotaak al queued of running is voor de huidige sessie, retourneert video_generate de bestaande taakstatus in plaats van een nieuwe te starten. Gebruik action: "status" om expliciet te controleren zonder een nieuwe generatie te activeren.

Ondersteunde providers

ProviderStandaardmodelTekstAfbeeldingsreferentieVideoreferentieAuthenticatie
Alibabawan2.6-t2vJa (externe URL)Ja (externe URL)MODELSTUDIO_API_KEY
BytePlus (1.0)seedance-1-0-pro-250528Tot 2 afbeeldingen (alleen I2V-modellen; eerste + laatste frame)-BYTEPLUS_API_KEY
BytePlus Seedance 1.5seedance-1-5-pro-251215Tot 2 afbeeldingen (eerste + laatste frame via rol)-BYTEPLUS_API_KEY
BytePlus Seedance 2.0dreamina-seedance-2-0-260128Tot 9 referentieafbeeldingenTot 3 video’sBYTEPLUS_API_KEY
ComfyUIworkflow1 afbeelding-COMFY_API_KEY of COMFY_CLOUD_API_KEY
DeepInfraPixverse/Pixverse-T2V--DEEPINFRA_API_KEY
falfal-ai/minimax/video-01-live1 afbeelding; tot 9 met Seedance reference-to-videoTot 3 video’s met Seedance reference-to-videoFAL_KEY
Googleveo-3.1-fast-generate-preview1 afbeelding1 videoGEMINI_API_KEY
MiniMaxMiniMax-Hailuo-2.31 afbeelding-MINIMAX_API_KEY of MiniMax OAuth
OpenAIsora-21 afbeelding1 videoOPENAI_API_KEY
OpenRoutergoogle/veo-3.1-fastTot 4 afbeeldingen (eerste/laatste frame of referenties)-OPENROUTER_API_KEY
Qwenwan2.6-t2vJa (externe URL)Ja (externe URL)QWEN_API_KEY
Runwaygen4.51 afbeelding1 videoRUNWAYML_API_SECRET
TogetherWan-AI/Wan2.2-T2V-A14B1 afbeelding-TOGETHER_API_KEY
Vydraveo31 afbeelding (kling)-VYDRA_API_KEY
xAIgrok-imagine-video1 first-frame-afbeelding of tot 7 reference_images1 videoXAI_API_KEY
Sommige providers accepteren aanvullende of alternatieve omgevingsvariabelen voor API-sleutels. Zie de afzonderlijke providerpagina’s voor details. Voer video_generate action=list uit om beschikbare providers, modellen en runtime-modi tijdens runtime te inspecteren.

Capaciteitsmatrix

Het expliciete moduscontract dat wordt gebruikt door video_generate, contracttests en de gedeelde live sweep:
ProvidergenerateimageToVideovideoToVideoGedeelde live lanes vandaag
Alibabagenerate, imageToVideo; videoToVideo overgeslagen omdat deze provider externe http(s)-video-URL’s nodig heeft
BytePlus-generate, imageToVideo
ComfyUI-Niet in de gedeelde sweep; workflowspecifieke dekking staat bij Comfy-tests
DeepInfra--generate; native DeepInfra-videoschema’s zijn tekst-naar-video in het gebundelde contract
falgenerate, imageToVideo; videoToVideo alleen bij gebruik van Seedance reference-to-video
Googlegenerate, imageToVideo; gedeelde videoToVideo overgeslagen omdat de huidige buffer-backed Gemini/Veo-sweep die invoer niet accepteert
MiniMax-generate, imageToVideo
OpenAIgenerate, imageToVideo; gedeelde videoToVideo overgeslagen omdat dit org-/invoerpad momenteel provider-side inpaint/remix-toegang vereist
OpenRouter-generate, imageToVideo
Qwengenerate, imageToVideo; videoToVideo overgeslagen omdat deze provider externe http(s)-video-URL’s nodig heeft
Runwaygenerate, imageToVideo; videoToVideo draait alleen wanneer het geselecteerde model runway/gen4_aleph is
Together-generate, imageToVideo
Vydra-generate; gedeelde imageToVideo overgeslagen omdat gebundelde veo3 alleen tekst ondersteunt en gebundelde kling een externe afbeeldings-URL vereist
xAIgenerate, imageToVideo; videoToVideo overgeslagen omdat deze provider momenteel een externe MP4-URL nodig heeft

Toolparameters

Vereist

prompt
string
vereist
Tekstbeschrijving van de video die moet worden gegenereerd. Vereist voor action: "generate".

Contentinvoer

image
string
Eén referentieafbeelding (pad of URL).
images
string[]
Meerdere referentieafbeeldingen (maximaal 9).
imageRoles
string[]
Optionele rolhints per positie, parallel aan de gecombineerde afbeeldingenlijst. Canonieke waarden: first_frame, last_frame, reference_image.
video
string
Eén referentievideo (pad of URL).
videos
string[]
Meerdere referentievideo’s (maximaal 4).
videoRoles
string[]
Optionele rolhints per positie, parallel aan de gecombineerde videolijst. Canonieke waarde: reference_video.
audioRef
string
Eén referentie-audio (pad of URL). Gebruikt voor achtergrondmuziek of stemreferentie wanneer de provider audio-invoer ondersteunt.
audioRefs
string[]
Meerdere referentie-audio’s (maximaal 3).
audioRoles
string[]
Optionele rolhints per positie, parallel aan de gecombineerde audiolijst. Canonieke waarde: reference_audio.
Rolhints worden ongewijzigd doorgestuurd naar de provider. Canonieke waarden komen uit de VideoGenerationAssetRole-union, maar providers kunnen aanvullende rolstrings accepteren. *Roles-arrays mogen niet meer items bevatten dan de bijbehorende referentielijst; off-by-one-fouten mislukken met een duidelijke fout. Gebruik een lege string om een slot niet in te stellen. Stel voor xAI elke afbeeldingsrol in op reference_image om de generatiemodus reference_images te gebruiken; laat de rol weg of gebruik first_frame voor image-to-video met één afbeelding.

Stijlbediening

aspectRatio
string
Hint voor beeldverhouding, zoals 1:1, 16:9, 9:16, adaptive of een providerspecifieke waarde. OpenClaw normaliseert of negeert niet-ondersteunde waarden per provider.
resolution
string
Resolutiehint, zoals 480P, 720P, 768P, 1080P, 4K of een providerspecifieke waarde. OpenClaw normaliseert of negeert niet-ondersteunde waarden per provider.
durationSeconds
number
Doelduur in seconden (afgerond naar de dichtstbijzijnde door de provider ondersteunde waarde).
size
string
Groottehint wanneer de provider dit ondersteunt.
audio
boolean
Schakel gegenereerde audio in de uitvoer in wanneer dit wordt ondersteund. Onderscheiden van audioRef* (invoer).
watermark
boolean
Schakel providerwatermerken in of uit wanneer dit wordt ondersteund.
adaptive is een providerspecifieke sentinel: deze wordt ongewijzigd doorgestuurd naar providers die adaptive in hun mogelijkheden declareren (bijv. BytePlus Seedance gebruikt dit om de verhouding automatisch te detecteren op basis van de afmetingen van de invoerafbeelding). Providers die dit niet declareren, tonen de waarde via details.ignoredOverrides in het toolresultaat zodat het wegvallen zichtbaar is.

Geavanceerd

action
"generate" | "status" | "list"
standaard:"generate"
"status" retourneert de huidige sessietaak; "list" inspecteert providers.
model
string
Provider/model-override (bijv. runway/gen4.5).
filename
string
Hint voor uitvoerbestandsnaam.
timeoutMs
number
Optionele time-out voor providerbewerking in milliseconden.
providerOptions
object
Providerspecifieke opties als JSON-object (bijv. {"seed": 42, "draft": true}). Providers die een getypt schema declareren, valideren de sleutels en typen; onbekende sleutels of mismatches slaan de kandidaat over tijdens fallback. Providers zonder een gedeclareerd schema ontvangen de opties ongewijzigd. Voer video_generate action=list uit om te zien wat elke provider accepteert.
Niet alle providers ondersteunen alle parameters. OpenClaw normaliseert de duur naar de dichtstbijzijnde door de provider ondersteunde waarde, en wijst vertaalde geometriehints zoals grootte-naar-beeldverhouding opnieuw toe wanneer een fallbackprovider een ander bedieningsoppervlak biedt. Echt niet-ondersteunde overrides worden op best-effortbasis genegeerd en als waarschuwingen in het toolresultaat gerapporteerd. Harde capaciteitslimieten (zoals te veel referentie-invoer) mislukken vóór indiening. Toolresultaten rapporteren toegepaste instellingen; details.normalization legt elke vertaling van aangevraagd naar toegepast vast.
Referentie-invoer selecteert de runtimemodus:
  • Geen referentiemedia → generate
  • Enige afbeeldingsreferentie → imageToVideo
  • Enige videoreferentie → videoToVideo
  • Referentie-audio-invoer wijzigt niet de opgeloste modus; deze wordt toegepast boven op welke modus de afbeeldings-/videoreferenties ook selecteren, en werkt alleen met providers die maxInputAudios declareren.
Gemengde afbeeldings- en videoreferenties zijn geen stabiel gedeeld capaciteitsoppervlak. Gebruik bij voorkeur één referentietype per verzoek.

Fallback en getypte opties

Sommige capaciteitscontroles worden toegepast in de fallbacklaag in plaats van aan de toolgrens, zodat een verzoek dat de limieten van de primaire provider overschrijdt nog steeds kan draaien op een geschikte fallback:
  • Actieve kandidaat die geen maxInputAudios (of 0) declareert, wordt overgeslagen wanneer het verzoek audioreferenties bevat; de volgende kandidaat wordt geprobeerd.
  • maxDurationSeconds van actieve kandidaat ligt onder de aangevraagde durationSeconds zonder gedeclareerde lijst supportedDurationSeconds → overgeslagen.
  • Verzoek bevat providerOptions en de actieve kandidaat declareert expliciet een getypt providerOptions-schema → overgeslagen als aangeleverde sleutels niet in het schema staan of waardetypen niet overeenkomen. Providers zonder een gedeclareerd schema ontvangen opties ongewijzigd (achterwaarts compatibele passthrough). Een provider kan alle provideropties uitschakelen door een leeg schema te declareren (capabilities.providerOptions: {}), wat dezelfde overslag veroorzaakt als een typemismatch.
De eerste overslagreden in een verzoek wordt op warn gelogd zodat operators zien wanneer hun primaire provider is overgeslagen; daaropvolgende overslagen worden op debug gelogd om lange fallbackketens stil te houden. Als elke kandidaat wordt overgeslagen, bevat de geaggregeerde fout de overslagreden voor elke kandidaat.

Acties

ActieWat deze doet
generateStandaard. Maak een video op basis van de opgegeven prompt en optionele referentie-invoer.
statusControleer de status van de lopende videotaak voor de huidige sessie zonder een nieuwe generatie te starten.
listToon beschikbare providers, modellen en hun mogelijkheden.

Modelselectie

OpenClaw lost het model in deze volgorde op:
  1. model-toolparameter - als de agent er een opgeeft in de aanroep.
  2. videoGenerationModel.primary uit de configuratie.
  3. videoGenerationModel.fallbacks op volgorde.
  4. Automatische detectie - providers met geldige auth, beginnend met de huidige standaardprovider, daarna de resterende providers in alfabetische volgorde.
Als een provider faalt, wordt de volgende kandidaat automatisch geprobeerd. Als alle kandidaten falen, bevat de fout details van elke poging. Stel agents.defaults.mediaGenerationAutoProviderFallback: false in om alleen de expliciete items model, primary en fallbacks te gebruiken.
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
      },
    },
  },
}

Providernotities

Gebruikt het async eindpunt van DashScope / Model Studio. Referentieafbeeldingen en video’s moeten externe http(s)-URL’s zijn.
Provider-id: byteplus.Modellen: seedance-1-0-pro-250528 (standaard), 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-modellen (*-t2v-*) accepteren geen afbeeldingsinvoer; I2V-modellen en algemene *-pro-*-modellen ondersteunen één referentieafbeelding (eerste frame). Geef de afbeelding positioneel door of stel role: "first_frame" in. T2V-model-ID’s worden automatisch omgeschakeld naar de overeenkomstige I2V- variant wanneer een afbeelding wordt opgegeven.Ondersteunde providerOptions-sleutels: seed (getal), draft (boolean - forceert 480p), camera_fixed (boolean).
Vereist de @openclaw/byteplus-modelark Plugin. Provider-id: byteplus-seedance15. Model: seedance-1-5-pro-251215.Gebruikt de uniforme content[]-API. Ondersteunt maximaal 2 invoerafbeeldingen (first_frame + last_frame). Alle invoer moet uit externe https://- URL’s bestaan. Stel role: "first_frame" / "last_frame" in op elke afbeelding, of geef afbeeldingen positioneel door.aspectRatio: "adaptive" detecteert de verhouding automatisch op basis van de invoerafbeelding. audio: true wordt toegewezen aan generate_audio. providerOptions.seed (getal) wordt doorgestuurd.
Vereist de @openclaw/byteplus-modelark Plugin. Provider-id: byteplus-seedance2. Modellen: dreamina-seedance-2-0-260128, dreamina-seedance-2-0-fast-260128.Gebruikt de uniforme content[]-API. Ondersteunt maximaal 9 referentieafbeeldingen, 3 referentievideo’s en 3 referentie-audio’s. Alle invoer moet uit externe https://-URL’s bestaan. Stel role in op elk asset - ondersteunde waarden: "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio".aspectRatio: "adaptive" detecteert de verhouding automatisch op basis van de invoerafbeelding. audio: true wordt toegewezen aan generate_audio. providerOptions.seed (getal) wordt doorgestuurd.
Workflow-gestuurde lokale of cloud-uitvoering. Ondersteunt tekst-naar-video en afbeelding-naar-video via de geconfigureerde grafiek.
Gebruikt een wachtrij-ondersteunde flow voor langlopende taken. OpenClaw wacht standaard maximaal 20 minuten voordat een fal-wachtrijtaak die nog bezig is als verlopen wordt behandeld. De meeste fal-videomodellen accepteren één afbeeldingsreferentie. Seedance 2.0 reference-to-video- modellen accepteren maximaal 9 afbeeldingen, 3 video’s en 3 audioreferenties, met maximaal 12 referentiebestanden in totaal.
Ondersteunt één afbeeldings- of één videoreferentie. Verzoeken voor gegenereerde audio worden genegeerd met een waarschuwing op het Gemini API-pad, omdat die API de parameter generateAudio voor huidige Veo-videogeneratie weigert.
Alleen één afbeeldingsreferentie. MiniMax accepteert resoluties 768P en 1080P; verzoeken zoals 720P worden vóór verzending genormaliseerd naar de dichtstbijzijnde ondersteunde waarde.
Alleen de overschrijving size wordt doorgegeven. Andere stijloverschrijvingen (aspectRatio, resolution, audio, watermark) worden genegeerd met een waarschuwing.
Gebruikt de asynchrone /videos-API van OpenRouter. OpenClaw dient de taak in, pollt polling_url en downloadt ofwel unsigned_urls of het gedocumenteerde eindpunt voor taakinhoud. De meegeleverde standaard google/veo-3.1-fast adverteert duurwaarden van 4/6/8 seconden, resoluties 720P/1080P en beeldverhoudingen 16:9/9:16.
Dezelfde DashScope-backend als Alibaba. Referentie-invoer moet uit externe http(s)-URL’s bestaan; lokale bestanden worden vooraf geweigerd.
Ondersteunt lokale bestanden via data-URI’s. Video-naar-video vereist runway/gen4_aleph. Runs met alleen tekst bieden beeldverhoudingen 16:9 en 9:16.
Alleen één afbeeldingsreferentie.
Gebruikt https://www.vydra.ai/api/v1 rechtstreeks om redirects te vermijden die authenticatie laten vallen. veo3 wordt alleen als tekst-naar-video meegeleverd; kling vereist een externe afbeeldings-URL.
Ondersteunt tekst-naar-video, afbeelding-naar-video met één eerste frame, maximaal 7 reference_image-invoeritems via xAI reference_images, en externe flows voor videobewerking/-uitbreiding.

Mogelijkheidsmodi voor providers

Het gedeelde contract voor videogeneratie ondersteunt modusspecifieke mogelijkheden in plaats van alleen platte geaggregeerde limieten. Nieuwe providerimplementaties moeten de voorkeur geven aan expliciete modusblokken:
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,
  },
}
Platte geaggregeerde velden zoals maxInputImages en maxInputVideos zijn niet genoeg om ondersteuning voor transformatiemodi te adverteren. Providers moeten generate, imageToVideo en videoToVideo expliciet declareren zodat live tests, contracttests en de gedeelde tool video_generate ondersteuning voor modi deterministisch kunnen valideren. Wanneer één model in een provider bredere ondersteuning voor referentie-invoer heeft dan de rest, gebruik dan maxInputImagesByModel, maxInputVideosByModel of maxInputAudiosByModel in plaats van de modusbrede limiet te verhogen.

Live tests

Opt-in live dekking voor de gedeelde meegeleverde providers:
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
Repo-wrapper:
pnpm test:live:media video
Dit live bestand laadt ontbrekende provider-omgevingsvariabelen uit ~/.profile, geeft standaard de voorkeur aan live/env-API-sleutels boven opgeslagen authenticatieprofielen en voert standaard een release-veilige rooktest uit:
  • generate voor elke niet-FAL-provider in de sweep.
  • Kreeftenprompt van één seconde.
  • Operatielimiet per provider uit OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (standaard 180000).
FAL is opt-in omdat wachtrijlatentie aan providerzijde de releasetijd kan domineren:
pnpm test:live:media video --video-providers fal
Stel OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 in om ook gedeclareerde transformatiemodi uit te voeren die de gedeelde sweep veilig met lokale media kan testen:
  • imageToVideo wanneer capabilities.imageToVideo.enabled.
  • videoToVideo wanneer capabilities.videoToVideo.enabled en de provider/het model buffer-ondersteunde lokale video-invoer in de gedeelde sweep accepteert.
Vandaag dekt de gedeelde live lane voor videoToVideo alleen runway wanneer je runway/gen4_aleph selecteert.

Configuratie

Stel het standaardmodel voor videogeneratie in je OpenClaw-configuratie in:
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-r2v-flash"],
      },
    },
  },
}
Of via de CLI:
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"

Gerelateerd