video_generate. Se admiten dieciséis backends de proveedores;
el agente elige automáticamente el adecuado según la configuración y
las claves de API disponibles.
video_generate solo aparece cuando hay al menos un proveedor de generación de video
disponible. Si no aparece entre las herramientas del agente, establezca una clave de API de proveedor o
configure agents.defaults.mediaModels.video.video_generate tiene tres modos de ejecución, que se determinan a partir de las entradas de referencia
de la llamada:
generate- sin contenido multimedia de referencia (texto a video).imageToVideo- una o más imágenes de referencia.videoToVideo- uno o más videos de referencia.
action=list.
Inicio rápido
1
Configurar la autenticación
Establezca una clave de API para cualquier proveedor compatible:
2
Elegir un modelo predeterminado (opcional)
3
Solicitarlo al agente
Genera un video cinematográfico de 5 segundos de una langosta amistosa surfeando al atardecer.El agente llama automáticamente a
video_generate. No es necesario incluir la herramienta
en una lista de permitidas.Cómo funciona la generación asíncrona
La generación de video es asíncrona:- OpenClaw envía la solicitud al proveedor y devuelve inmediatamente un id de tarea.
- El proveedor procesa el trabajo en segundo plano (normalmente entre 30 segundos y varios minutos, según el proveedor y la resolución; los proveedores lentos respaldados por colas pueden ejecutarse hasta el tiempo de espera configurado).
- Cuando el video está listo, OpenClaw reactiva la misma sesión con un evento interno de finalización.
- El agente informa de ello mediante el modo normal de respuesta visible de la sesión:
respuesta final automática, o
message(action="send")cuando la sesión requiere la herramienta de mensajes. Si la sesión solicitante está inactiva, o falla su reactivación y el contenido multimedia generado sigue sin aparecer en la respuesta de finalización, OpenClaw envía directamente un mensaje alternativo idempotente con el contenido multimedia.
video_generate en la misma
sesión devuelven el estado actual de la tarea en lugar de iniciar otra
generación. Use action: "status" para consultarlo sin activar una nueva
generación, o openclaw tasks list / openclaw tasks show <lookup> desde la
CLI (consulte Tareas en segundo plano).
Fuera de las ejecuciones de agentes respaldadas por sesiones (por ejemplo, invocaciones directas de herramientas),
la herramienta recurre a la generación en línea y devuelve la ruta final del contenido multimedia
en el mismo turno.
Los archivos de video generados se guardan en el almacenamiento multimedia administrado por OpenClaw cuando el
proveedor devuelve bytes. El límite predeterminado es de 16MB (el límite compartido de contenido multimedia
de video); agents.defaults.mediaMaxMb lo aumenta para renderizaciones más grandes. Cuando un
proveedor también devuelve una URL de salida alojada, OpenClaw entrega esa URL en lugar
de marcar la tarea como fallida si la persistencia local rechaza un archivo demasiado grande.
Ciclo de vida de la tarea
Consulte el estado desde la CLI:
Proveedores compatibles
Algunos proveedores aceptan variables de entorno de claves de API adicionales o alternativas. Consulte
las páginas de los proveedores individuales para obtener más detalles.
Ejecute
video_generate action=list para inspeccionar en tiempo de ejecución los proveedores, modelos y
modos de ejecución disponibles.
Matriz de capacidades
El contrato de modos explícito que usanvideo_generate, las pruebas de contrato y
el barrido en vivo compartido:
Parámetros de la herramienta
Obligatorios
string
requerido
Descripción textual del vídeo que se va a generar. Obligatoria para
action: "generate".Entradas de contenido
string
Una imagen de referencia (ruta o URL).
string[]
Varias imágenes de referencia (hasta 9).
string[]
Indicaciones opcionales de roles por posición, paralelas a la lista combinada de imágenes.
Valores canónicos:
first_frame, last_frame, reference_image.string
Un vídeo de referencia (ruta o URL).
string[]
Varios vídeos de referencia (hasta 4).
string[]
Indicaciones opcionales de roles por posición, paralelas a la lista combinada de vídeos.
Valor canónico:
reference_video.string
Un audio de referencia (ruta o URL). Se utiliza como música de fondo o
referencia de voz cuando el proveedor admite entradas de audio.
string[]
Varios audios de referencia (hasta 3).
string[]
Indicaciones opcionales de roles por posición, paralelas a la lista combinada de audios.
Valor canónico:
reference_audio.Las indicaciones de roles se reenvían al proveedor sin modificaciones. Los valores canónicos proceden de
la unión
VideoGenerationAssetRole, pero los proveedores pueden aceptar cadenas de
roles adicionales. Las matrices *Roles no deben tener más entradas que la
lista de referencias correspondiente; los errores de desfase de una posición producen un error claro.
Use una cadena vacía para dejar una posición sin definir. Para xAI, establezca todos los roles de imagen en
reference_image para usar su modo de generación reference_images; omita el
rol o use first_frame para convertir una sola imagen en vídeo.Controles de estilo
string
Indicación de relación de aspecto como
1:1, 16:9, 9:16, adaptive o un valor específico del proveedor. OpenClaw normaliza o ignora los valores no admitidos según el proveedor.string
Indicación de resolución como
360P, 480P, 540P, 720P, 768P, 1080P, 4K o un valor específico del proveedor. OpenClaw normaliza o ignora los valores no admitidos según el proveedor.number
Duración objetivo en segundos (redondeada al valor más cercano admitido por el proveedor).
string
Indicación de tamaño cuando el proveedor la admite.
boolean
Activa el audio generado en la salida cuando se admite. Es distinto de
audioRef* (entradas).boolean
Activa o desactiva la marca de agua del proveedor cuando se admite.
adaptive es un valor centinela específico del proveedor: se reenvía sin modificaciones a
los proveedores que declaran adaptive en sus capacidades (por ejemplo, BytePlus
Seedance lo utiliza para detectar automáticamente la relación a partir de las dimensiones
de la imagen de entrada). Los proveedores que no lo declaran muestran el valor mediante
details.ignoredOverrides en el resultado de la herramienta para que la omisión sea visible.
Opciones avanzadas
"generate" | "status" | "list"
predeterminado:"generate"
"status" devuelve la tarea de la sesión actual; "list" inspecciona los proveedores.string
Sustitución del proveedor/modelo (por ejemplo,
runway/gen4.5).string
Indicación del nombre del archivo de salida.
number
Tiempo de espera opcional para la operación del proveedor, en milisegundos. Si se omite, OpenClaw usa
agents.defaults.mediaModels.video.timeoutMs si está configurado; de lo contrario, usa el valor predeterminado definido por el autor del plugin del proveedor, cuando exista.object
Opciones específicas del proveedor como objeto JSON (por ejemplo,
{"seed": 42, "draft": true}).
Los proveedores que declaran un esquema tipado validan las claves y los tipos; las claves
desconocidas o las discrepancias hacen que se omita el candidato durante la conmutación por error. Los proveedores sin un
esquema declarado reciben las opciones sin modificaciones. Ejecute video_generate action=list
para consultar qué acepta cada proveedor.No todos los proveedores admiten todos los parámetros. OpenClaw normaliza la duración al
valor admitido más cercano por el proveedor y reasigna las indicaciones geométricas traducidas,
como la conversión de tamaño a relación de aspecto, cuando un proveedor alternativo ofrece una
superficie de control diferente. Las sustituciones realmente no admitidas se ignoran aplicando el
máximo esfuerzo posible y se notifican como advertencias en el resultado de la herramienta. Los límites estrictos de capacidad
(como un exceso de entradas de referencia) producen un error antes del envío. Los resultados de la herramienta
informan de la configuración aplicada;
details.normalization registra cualquier
traducción entre lo solicitado y lo aplicado.- Sin medios de referencia ->
generate - Cualquier referencia de imagen ->
imageToVideo - Cualquier referencia de vídeo ->
videoToVideo - Las entradas de audio de referencia no cambian el modo resuelto; se aplican
sobre el modo seleccionado por las referencias de imagen o vídeo y solo funcionan
con proveedores que declaran
maxInputAudios.
Conmutación por error y opciones tipadas
Algunas comprobaciones de capacidad se aplican en la capa de conmutación por error, en lugar de en el límite de la herramienta, por lo que una solicitud que supere los límites del proveedor principal aún puede ejecutarse en un proveedor alternativo que tenga la capacidad necesaria:- El candidato activo que no declare
maxInputAudios(o0) se omite cuando la solicitud contiene referencias de audio; se prueba el siguiente candidato. La misma protección se aplica a los recuentos de referencias de imagen y vídeo en relación conmaxInputImages/maxInputVideos. - Si el
maxDurationSecondsdel candidato activo es inferior aldurationSecondssolicitado y no hay una listasupportedDurationSecondsdeclarada, se omite. - Si la solicitud contiene
providerOptionsy el candidato activo declara explícitamente un esquema tipadoproviderOptions, se omite si las claves proporcionadas no están en el esquema o si los tipos de los valores no coinciden. Los proveedores sin un esquema declarado reciben las opciones sin modificaciones (transferencia compatible con versiones anteriores). Un proveedor puede rechazar todas las opciones del proveedor declarando un esquema vacío (capabilities.providerOptions: {}), lo que provoca la misma omisión que una discrepancia de tipos.
warn para que los operadores sepan cuándo
se ha descartado su proveedor principal; las omisiones posteriores se registran en debug para
evitar ruido en cadenas largas de conmutación por error. Si se omiten todos los candidatos, el
error agregado incluye el motivo de omisión de cada uno.
Acciones
Selección del modelo
OpenClaw resuelve el modelo en este orden:- Parámetro de herramienta
model: si el agente especifica uno en la llamada. videoGenerationModel.primaryde la configuración.videoGenerationModel.fallbacksen orden.- Detección automática: proveedores que tienen una autenticación válida, comenzando por el proveedor predeterminado actual y, después, los proveedores restantes en orden alfabético.
model sigue siendo determinante.
Notas sobre proveedores
Alibaba
Alibaba
Utiliza el endpoint asíncrono de DashScope / Model Studio. Las imágenes y los
vídeos de referencia deben ser URL
http(s) remotas.BytePlus (incluido)
BytePlus (incluido)
Id. del proveedor:
byteplus.Modelos: seedance-1-0-pro-250528 (predeterminado),
seedance-1-5-pro-251215.Utiliza la API unificada content[]. Admite hasta 2 imágenes de entrada
(first_frame + last_frame). Pase las imágenes por posición o establezca explícitamente
el valor role de cada imagen.Claves providerOptions admitidas: seed (número), draft (booleano:
fuerza 480p), camera_fixed (booleano).Plugin BytePlus Seedance 1.5
Plugin BytePlus Seedance 1.5
Requiere el plugin
@openclaw/byteplus-modelark
(externo, no incluido). Id. del proveedor: byteplus-seedance15. Modelo:
seedance-1-5-pro-251215.Utiliza la API unificada content[]. Admite como máximo 2 imágenes de entrada
(first_frame + last_frame). Todas las entradas deben ser URL https://
remotas. Establezca role: "first_frame" / "last_frame" en cada imagen o
pase las imágenes por posición.aspectRatio: "adaptive" detecta automáticamente la relación a partir de la imagen de entrada.
audio: true se asigna a generate_audio. providerOptions.seed
(número) se reenvía.BytePlus Seedance 2.0
BytePlus Seedance 2.0
Requiere el plugin
@openclaw/byteplus-modelark
(externo, no incluido). Id. del proveedor: byteplus-seedance2. Modelos:
dreamina-seedance-2-0-260128,
dreamina-seedance-2-0-fast-260128.Utiliza la API unificada content[]. Admite hasta 9 imágenes de referencia,
3 vídeos de referencia y 3 audios de referencia. Todas las entradas deben ser URL
https:// remotas. Establezca role en cada recurso; valores admitidos:
"first_frame", "last_frame", "reference_image",
"reference_video", "reference_audio".aspectRatio: "adaptive" detecta automáticamente la relación a partir de la imagen de entrada.
audio: true se asigna a generate_audio. providerOptions.seed
(número) se reenvía.ComfyUI
ComfyUI
Ejecución local o en la nube basada en flujos de trabajo. Admite texto a vídeo y
de imagen a vídeo mediante el grafo configurado.
fal
fal
Utiliza un flujo respaldado por una cola para tareas de larga duración. OpenClaw espera hasta 20
minutos de forma predeterminada antes de considerar que una tarea en curso de la cola de fal ha
agotado el tiempo de espera. La mayoría de los modelos de vídeo de fal
aceptan una única referencia de imagen. Los modelos de referencia a vídeo
Seedance 2.0 aceptan hasta 9 imágenes, 3 vídeos y 3 referencias de audio, con
un máximo de 12 archivos de referencia en total.
Google (Gemini / Veo)
Google (Gemini / Veo)
Admite una referencia de imagen o de vídeo. Las solicitudes de audio generado se
ignoran con una advertencia en la ruta de la API de Gemini porque esa API rechaza
el parámetro
generateAudio para la generación de vídeo actual de Veo.MiniMax
MiniMax
Solo una referencia de imagen. MiniMax acepta las resoluciones
768P y 1080P;
las solicitudes como 720P se normalizan al valor compatible más
cercano antes del envío.OpenAI
OpenAI
Solo se reenvía la anulación
size. Las demás anulaciones de estilo
(aspectRatio, resolution, audio, watermark) se ignoran con
una advertencia.OpenRouter
OpenRouter
Utiliza la API asíncrona
/videos de OpenRouter. OpenClaw envía la
tarea, consulta periódicamente polling_url y descarga unsigned_urls o el
endpoint de contenido de la tarea documentado. El valor predeterminado incluido google/veo-3.1-fast
anuncia duraciones de 4/6/8 segundos, resoluciones 720P/1080P y
relaciones de aspecto 16:9/9:16.Qwen
Qwen
El mismo backend de DashScope que Alibaba. Las entradas de referencia deben ser URL
http(s) remotas; los archivos locales se rechazan de antemano.Runway
Runway
Admite archivos locales mediante URI de datos. La conversión de vídeo a vídeo requiere
runway/gen4_aleph. Las ejecuciones solo de texto ofrecen las relaciones de
aspecto 16:9 y 9:16.Together
Together
Solo una referencia de imagen.
Vydra
Vydra
Utiliza
https://www.vydra.ai/api/v1 directamente para evitar redirecciones que
descartan la autenticación. veo3 se incluye únicamente para texto a vídeo; kling requiere
una URL de imagen remota.xAI
xAI
El modelo predeterminado
grok-imagine-video admite texto a vídeo, conversión de
una única imagen de primer fotograma a vídeo, hasta 7 entradas reference_image mediante
reference_images de xAI y flujos remotos de edición/extensión de vídeo. La generación usa de forma
predeterminada 480P; la conversión de una única imagen a vídeo hereda la proporción de origen cuando
se omite aspectRatio. La edición/extensión de vídeo hereda la geometría de entrada y
no acepta anulaciones de relación de aspecto ni de resolución. La extensión acepta entre 2 y 10
segundos.grok-imagine-video-1.5 es únicamente de imagen a vídeo: proporcione exactamente una imagen.
Admite entre 1 y 15 segundos y 480P, 720P o 1080P, con
480P como valor predeterminado; omita aspectRatio para heredar la proporción de la imagen de origen. Los identificadores
de vista previa y 1.5 con fecha reciben la misma validación y se reenvían
sin cambios.Modos de capacidad del proveedor
El contrato compartido de generación de vídeo admite capacidades específicas por modo en lugar de únicamente límites agregados planos. Las nuevas implementaciones de proveedores deben preferir bloques de modo explícitos:maxInputImages y maxInputVideos
no bastan para anunciar compatibilidad con modos de transformación. Los proveedores deben
declarar generate, imageToVideo y videoToVideo explícitamente para que las
pruebas en vivo, las pruebas de contrato y la herramienta compartida video_generate puedan validar
la compatibilidad de modos de forma determinista.
Cuando un modelo de un proveedor admita más entradas de referencia que los
demás, utilice maxInputImagesByModel, maxInputVideosByModel o
maxInputAudiosByModel en lugar de elevar el límite de todo el modo.
Pruebas en vivo
Cobertura en vivo opcional para los proveedores compartidos incluidos:generatepara cada proveedor que no sea FAL en el barrido.- Prompt de langosta de un segundo.
- Límite de operaciones por proveedor de
OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS(180000de forma predeterminada).
OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 para ejecutar también los modos de
transformación declarados que el barrido compartido puede ejercitar de forma segura con medios locales:
imageToVideocuandocapabilities.imageToVideo.enabled.videoToVideocuandocapabilities.videoToVideo.enabledy el proveedor/modelo acepte entrada de vídeo local respaldada por búfer en el barrido compartido.
videoToVideo cubre runway solo cuando se
selecciona runway/gen4_aleph.
Configuración
Establezca el modelo predeterminado de generación de vídeo en la configuración de OpenClaw:Relacionado
- Alibaba Model Studio
- Tareas en segundo plano - seguimiento de tareas para la generación asíncrona de vídeo
- BytePlus
- ComfyUI
- Referencia de configuración
- fal
- Google (Gemini)
- MiniMax
- Modelos
- OpenAI
- Qwen
- Runway
- Together AI
- Descripción general de las herramientas
- Vydra
- xAI