Generación de videos

Los agentes de OpenClaw pueden generar vídeos a partir de indicaciones de texto, imágenes de referencia o vídeos existentes. Se admiten dieciséis proveedores de backend, cada uno con diferentes opciones de modelo, modos de entrada y conjuntos de funciones. El agente selecciona automáticamente el proveedor adecuado según su configuración y las claves de API disponibles.

Note

La herramienta

video_generate

solo aparece cuando hay al menos un proveedor de generación de vídeo disponible. Si no la ve en sus herramientas de agente, configure una clave de API de proveedor o configure

agents.defaults.videoGenerationModel

.

OpenClaw trata la generación de video como tres modos de tiempo de ejecución:

• generate: solicitudes de texto a vídeo sin medios de referencia.
• imageToVideo: la solicitud incluye una o más imágenes de referencia.
• videoToVideo: la solicitud incluye uno o más vídeos de referencia.

Los proveedores pueden admitir cualquier subconjunto de esos modos. La herramienta valida el modo activo antes del envío e informa de los modos admitidos en action=list.

Inicio rápido

1. Configurar autenticación

   Establezca una clave de API para cualquier proveedor admitido:

   export GEMINI_API_KEY="your-key"

2. Elegir un modelo predeterminado (opcional)

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

3. Pídele al agente

   Genera un vídeo cinematográfico de 5 segundos de una langosta amigable surfeando al atardecer.

   El agente llama a video_generate automáticamente. No se necesita permitir la herramienta.

Cómo funciona la generación asíncrona

La generación de vídeo es asíncrona. Cuando el agente llama a video_generate en una sesión:

1. OpenClaw envía la solicitud al proveedor y devuelve inmediatamente un id de tarea.
2. El proveedor procesa el trabajo en segundo plano (generalmente de 30 segundos a varios minutos, dependiendo del proveedor y la resolución; los proveedores lentos con cola pueden ejecutarse hasta el tiempo de espera configurado).
3. Cuando el video está listo, OpenClaw reactiva la misma sesión con un evento interno de finalización.
4. El agente informa al usuario a través del modo de respuesta visible normal de la sesión: entrega de la respuesta final cuando es automática, o message(action="send") cuando la sesión requiere la herramienta de mensaje. Si la sesión solicitante está inactiva o falla su activación activa, y algún video generado aún falta en la respuesta de finalización, OpenClaw envía una alternativa directa idempotente con solo el video que falta.

Mientras un trabajo está en proceso, las llamadas duplicadas a video_generate en la misma sesión devuelven el estado actual de la tarea en lugar de iniciar otra generación. Use openclaw tasks list o openclaw tasks show <taskId> para verificar el progreso desde la CLI.

Fuera de las ejecuciones del agente respaldadas por sesión (por ejemplo, invocaciones directas de herramientas), la herramienta recurre a la generación en línea y devuelve la ruta de medios final en el mismo turno.

Los archivos de video generados se guardan en el almacenamiento de medios gestionado por OpenClaw cuando el proveedor devuelve bytes. El límite de guardado predeterminado de videos generados sigue el límite de medios de video, y agents.defaults.mediaMaxMb lo aumenta para renders más grandes. Cuando un proveedor también devuelve una URL de salida alojada, OpenClaw puede entregar esa URL en lugar de fallar la tarea si la persistencia local rechaza un archivo demasiado grande.

Ciclo de vida de la tarea

Estado	Significado
queued	Tarea creada, esperando a que el proveedor la acepte.
running	El proveedor está procesando (típicamente de 30 segundos a varios minutos dependiendo del proveedor y la resolución).
succeeded	Video listo; el agente se despierta y lo publica en la conversación.
failed	Error o tiempo de espera del proveedor; el agente se despierta con detalles del error.

Verificar el estado desde la CLI:

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

Si una tarea de video ya está queued o running para la sesión actual, video_generate devuelve el estado de la tarea existente en lugar de iniciar una nueva. Use action: "status" para verificar explícitamente sin activar una nueva generación.

Proveedores compatibles

Proveedor	Modelo predeterminado	Texto	Ref. de imagen	Ref. de video	Autenticación
Alibaba	wan2.6-t2v	✓	Sí (URL remota)	Sí (URL remota)	MODELSTUDIO_API_KEY
BytePlus (1.0)	seedance-1-0-pro-250528	✓	Hasta 2 imágenes (solo modelos I2V; primer + último fotograma)	-	BYTEPLUS_API_KEY
BytePlus Seedance 1.5	seedance-1-5-pro-251215	✓	Hasta 2 imágenes (primer + último fotograma a través del rol)	-	BYTEPLUS_API_KEY
BytePlus Seedance 2.0	dreamina-seedance-2-0-260128	✓	Hasta 9 imágenes de referencia	Hasta 3 videos	BYTEPLUS_API_KEY
ComfyUI	workflow	✓	1 imagen	-	COMFY_API_KEY o COMFY_CLOUD_API_KEY
DeepInfra	Pixverse/Pixverse-T2V	✓	-	-	DEEPINFRA_API_KEY
fal	fal-ai/minimax/video-01-live	✓	1 imagen; hasta 9 con Seedance referencia-a-video	Hasta 3 videos con Seedance referencia-a-video	FAL_KEY
Google	veo-3.1-fast-generate-preview	✓	1 imagen	1 video	GEMINI_API_KEY
MiniMax	MiniMax-Hailuo-2.3	✓	1 imagen	-	MINIMAX_API_KEY u OAuth de MiniMax
OpenAI	sora-2	✓	1 imagen	1 video	OPENAI_API_KEY
OpenRouter	google/veo-3.1-fast	✓	Hasta 4 imágenes (primer/último fotograma o referencias)	-	OPENROUTER_API_KEY
Qwen	wan2.6-t2v	✓	Sí (URL remota)	Sí (URL remota)	QWEN_API_KEY
Runway	gen4.5	✓	1 imagen	1 video	RUNWAYML_API_SECRET
Together	Wan-AI/Wan2.2-T2V-A14B	✓	Wan-AI/Wan2.2-I2V-A14B solo	-	TOGETHER_API_KEY
Vydra	veo3	✓	1 imagen (kling)	-	VYDRA_API_KEY
xAI	grok-imagine-video	✓	1 imagen del primer fotograma o hasta a 7 reference_images	1 vídeo	XAI_API_KEY

Algunos proveedores aceptan variables de entorno de clave de API adicionales o alternativas. Consulte las páginas del proveedor individuales para obtener más detalles.

Ejecute video_generate action=list para inspeccionar los proveedores disponibles, los modelos y los modos de ejecución en tiempo de ejecución.

Matriz de capacidades

El contrato de modo explícito utilizado por video_generate, las pruebas de contrato y el barrido en vivo compartido:

Proveedor	generate	imageToVideo	videoToVideo	Carriles compartidos en vivo hoy
Alibaba	✓	✓	✓	generate, imageToVideo; videoToVideo omitido porque este proveedor necesita URLs de video http(s) remotas
BytePlus	✓	✓	-	generate, imageToVideo
ComfyUI	✓	✓	-	No está en el barrido compartido; la cobertura específica del flujo de trabajo reside con las pruebas de Comfy
DeepInfra	✓	-	-	generate; los esquemas de video nativos de DeepInfra son de texto a video en el contrato incluido
fal	✓	✓	✓	generate, imageToVideo; videoToVideo solo cuando se usa referencia a video de Seedance
Google	✓	✓	✓	generate, imageToVideo; videoToVideo compartido omitido porque el barrido Gemini/Veo con respaldo en búfer actual no acepta esa entrada
MiniMax	✓	✓	-	generate, imageToVideo
OpenAI	✓	✓	✓	generate, imageToVideo; videoToVideo compartido omitido porque esta ruta de organización/entrada actualmente necesita acceso de edición de video del lado del proveedor
OpenRouter	✓	✓	-	generate, imageToVideo
Qwen	✓	✓	✓	generate, imageToVideo; videoToVideo omitido porque este proveedor necesita http(s) de video remotas
Runway	✓	✓	✓	generate, imageToVideo; videoToVideo se ejecuta solo cuando el modelo seleccionado es runway/gen4_aleph
Together	✓	✓	-	generate, imageToVideo
Vydra	✓	✓	-	generate; imageToVideo compartido omitido porque veo3 incluido es solo de texto y kling incluido requiere una URL de imagen remota
xAI	✓	✓	✓	generate, imageToVideo; videoToVideo omitido porque este proveedor actualmente necesita una URL MP4 remota

Parámetros de la herramienta

Obligatorio

Descripción de texto del video a generar. Obligatorio para `action: "generate"`.

Entradas de contenido

Imagen de referencia única (ruta o URL). Múltiples imágenes de referencia (hasta 9). Sugerencias opcionales de rol por posición en paralelo a la lista de imágenes combinada. Valores canónicos: `first_frame`, `last_frame`, `reference_image`. Video de referencia único (ruta o URL). Múltiples videos de referencia (hasta 4). Sugerencias opcionales de rol por posición en paralelo a la lista de videos combinada. Valor canónico: `reference_video`. Audio de referencia único (ruta o URL). Se utiliza como música de fondo o referencia de voz cuando el proveedor admite entradas de audio. Múltiples audios de referencia (hasta 3). Sugerencias opcionales de rol por posición en paralelo a la lista de audios combinada. Valor canónico: `reference_audio`.

Note

Las sugerencias de rol se reenvían al proveedor tal cual. Los valores canónicos provienen de la unión VideoGenerationAssetRole pero los proveedores pueden aceptar cadenas de rol adicionales. Los arrays *Roles no deben tener más entradas que la lista de referencia correspondiente; los errores de uno por uno fallan con un error claro. Use una cadena vacía para dejar un espacio sin establecer. Para xAI, configure cada rol de imagen en reference_image para usar su modo de generación reference_images; omita el rol o use first_frame para imagen a video de imagen única.

Controles de estilo

Sugerencia 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 compatibles según el proveedor. Sugerencia de resolución, como `480P`, `720P`, `768P`, `1080P`, `4K` o un valor específico del proveedor. OpenClaw normaliza o ignora los valores no compatibles según el proveedor. Duración objetivo en segundos (redondeada al valor compatible más cercano del proveedor). Sugerencia de tamaño cuando el proveedor lo admite. Habilitar el audio generado en la salida cuando se admite. Distinto de `audioRef*` (entradas). Activar o desactivar la marca de agua del proveedor cuando se admite.

adaptive es un valor centinela específico del proveedor: se reenvía tal cual a los proveedores que declaran adaptive en sus capacidades (p. ej., BytePlus Seedance lo usa para detectar automáticamente la relación de aspecto a partir de las dimensiones de la imagen de entrada). Los proveedores que no lo declaran muestran el valor a través de details.ignoredOverrides en el resultado de la herramienta para que la omisión sea visible.

Avanzado

`"status"` devuelve la tarea de la sesión actual; `"list"` inspecciona los proveedores. Sobrescritura de proveedor/modelo (p. ej., `runway/gen4.5`). Sugerencia de nombre de archivo de salida. Tiempo de espera opcional de la operación del proveedor en milisegundos. Cuando se omite, OpenClaw usa `agents.defaults.videoGenerationModel.timeoutMs` si está configurado; de lo contrario, usa el valor predeterminado del proveedor definido por el complemento cuando existe uno. Opciones específicas del proveedor como un objeto JSON (p. ej., `{"seed": 42, "draft": true}`). Los proveedores que declaran un esquema con tipos validan las claves y los tipos; las claves desconocidas o discordancias omiten el candidato durante la conmutación por error. Los proveedores sin un esquema declarado reciben las opciones tal como son. Ejecute `video_generate action=list` para ver qué acepta cada proveedor.

Note

No todos los proveedores admiten todos los parámetros. OpenClaw normaliza la duración al valor más cercano admitido por el proveedor y reasigna las sugerencias de geometría traducidas tales como tamaño a relación de aspecto cuando un proveedor de conmutación por error expone una superficie de control diferente. Las sobrescrituras realmente no admitidas se ignoran en la medida de lo posible y se reportan como advertencias en el resultado de la herramienta. Los límites estrictos de capacidad (como demasiadas entradas de referencia) fallan antes del envío. Los resultados de la herramienta reportan la configuración aplicada; details.normalization captura cualquier traducción de solicitado a aplicado.

Las entradas de referencia seleccionan el modo de tiempo de ejecución:

• Sin medios de referencia → generate
• Cualquier referencia de imagen → imageToVideo
• Cualquier referencia de video → videoToVideo
• Las entradas de audio de referencia no cambian el modo resuelto; se aplican sobre cualquier modo que seleccionen las referencias de imagen/video y solo funcionan con proveedores que declaran maxInputAudios.

Las referencias mixtas de imagen y video no son una superficie de capacidad compartida estable. Prefiera un tipo de referencia por solicitud.

Reserva y opciones tipadas

Algunas comprobaciones de capacidades se aplican en la capa de reserva (fallback) en lugar de en el límite de la herramienta, por lo que una solicitud que exceda los límites del proveedor principal aún puede ejecutarse en una reserva capaz:

• Se omite el candidato activo que declara no tener maxInputAudios (o 0) cuando la solicitud contiene referencias de audio; se prueba el siguiente candidato.
• El maxDurationSeconds del candidato activo por debajo del durationSeconds solicitado sin una lista declarada de supportedDurationSeconds → omitido.
• La solicitud contiene providerOptions y el candidato activo declara explícitamente un esquema providerOptions tipado → se omite si las claves proporcionadas no están en el esquema o si los tipos de valor no coinciden. Los proveedores sin un esquema declarado reciben las opciones tal cual (transferencia compatible con versiones anteriores). Un proveedor puede optar por no recibir ninguna opción de proveedor declarando un esquema vacío (capabilities.providerOptions: {}), lo que provoca la misma omisión que una discordancia de tipos.

El primer motivo de omisión en una solicitud se registra en warn para que los operadores vean cuándo se saltó su proveedor principal; las omisiones posteriores se registran en debug para mantener silenciosas las cadenas de retroceso largas. Si se omite todos los candidatos, el error agregado incluye el motivo de omisión de cada uno.

Acciones

Acción	Lo que hace
generate	Predeterminado. Crea un video a partir del mensaje dado y entradas de referencia opcionales.
status	Comprueba el estado de la tarea de video en curso para la sesión actual sin iniciar otra generación.
list	Muestra los proveedores disponibles, los modelos y sus capacidades.

Selección de modelo

OpenClaw resuelve el modelo en este orden:

1. parámetro de herramienta model - si el agente especifica uno en la llamada.
2. videoGenerationModel.primary de la configuración.
3. videoGenerationModel.fallbacks en orden.
4. Detección automática - proveedores que tienen autenticación válida, comenzando por el proveedor predeterminado actual, luego los proveedores restantes en orden alfabético.

Si un proveedor falla, se prueba automáticamente el siguiente candidato. Si fallan todos los candidatos, el error incluye detalles de cada intento.

Establezca agents.defaults.mediaGenerationAutoProviderFallback: false para usar solo las entradas explícitas model, primary y fallbacks.

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
      },
    },
  },
}

Notas del proveedor

Alibaba

Utiliza el endpoint asíncrono de DashScope / Model Studio. Las imágenes y videos de referencia deben ser URLs http(s) remotas.

BytePlus (1.0)

Id. de proveedor: byteplus.

Modelos: seedance-1-0-pro-250528 (predeterminado), seedance-1-0-pro-t2v-250528, seedance-1-0-pro-fast-251015, seedance-1-0-lite-t2v-250428, seedance-1-0-lite-i2v-250428.

Los modelos T2V (*-t2v-*) no aceptan entradas de imagen; los modelos I2V y los modelos *-pro-* generales admiten una única imagen de referencia (primer fotograma). Pase la imagen posicionalmente o configure role: "first_frame". Los IDs de modelos T2V se cambian automáticamente a la variante I2V correspondiente cuando se proporciona una imagen.

Claves providerOptions compatibles: seed (número), draft (booleano - fuerza 480p), camera_fixed (booleano).

BytePlus Seedance 1.5

Requiere el complemento @openclaw/byteplus-modelark. Id. de proveedor: byteplus-seedance15. Modelo: seedance-1-5-pro-251215.

Utiliza la API unificada de content[]. Admite un máximo de 2 imágenes de entrada (first_frame + last_frame). Todas las entradas deben ser URLs https:// remotas. Configure role: "first_frame" / "last_frame" en cada imagen, o pase imágenes posicionalmente.

aspectRatio: "adaptive" detecta automáticamente la relación de aspecto de la imagen de entrada. audio: true se asigna a generate_audio. providerOptions.seed (número) se reenvía.

BytePlus Seedance 2.0

Requiere el plugin @openclaw/byteplus-modelark. 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 videos de referencia y 3 audios de referencia. Todas las entradas deben ser URLs https:// remotas. Establezca role en cada activo; valores admitidos: "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio".

aspectRatio: "adaptive" detecta automáticamente la proporción desde la imagen de entrada. audio: true se asigna a generate_audio. providerOptions.seed (número) se reenvía.

ComfyUI

Ejecución local o en la nube impulsada por flujos de trabajo. Admite texto a video y imagen a video a través del gráfico configurado.

fal

Utiliza un flujo con respaldo de cola para trabajos de larga duración. OpenClaw espera hasta 20 minutos de forma predeterminada antes de tratar un trabajo en cola fal en curso como agotado por tiempo. La mayoría de los modelos de video de fal aceptan una sola referencia de imagen. Los modelos de video de referencia a video de Seedance 2.0 aceptan hasta 9 imágenes, 3 videos y 3 referencias de audio, con un máximo de 12 archivos de referencia en total.

Google (Gemini / Veo)

Admite una imagen o un video de referencia. 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 video Veo actual.

MiniMax

Solo referencia de imagen única. MiniMax acepta 768P y 1080P resoluciones; las solicitudes como 720P se normalizan al valor admitido más cercano antes del envío.

OpenAI

Solo se reenvía la anulación size. Otras anulaciones de estilo (aspectRatio, resolution, audio, watermark) se ignoran con una advertencia.

OpenRouter

Utiliza la API asíncrona /videos de OpenRouter. OpenClaw envía el trabajo, sondea polling_url y descarga unsigned_urls o el punto de conexión de contenido del trabajo documentado. El modelo google/veo-3.1-fast incluido de forma predeterminada anuncia duraciones de 4/6/8 segundos, resoluciones 720P/1080P y relaciones de aspecto 16:9/9:16.

Qwen

El mismo backend DashScope que Alibaba. Las entradas de referencia deben ser URLs http(s) remotas; los archivos locales se rechazan de inmediato.

Runway

Admite archivos locales a través de URI de datos. Video a video requiere runway/gen4_aleph. Las ejecuciones solo de texto exponen relaciones de aspecto 16:9 y 9:16.

Together

Solo referencia de imagen única.

Vydra

Utiliza https://www.vydra.ai/api/v1 directamente para evitar redirecciones que eliminen la autenticación. veo3 se incluye solo para texto a video; kling requiere una URL de imagen remota.

xAI

Admite texto a video, imagen a video de un solo primer fotograma, hasta 7 entradas reference_image a través de xAI reference_images, y flujos de edición/extensión de video remotos.

Modos de capacidad del proveedor

El contrato compartido de generación de video admite capacidades específicas del modo en lugar de solo límites agregados planos. Las nuevas implementaciones de proveedores deben preferir bloques de modo explícitos:

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,
  },
}

Los campos agregados planos como maxInputImages y maxInputVideos no son suficientes para anunciar la compatibilidad con el modo 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 del modo de manera determinista.

Cuando un modelo en un proveedor tiene una compatibilidad de entrada de referencia más amplia que el resto, use maxInputImagesByModel, maxInputVideosByModel o maxInputAudiosByModel en lugar de aumentar el límite de todo el modo.

Pruebas en vivo

Cobertura en vivo opcional para los proveedores agrupados compartidos:

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts

Contenedor del repositorio:

pnpm test:live:media video

Este archivo en vivo utiliza por defecto las variables de entorno del proveedor ya exportadas antes que los perfiles de autenticación almacenados, y ejecuta por defecto una prueba de humo segura para lanzamientos:

• generate para cada proveedor que no sea FAL en el barrido.
• Indicador de langosta de un segundo.
• Límite de operaciones por proveedor desde OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 de forma predeterminada).

FAL es opcional porque la latencia de la cola del lado del proveedor puede dominar el tiempo de lanzamiento:

pnpm test:live:media video --video-providers fal

Establezca OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 para también ejecutar los modos de transformación declarados que el barrido compartido pueda ejercer de manera segura con medios locales:

• imageToVideo cuando capabilities.imageToVideo.enabled.
• videoToVideo cuando capabilities.videoToVideo.enabled y el proveedor/modelo acepta entrada de video local respaldada por búfer en el barrido compartido.

Hoy, el carril compartido videoToVideo en vivo cubre runway solo cuando selecciona runway/gen4_aleph.

Configuración

Establezca el modelo de generación de video predeterminado en su configuración de OpenClaw:

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-r2v-flash"],
      },
    },
  },
}

O a través de la CLI:

openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"

Relacionado

• Alibaba Model Studio
• Tareas en segundo plano - seguimiento de tareas para la generación de video asíncrona
• BytePlus
• ComfyUI
• Referencia de configuración
• fal
• Google (Gemini)
• MiniMax
• Modelos
• OpenAI
• Qwen
• Runway
• Together AI
• Descripción general de herramientas
• Vydra
• xAI