Skip to main content
OpenClaw-agents genereren video’s op basis van tekstprompts, referentieafbeeldingen of bestaande video’s via video_generate. Zestien providerbackends worden ondersteund; de agent kiest automatisch de juiste op basis van de configuratie en beschikbare API-sleutels.
video_generate verschijnt alleen wanneer ten minste één provider voor videogeneratie beschikbaar is. Als deze ontbreekt in je agenttools, stel dan een API-sleutel van een provider in of configureer agents.defaults.mediaModels.video.
video_generate heeft drie runtimemodi, bepaald aan de hand van de referentie-invoer in de aanroep:
  • generate - geen referentiemedia (tekst-naar-video).
  • imageToVideo - een of meer referentieafbeeldingen.
  • videoToVideo - een of meer referentievideo’s.
Providers kunnen elke combinatie 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:
2

Een standaardmodel kiezen (optioneel)

3

De agent vragen

Genereer een filmische video van 5 seconden waarin een vriendelijke kreeft bij zonsondergang surft.
De agent roept video_generate automatisch aan. Het is niet nodig de tool op een toelatingslijst te zetten.

Hoe asynchrone generatie werkt

Videogeneratie verloopt asynchroon:
  1. OpenClaw dient het verzoek in bij de provider en retourneert onmiddellijk een taak-id.
  2. De provider verwerkt de taak op de achtergrond (doorgaans 30 seconden tot enkele minuten, afhankelijk van de provider en resolutie; trage providers met wachtrijen kunnen doorgaan tot de geconfigureerde time-out).
  3. Wanneer de video gereed is, activeert OpenClaw dezelfde sessie met een interne voltooiingsgebeurtenis.
  4. De agent rapporteert deze via de normale modus voor zichtbare antwoorden van de sessie: een automatisch eindantwoord, of message(action="send") wanneer de sessie de berichtentool vereist. Als de sessie van de aanvrager inactief is, of het activeren ervan mislukt en de gegenereerde media nog steeds ontbreken in het voltooiingsantwoord, verzendt OpenClaw een idempotente directe fallback met de media.
Zolang een taak wordt uitgevoerd, retourneren dubbele aanroepen van video_generate in dezelfde sessie de huidige taakstatus in plaats van een nieuwe generatie te starten. Gebruik action: "status" om de status te controleren zonder een nieuwe generatie te activeren, of openclaw tasks list / openclaw tasks show <lookup> vanuit de CLI (zie Achtergrondtaken). Buiten agentuitvoeringen die aan een sessie zijn gekoppeld (bijvoorbeeld directe toolaanroepen), valt de tool terug op inlinegeneratie en retourneert deze het uiteindelijke mediapad in dezelfde beurt. Gegenereerde videobestanden worden opgeslagen in door OpenClaw beheerde mediaopslag wanneer de provider bytes retourneert. De standaardlimiet is 16MB (de gedeelde limiet voor videomedia); agents.defaults.mediaMaxMb verhoogt deze voor grotere renders. Wanneer een provider ook een gehoste uitvoer-URL retourneert, levert OpenClaw die URL in plaats van de taak te laten mislukken als lokale opslag een te groot bestand weigert.

Levenscyclus van taken

Controleer de status vanuit de CLI:

Ondersteunde providers

Sommige providers accepteren aanvullende of alternatieve omgevingsvariabelen voor API-sleutels. Zie de afzonderlijke providerpagina’s voor details. Voer video_generate action=list uit om tijdens runtime de beschikbare providers, modellen en runtimemodi te bekijken.

Mogelijkhedenmatrix

Het expliciete moduscontract dat wordt gebruikt door video_generate, contracttests en de gedeelde live-controle:

Toolparameters

Vereist

string
vereist
Tekstuele beschrijving van de te genereren video. Vereist voor action: "generate".

Inhoudsinvoer

string
Eén referentieafbeelding (pad of URL).
string[]
Meerdere referentieafbeeldingen (maximaal 9).
string[]
Optionele rolhints per positie, parallel aan de gecombineerde lijst met afbeeldingen. Canonieke waarden: first_frame, last_frame, reference_image.
string
Eén referentievideo (pad of URL).
string[]
Meerdere referentievideo’s (maximaal 4).
string[]
Optionele rolhints per positie, parallel aan de gecombineerde lijst met video’s. Canonieke waarde: reference_video.
string
Eén referentie-audiobestand (pad of URL). Wordt gebruikt voor achtergrondmuziek of als stemreferentie wanneer de provider audio-invoer ondersteunt.
string[]
Meerdere referentie-audiobestanden (maximaal 3).
string[]
Optionele rolhints per positie, parallel aan de gecombineerde lijst met audiobestanden. Canonieke waarde: reference_audio.
Rolhints worden ongewijzigd doorgestuurd naar de provider. Canonieke waarden zijn afkomstig uit de union VideoGenerationAssetRole, maar providers kunnen aanvullende rolstrings accepteren. Arrays met *Roles mogen niet meer items bevatten dan de bijbehorende referentielijst; fouten van één positie verschil mislukken met een duidelijke foutmelding. Gebruik een lege string om een positie 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 afbeelding-naar-video met één afbeelding.

Stijlopties

string
Hint voor de beeldverhouding, zoals 1:1, 16:9, 9:16, adaptive of een providerspecifieke waarde. OpenClaw normaliseert niet-ondersteunde waarden per provider of negeert ze.
string
Hint voor de resolutie, zoals 360P, 480P, 540P, 720P, 768P, 1080P, 4K of een providerspecifieke waarde. OpenClaw normaliseert niet-ondersteunde waarden per provider of negeert ze.
number
Beoogde duur in seconden (afgerond op de dichtstbijzijnde door de provider ondersteunde waarde).
string
Hint voor de grootte wanneer de provider dit ondersteunt.
boolean
Schakel gegenereerde audio in de uitvoer in wanneer dit wordt ondersteund. Staat los van audioRef* (invoer).
boolean
Schakel het watermerk van de provider in of uit wanneer dit wordt ondersteund.
adaptive is een providerspecifieke sentinel: deze wordt ongewijzigd doorgestuurd naar providers die adaptive in hun mogelijkheden declareren (BytePlus Seedance gebruikt dit bijvoorbeeld om de verhouding automatisch af te leiden uit de afmetingen van de invoerafbeelding). Providers die dit niet declareren, vermelden de waarde via details.ignoredOverrides in het toolresultaat, zodat zichtbaar is dat deze is weggelaten.

Geavanceerd

"generate" | "status" | "list"
standaard:"generate"
"status" retourneert de huidige sessietaak; "list" inspecteert providers.
string
Overschrijving van provider/model (bijvoorbeeld runway/gen4.5).
string
Hint voor de uitvoerbestandsnaam.
number
Optionele time-out voor de providerbewerking in milliseconden. Wanneer deze wordt weggelaten, gebruikt OpenClaw agents.defaults.mediaModels.video.timeoutMs indien geconfigureerd, en anders de door de pluginauteur ingestelde standaardwaarde van de provider als die bestaat.
object
Providerspecifieke opties als JSON-object (bijvoorbeeld {"seed": 42, "draft": true}). Providers die een getypeerd schema declareren, valideren de sleutels en typen; bij onbekende sleutels of afwijkingen wordt de kandidaat tijdens de fallback overgeslagen. Providers zonder 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 aanbiedt. Daadwerkelijk niet-ondersteunde overschrijvingen worden naar beste vermogen genegeerd en als waarschuwingen in het toolresultaat gemeld. Harde capaciteitslimieten (zoals te veel referentie-invoer) leiden vóór verzending tot een fout. Toolresultaten vermelden de toegepaste instellingen; details.normalization registreert elke vertaling van aangevraagd naar toegepast.
Referentie-invoer bepaalt de runtimemodus:
  • Geen referentiemedia -> generate
  • Een of meer afbeeldingsreferenties -> imageToVideo
  • Een of meer videoreferenties -> videoToVideo
  • Referentie-audio-invoer verandert de vastgestelde modus niet; deze wordt toegepast boven op de modus die door de afbeeldings-/videoreferenties wordt bepaald en werkt alleen met providers die maxInputAudios declareren.
Gemengde afbeeldings- en videoreferenties vormen geen stabiel gedeeld capaciteitsoppervlak. Gebruik bij voorkeur één referentietype per aanvraag.

Fallback en getypeerde opties

Sommige capaciteitscontroles vinden plaats in de fallbacklaag in plaats van aan de grens van de tool, zodat een aanvraag die de limieten van de primaire provider overschrijdt, toch kan worden uitgevoerd door een geschikte fallback:
  • Een actieve kandidaat die geen maxInputAudios (of 0) declareert, wordt overgeslagen wanneer de aanvraag audioreferenties bevat; de volgende kandidaat wordt geprobeerd. Dezelfde beveiliging geldt voor het aantal afbeeldings- en videoreferenties ten opzichte van maxInputImages/maxInputVideos.
  • De maxDurationSeconds van de actieve kandidaat ligt onder de aangevraagde durationSeconds en er is geen lijst met supportedDurationSeconds gedeclareerd -> wordt overgeslagen.
  • De aanvraag bevat providerOptions en de actieve kandidaat declareert expliciet een getypeerd providerOptions-schema -> wordt overgeslagen als opgegeven sleutels niet in het schema staan of waardetypen niet overeenkomen. Providers zonder gedeclareerd schema ontvangen opties ongewijzigd (achterwaarts compatibele doorgifte). Een provider kan alle provideropties uitsluiten door een leeg schema (capabilities.providerOptions: {}) te declareren, wat dezelfde overslag veroorzaakt als een typeafwijking.
De eerste reden voor overslaan binnen een aanvraag wordt geregistreerd op warn, zodat operators zien wanneer hun primaire provider is gepasseerd; daaropvolgende redenen worden geregistreerd op debug om lange fallbackketens stil te houden. Als elke kandidaat wordt overgeslagen, bevat de samengevoegde foutmelding voor elke kandidaat de reden voor het overslaan.

Acties

Modelselectie

OpenClaw bepaalt het model in deze volgorde:
  1. Toolparameter model - 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 authenticatie, te beginnen met de huidige standaardprovider en vervolgens de resterende providers in alfabetische volgorde.
Als een provider mislukt, wordt automatisch de volgende kandidaat geprobeerd. Als alle kandidaten mislukken, bevat de foutmelding details van elke poging. Automatische fallback tussen geauthenticeerde providers is altijd ingeschakeld. Een model per aanroep blijft gezaghebbend.

Provideropmerkingen

Gebruikt het asynchrone 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-5-pro-251215.Gebruikt de uniforme content[]-API. Ondersteunt maximaal 2 invoerafbeeldingen (first_frame + last_frame). Geef afbeeldingen positioneel door of stel voor elke afbeelding expliciet role in.Ondersteunde providerOptions-sleutels: seed (getal), draft (booleaans - dwingt 480p af), camera_fixed (booleaans).
Vereist de @openclaw/byteplus-modelark Plugin (extern, niet meegeleverd). 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 bestaan uit externe https://- URL’s. Stel voor elke afbeelding role: "first_frame" / "last_frame" in 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 (extern, niet meegeleverd). 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-audiobestanden. Alle invoer moet bestaan uit externe https://-URL’s. Stel voor elk item role in - 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.
Workflowgestuurde lokale uitvoering of uitvoering in de cloud. Ondersteunt tekst-naar-video en afbeelding-naar-video via de geconfigureerde graaf.
Gebruikt een wachtrijgestuurde flow voor langlopende taken. OpenClaw wacht standaard maximaal 20 minuten voordat een actieve fal-wachtrijtaak als verlopen wordt beschouwd. De meeste fal-videomodellen accepteren één afbeeldingsreferentie. Seedance 2.0-modellen voor referentie-naar-video accepteren maximaal 9 afbeeldingen, 3 video’s en 3 audioreferenties, met in totaal maximaal 12 referentiebestanden.
Ondersteunt één afbeeldings- of videoreferentie. Verzoeken om gegenereerde audio worden genegeerd met een waarschuwing in het Gemini API-pad, omdat die API de parameter generateAudio voor de huidige Veo-videogeneratie weigert.
Slechts één afbeeldingsreferentie. MiniMax accepteert de resoluties 768P en 1080P; verzoeken zoals 720P worden vóór verzending genormaliseerd naar de dichtstbijzijnde ondersteunde waarde.
Alleen de overschrijving size wordt doorgestuurd. Andere stijloverschrijvingen (aspectRatio, resolution, audio, watermark) worden genegeerd met een waarschuwing.
Gebruikt de asynchrone /videos-API van OpenRouter. OpenClaw dient de taak in, peilt polling_url en downloadt unsigned_urls of het gedocumenteerde inhoudseindpunt van de taak. De meegeleverde standaardwaarde google/veo-3.1-fast vermeldt tijdsduren 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. Uitvoeringen met alleen tekst bieden de beeldverhoudingen 16:9 en 9:16.
Slechts één afbeeldingsreferentie.
Gebruikt https://www.vydra.ai/api/v1 rechtstreeks om omleidingen te vermijden waarbij authenticatie verloren gaat. veo3 wordt alleen voor tekst-naar-video meegeleverd; kling vereist een externe afbeeldings-URL.
Het standaardmodel grok-imagine-video ondersteunt tekst-naar-video, afbeelding-naar-video met één afbeelding als eerste frame, maximaal 7 reference_image-invoeritems via xAI reference_images, en externe flows voor videobewerking/-verlenging. Generatie gebruikt standaard 480P; afbeelding-naar-video met één afbeelding neemt de verhouding van de bron over wanneer aspectRatio is weggelaten. Videobewerking/-verlenging neemt de geometrie van de invoer over en accepteert geen overschrijvingen voor beeldverhouding of resolutie. Verlenging accepteert 2-10 seconden.grok-imagine-video-1.5 is alleen voor afbeelding-naar-video: geef precies één afbeelding op. Het ondersteunt 1-15 seconden en 480P, 720P of 1080P, met standaard 480P; laat aspectRatio weg om de verhouding van de bronafbeelding over te nemen. De preview- en gedateerde 1.5-identificaties krijgen dezelfde validatie en worden ongewijzigd doorgestuurd.

Mogelijkheidsmodi van providers

Het gedeelde contract voor videogeneratie ondersteunt modusspecifieke mogelijkheden in plaats van alleen platte geaggregeerde limieten. Nieuwe providerimplementaties moeten bij voorkeur expliciete modusblokken gebruiken:
Platte geaggregeerde velden zoals maxInputImages en maxInputVideos zijn niet voldoende om ondersteuning voor transformatiemodi aan te geven. Providers moeten generate, imageToVideo en videoToVideo expliciet declareren, zodat live tests, contracttests en de gedeelde tool video_generate de modusondersteuning deterministisch kunnen valideren. Wanneer één model van een provider ruimere ondersteuning voor referentie-invoer heeft dan de rest, gebruik dan maxInputImagesByModel, maxInputVideosByModel of maxInputAudiosByModel in plaats van de limiet voor de hele modus te verhogen.

Live tests

Optionele live dekking voor de gedeelde meegeleverde providers:
Repo-wrapper:
Dit livebestand gebruikt standaard reeds geëxporteerde omgevingsvariabelen van providers vóór opgeslagen authenticatieprofielen en voert standaard een releaseveilige rooktest uit:
  • generate voor elke niet-FAL-provider in de reeks.
  • Lobster-prompt van één seconde.
  • Limiet voor bewerkingen per provider uit OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (standaard 180000).
FAL is optioneel, omdat wachtrijvertraging bij de provider de releasetijd kan domineren:
Stel OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 in om ook gedeclareerde transformatiemodi uit te voeren die de gedeelde reeks veilig met lokale media kan testen:
  • imageToVideo wanneer capabilities.imageToVideo.enabled.
  • videoToVideo wanneer capabilities.videoToVideo.enabled en het provider/model lokale video-invoer op basis van buffers in de gedeelde reeks accepteert.
Momenteel dekt de gedeelde live-lane videoToVideo alleen runway wanneer je runway/gen4_aleph selecteert.

Configuratie

Stel het standaardmodel voor videogeneratie in je OpenClaw-configuratie in:
Of via de CLI:

Gerelateerd