video_generate. Sono supportati sedici backend di
provider; l’agente seleziona automaticamente quello appropriato in base alla configurazione e
alle chiavi API disponibili.
video_generate compare solo quando è disponibile almeno un provider per la
generazione di video. Se non è presente tra gli strumenti dell’agente, imposta una chiave API del provider o
configura agents.defaults.videoGenerationModel.video_generate dispone di tre modalità di runtime, determinate dagli input di riferimento
nella chiamata:
generate- nessun contenuto multimediale di riferimento (da testo a video).imageToVideo- una o più immagini di riferimento.videoToVideo- uno o più video di riferimento.
action=list.
Avvio rapido
1
Configura l'autenticazione
Imposta una chiave API per qualsiasi provider supportato:
2
Scegli un modello predefinito (facoltativo)
3
Chiedi all'agente
Genera un video cinematografico di 5 secondi di un’aragosta amichevole che fa surf al tramonto.L’agente chiama automaticamente
video_generate. Non è necessario inserire
lo strumento in un elenco di elementi consentiti.Funzionamento della generazione asincrona
La generazione di video è asincrona:- OpenClaw invia la richiesta al provider e restituisce immediatamente un ID attività.
- Il provider elabora il processo in background (in genere da 30 secondi a diversi minuti, a seconda del provider e della risoluzione; i provider più lenti basati su coda possono impiegare fino al timeout configurato).
- Quando il video è pronto, OpenClaw riattiva la stessa sessione con un evento interno di completamento.
- L’agente lo comunica tramite la normale modalità di risposta visibile della sessione:
una risposta finale automatica oppure
message(action="send")quando la sessione richiede lo strumento di messaggistica. Se la sessione del richiedente è inattiva, oppure la sua riattivazione non riesce e il contenuto multimediale generato non è ancora presente nella risposta di completamento, OpenClaw invia direttamente un fallback idempotente con il contenuto multimediale.
video_generate nella stessa
sessione restituiscono lo stato dell’attività corrente anziché avviare un’altra
generazione. Usa action: "status" per verificare lo stato senza attivare una nuova
generazione, oppure openclaw tasks list / openclaw tasks show <lookup> dalla
CLI (consulta Attività in background).
Al di fuori delle esecuzioni dell’agente basate su sessione (ad esempio, nelle invocazioni dirette dello strumento),
lo strumento utilizza come fallback la generazione in linea e restituisce il percorso finale del contenuto multimediale
nello stesso turno.
Quando il provider restituisce byte, i file video generati vengono salvati nell’archivio multimediale gestito da OpenClaw.
Il limite predefinito è 16 MB (il limite condiviso per i contenuti multimediali video);
agents.defaults.mediaMaxMb consente di aumentarlo per rendering più grandi. Quando un
provider restituisce anche un URL di output ospitato, OpenClaw distribuisce tale URL anziché
segnalare l’attività come non riuscita se la persistenza locale rifiuta un file di dimensioni eccessive.
Ciclo di vita dell’attività
Verifica lo stato dalla CLI:
Provider supportati
Alcuni provider accettano variabili di ambiente aggiuntive o alternative per la chiave API. Consulta
le singole pagine dei provider per i dettagli.
Esegui
video_generate action=list per esaminare durante il runtime i provider, i modelli e
le modalità di runtime disponibili.
Matrice delle funzionalità
Il contratto esplicito delle modalità utilizzato davideo_generate, dai test del contratto e
dall’analisi live condivisa:
Parametri dello strumento
Obbligatori
string
obbligatorio
Descrizione testuale del video da generare. Obbligatoria per
action: "generate".Input dei contenuti
string
Singola immagine di riferimento (percorso o URL).
string[]
Più immagini di riferimento (fino a 9).
string[]
Indicazioni facoltative sul ruolo per posizione, parallele all’elenco combinato delle immagini.
Valori canonici:
first_frame, last_frame, reference_image.string
Singolo video di riferimento (percorso o URL).
string[]
Più video di riferimento (fino a 4).
string[]
Indicazioni facoltative sul ruolo per posizione, parallele all’elenco combinato dei video.
Valore canonico:
reference_video.string
Singolo audio di riferimento (percorso o URL). Utilizzato per la musica di sottofondo o come
riferimento vocale quando il provider supporta input audio.
string[]
Più audio di riferimento (fino a 3).
string[]
Indicazioni facoltative sul ruolo per posizione, parallele all’elenco combinato degli audio.
Valore canonico:
reference_audio.Le indicazioni sui ruoli vengono inoltrate al provider così come sono. I valori canonici provengono
dall’unione
VideoGenerationAssetRole, ma i provider possono accettare ulteriori
stringhe di ruolo. Gli array *Roles non devono contenere più voci del
corrispondente elenco di riferimenti; gli errori di una posizione generano un messaggio di errore chiaro.
Utilizzare una stringa vuota per lasciare una posizione non impostata. Per xAI, impostare ogni ruolo immagine su
reference_image per utilizzare la modalità di generazione reference_images; omettere il
ruolo oppure utilizzare first_frame per la conversione da immagine singola a video.Controlli dello stile
string
Indicazione delle proporzioni, ad esempio
1:1, 16:9, 9:16, adaptive o un valore specifico del provider. OpenClaw normalizza o ignora i valori non supportati in base al provider.string
Indicazione della risoluzione, ad esempio
360P, 480P, 540P, 720P, 768P, 1080P, 4K o un valore specifico del provider. OpenClaw normalizza o ignora i valori non supportati in base al provider.number
Durata desiderata in secondi (arrotondata al valore supportato dal provider più vicino).
string
Indicazione delle dimensioni quando il provider le supporta.
boolean
Abilita l’audio generato nell’output quando supportato. Distinto da
audioRef* (input).boolean
Attiva o disattiva la filigrana del provider quando supportata.
adaptive è un valore sentinella specifico del provider: viene inoltrato così com’è ai
provider che dichiarano adaptive nelle proprie funzionalità (ad esempio BytePlus
Seedance lo utilizza per rilevare automaticamente le proporzioni dalle dimensioni
dell’immagine di input). I provider che non lo dichiarano espongono il valore tramite
details.ignoredOverrides nel risultato dello strumento, rendendo visibile lo scarto.
Impostazioni avanzate
"generate" | "status" | "list"
predefinito:"generate"
"status" restituisce l’attività corrente della sessione; "list" esamina i provider.string
Sostituzione di provider/modello (ad esempio
runway/gen4.5).string
Indicazione del nome del file di output.
number
Timeout facoltativo dell’operazione del provider in millisecondi. Se omesso, OpenClaw utilizza
agents.defaults.videoGenerationModel.timeoutMs, se configurato; in caso contrario, utilizza il valore predefinito del provider definito dal plugin, se disponibile.object
Opzioni specifiche del provider sotto forma di oggetto JSON (ad esempio
{"seed": 42, "draft": true}).
I provider che dichiarano uno schema tipizzato convalidano le chiavi e i tipi; le chiavi
sconosciute o le incompatibilità fanno saltare il candidato durante il fallback. I provider privi di
uno schema dichiarato ricevono le opzioni così come sono. Eseguire video_generate action=list
per vedere quali opzioni accetta ciascun provider.Non tutti i provider supportano tutti i parametri. OpenClaw normalizza la durata al
valore supportato dal provider più vicino e rimappa le indicazioni geometriche convertite,
ad esempio dalle dimensioni alle proporzioni, quando un provider di fallback espone
un’interfaccia di controllo diversa. Le sostituzioni realmente non supportate vengono ignorate, ove possibile,
e segnalate come avvisi nel risultato dello strumento. I limiti rigidi delle funzionalità
(ad esempio un numero eccessivo di input di riferimento) causano un errore prima dell’invio. I risultati dello strumento
riportano le impostazioni applicate;
details.normalization registra qualsiasi
conversione dal valore richiesto a quello applicato.- Nessun contenuto multimediale di riferimento ->
generate - Qualsiasi immagine di riferimento ->
imageToVideo - Qualsiasi video di riferimento ->
videoToVideo - Gli input audio di riferimento non modificano la modalità risolta; vengono applicati
alla modalità selezionata dai riferimenti immagine/video e funzionano soltanto
con i provider che dichiarano
maxInputAudios.
Fallback e opzioni tipizzate
Alcuni controlli delle funzionalità vengono applicati al livello di fallback anziché al limite dello strumento; pertanto, una richiesta che supera i limiti del provider principale può comunque essere eseguita su un fallback compatibile:- Un candidato attivo che non dichiara
maxInputAudios(o dichiara0) viene saltato quando la richiesta contiene riferimenti audio; viene quindi provato il candidato successivo. La stessa protezione si applica al numero di riferimenti immagine e video rispetto amaxInputImages/maxInputVideos. - Un candidato attivo il cui
maxDurationSecondsè inferiore aldurationSecondsrichiesto e che non dichiara un elencosupportedDurationSecondsviene saltato. - Se la richiesta contiene
providerOptionse il candidato attivo dichiara esplicitamente uno schemaproviderOptionstipizzato, viene saltato se le chiavi fornite non sono incluse nello schema o se i tipi dei valori non corrispondono. I provider privi di uno schema dichiarato ricevono le opzioni così come sono (passaggio diretto compatibile con le versioni precedenti). Un provider può rifiutare tutte le opzioni specifiche del provider dichiarando uno schema vuoto (capabilities.providerOptions: {}), che determina lo stesso salto di un’incompatibilità di tipo.
warn, affinché gli operatori vedano quando
il provider principale è stato ignorato; i salti successivi vengono registrati al livello debug per
evitare rumore nelle lunghe catene di fallback. Se tutti i candidati vengono saltati,
l’errore aggregato include il motivo del salto per ciascuno di essi.
Azioni
Selezione del modello
OpenClaw risolve il modello nel seguente ordine:- Parametro dello strumento
model- se l’agente ne specifica uno nella chiamata. videoGenerationModel.primarydalla configurazione.videoGenerationModel.fallbacksnell’ordine specificato.- Rilevamento automatico - i provider con autenticazione valida, a partire dal provider predefinito corrente, seguiti dai provider rimanenti in ordine alfabetico.
agents.defaults.mediaGenerationAutoProviderFallback: false per utilizzare
soltanto le voci esplicite model, primary e fallbacks.
Note sui provider
Alibaba
Alibaba
Utilizza l’endpoint asincrono di DashScope / Model Studio. Le immagini e i
video di riferimento devono essere URL
http(s) remoti.BytePlus (1.0)
BytePlus (1.0)
ID provider:
byteplus.Modelli: seedance-1-0-pro-250528 (predefinito),
seedance-1-0-pro-t2v-250528, seedance-1-0-pro-fast-251015,
seedance-1-0-lite-t2v-250428, seedance-1-0-lite-i2v-250428.I modelli T2V (*-t2v-*) non accettano input immagine; i modelli I2V e
i modelli generici *-pro-* supportano una singola immagine di riferimento (primo
fotogramma). Passare l’immagine per posizione oppure impostare role: "first_frame".
Quando viene fornita un’immagine, gli ID dei modelli T2V vengono sostituiti automaticamente
con la variante I2V corrispondente.Chiavi providerOptions supportate: seed (numero), draft (booleano -
forza 480p), camera_fixed (booleano).BytePlus Seedance 1.5
BytePlus Seedance 1.5
Richiede il plugin
@openclaw/byteplus-modelark
(esterno, non incluso). ID provider: byteplus-seedance15. Modello:
seedance-1-5-pro-251215.Utilizza l’API unificata content[]. Supporta al massimo 2 immagini di input
(first_frame + last_frame). Tutti gli input devono essere URL https://
remoti. Impostare role: "first_frame" / "last_frame" su ogni immagine oppure
passare le immagini per posizione.aspectRatio: "adaptive" rileva automaticamente le proporzioni dall’immagine di input.
audio: true corrisponde a generate_audio. providerOptions.seed
(numero) viene inoltrato.BytePlus Seedance 2.0
BytePlus Seedance 2.0
Richiede il plugin
@openclaw/byteplus-modelark
(esterno, non incluso). ID provider: byteplus-seedance2. Modelli:
dreamina-seedance-2-0-260128,
dreamina-seedance-2-0-fast-260128.Utilizza l’API unificata content[]. Supporta fino a 9 immagini di riferimento,
3 video di riferimento e 3 audio di riferimento. Tutti gli input devono essere URL
https:// remoti. Impostare role su ogni risorsa; i valori supportati sono:
"first_frame", "last_frame", "reference_image",
"reference_video", "reference_audio".aspectRatio: "adaptive" rileva automaticamente le proporzioni dall’immagine di input.
audio: true corrisponde a generate_audio. providerOptions.seed
(numero) viene inoltrato.ComfyUI
ComfyUI
Esecuzione locale o nel cloud basata su flussi di lavoro. Supporta la
generazione da testo a video e da immagine a video tramite il grafo configurato.
fal
fal
Utilizza un flusso basato su coda per le operazioni di lunga durata. Per
impostazione predefinita, OpenClaw attende fino a 20 minuti prima di
considerare scaduta un’operazione nella coda fal ancora in corso. La maggior
parte dei modelli video fal accetta un singolo riferimento immagine. I
modelli Seedance 2.0 da riferimento a video accettano fino a 9 immagini,
3 video e 3 riferimenti audio, per un massimo complessivo di 12 file di
riferimento.
Google (Gemini / Veo)
Google (Gemini / Veo)
Supporta un riferimento costituito da un’immagine o da un video. Le richieste
di generazione audio vengono ignorate con un avviso nel percorso dell’API
Gemini, perché tale API rifiuta il parametro
generateAudio per l’attuale
generazione video Veo.MiniMax
MiniMax
È consentito un solo riferimento immagine. MiniMax accetta le risoluzioni
768P e 1080P; richieste come 720P vengono normalizzate al valore
supportato più vicino prima dell’invio.OpenAI
OpenAI
Viene inoltrata solo la sostituzione di
size. Le altre sostituzioni di stile
(aspectRatio, resolution, audio, watermark) vengono ignorate con
un avviso.OpenRouter
OpenRouter
Utilizza l’API asincrona
/videos di OpenRouter. OpenClaw invia
l’operazione, interroga periodicamente polling_url e scarica
unsigned_urls oppure l’endpoint documentato del contenuto dell’operazione.
Il modello predefinito incluso google/veo-3.1-fast dichiara durate di
4/6/8 secondi, risoluzioni 720P/1080P e proporzioni
16:9/9:16.Qwen
Qwen
Utilizza lo stesso backend DashScope di Alibaba. Gli input di riferimento
devono essere URL
http(s) remoti; i file locali vengono rifiutati
preventivamente.Runway
Runway
Supporta i file locali tramite URI di dati. La conversione da video a video
richiede
runway/gen4_aleph. Le esecuzioni basate solo su testo offrono
proporzioni 16:9 e 9:16.Together
Together
È consentito un solo riferimento immagine.
Vydra
Vydra
Utilizza direttamente
https://www.vydra.ai/api/v1 per evitare
reindirizzamenti che eliminano l’autenticazione. veo3 è incluso
esclusivamente per la generazione da testo a video; kling richiede
l’URL remoto di un’immagine.xAI
xAI
Il modello predefinito
grok-imagine-video supporta la generazione da testo
a video, da una singola immagine del primo fotogramma a video, fino a 7 input
reference_image tramite reference_images di xAI e flussi remoti di
modifica o estensione dei video. La generazione usa 480P per impostazione
predefinita; la generazione da una singola immagine a video eredita le
proporzioni della sorgente quando aspectRatio viene omesso. La modifica e
l’estensione dei video ereditano la geometria dell’input e non accettano
sostituzioni delle proporzioni o della risoluzione. L’estensione accetta
durate da 2 a 10 secondi.grok-imagine-video-1.5 supporta esclusivamente la generazione da immagine
a video: è necessario fornire esattamente un’immagine. Supporta durate da
1 a 15 secondi e risoluzioni 480P, 720P o 1080P, con 480P come
valore predefinito; omettere aspectRatio per ereditare le proporzioni
dell’immagine sorgente. Gli identificatori di anteprima e quelli datati
della versione 1.5 ricevono la stessa convalida e vengono inoltrati
invariati.Modalità delle funzionalità dei provider
Il contratto condiviso per la generazione video supporta funzionalità specifiche per modalità anziché soltanto limiti aggregati generali. Le nuove implementazioni dei provider dovrebbero preferire blocchi di modalità espliciti:maxInputImages e maxInputVideos
non sono sufficienti per dichiarare il supporto delle modalità di
trasformazione. I provider dovrebbero dichiarare esplicitamente generate,
imageToVideo e videoToVideo, affinché i test in ambiente reale, i test
del contratto e lo strumento condiviso video_generate possano convalidare
in modo deterministico il supporto delle modalità.
Quando un modello di un provider supporta un numero di input di riferimento
maggiore rispetto agli altri, utilizzare maxInputImagesByModel,
maxInputVideosByModel o maxInputAudiosByModel anziché aumentare il limite
dell’intera modalità.
Test in ambiente reale
Copertura in ambiente reale facoltativa per i provider condivisi inclusi:generateper ogni provider diverso da FAL incluso nell’esecuzione.- Prompt di un’aragosta della durata di un secondo.
- Limite temporale per operazione e per provider definito da
OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS(180000per impostazione predefinita).
OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 per eseguire anche le
modalità di trasformazione dichiarate che l’esecuzione condivisa può verificare
in sicurezza con contenuti multimediali locali:
imageToVideoquandocapabilities.imageToVideo.enabled.videoToVideoquandocapabilities.videoToVideo.enablede il provider/modello accetta, nell’esecuzione condivisa, un input video locale basato su buffer.
videoToVideo
copre solo runway quando viene selezionato runway/gen4_aleph.
Configurazione
Impostare il modello predefinito di generazione video nella configurazione di OpenClaw:Argomenti correlati
- Alibaba Model Studio
- Attività in background - monitoraggio delle attività per la generazione video asincrona
- BytePlus
- ComfyUI
- Riferimento della configurazione
- fal
- Google (Gemini)
- MiniMax
- Modelli
- OpenAI
- Qwen
- Runway
- Together AI
- Panoramica degli strumenti
- Vydra
- xAI