Genera videos con OpenClaw: Guía rápida de integración

Inicio rápido

1. Configura una API key para cualquier provider compatible:

export GEMINI_API_KEY="your-key"

2. Opcionalmente, fija un modelo por defecto:

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

3. Pregúntale al agent:

Genera un video cinematográfico de 5 segundos de una langosta amigable surfeando al atardecer.

El agent llama a video_generate automáticamente. No hace falta autorizar herramientas.

Qué sucede cuando generas un video

La generación de video es asíncrona. Cuando el agent llama a video_generate en una sesión:

1. OpenClaw envía la solicitud al provider y devuelve inmediatamente un ID de tarea.
2. El provider procesa el trabajo en segundo plano (normalmente de 30 segundos a 5 minutos, según el provider y la resolución).
3. Cuando el video está listo, OpenClaw reactiva la misma sesión con un evento de finalización interno.
4. El agent publica el video terminado en la conversación original.

Mientras un trabajo está en curso, 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. Usa openclaw tasks list o openclaw tasks show <taskId> para revisar el progreso desde la CLI.

Fuera de las ejecuciones del agent vinculadas a una sesión (por ejemplo, invocaciones directas de herramientas), la herramienta recurre a la generación inline y devuelve la ruta final del archivo en el mismo turno.

Ciclo de vida de la tarea

Cada solicitud de video_generate pasa por cuatro estados:

1. queued — tarea creada, esperando a que el provider la acepte.
2. running — el provider está procesando (normalmente de 30 segundos a 5 minutos según el provider y la resolución).
3. succeeded — video listo; el agent se activa y lo publica en la conversación.
4. failed — error del provider o tiempo de espera agotado; el agent se activa con los detalles del error.

Revisa el estado desde la CLI:

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

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

Proveedores compatibles

Proveedor	Modelo predeterminado	Texto	Ref. de imagen	Ref. de vídeo	API key
Alibaba	wan2.6-t2v	Sí	Sí (URL remota)	Sí (URL remota)	MODELSTUDIO_API_KEY
BytePlus	seedance-1-0-lite-t2v-250428	Sí	1 imagen	No	BYTEPLUS_API_KEY
ComfyUI	workflow	Sí	1 imagen	No	COMFY_API_KEY o COMFY_CLOUD_API_KEY
fal	fal-ai/minimax/video-01-live	Sí	1 imagen	No	FAL_KEY
Google	veo-3.1-fast-generate-preview	Sí	1 imagen	1 vídeo	GEMINI_API_KEY
MiniMax	MiniMax-Hailuo-2.3	Sí	1 imagen	No	MINIMAX_API_KEY
OpenAI	sora-2	Sí	1 imagen	1 vídeo	OPENAI_API_KEY
Qwen	wan2.6-t2v	Sí	Sí (URL remota)	Sí (URL remota)	QWEN_API_KEY
Runway	gen4.5	Sí	1 imagen	1 vídeo	RUNWAYML_API_SECRET
Together	Wan-AI/Wan2.2-T2V-A14B	Sí	1 imagen	No	TOGETHER_API_KEY
Vydra	veo3	Sí	1 imagen (kling)	No	VYDRA_API_KEY
xAI	grok-imagine-video	Sí	1 imagen	1 vídeo	XAI_API_KEY

Algunos proveedores aceptan variables de entorno de API key adicionales o alternativas. Consulta las páginas de proveedores individuales para más detalles.

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

Matriz de capacidades declaradas

Este es el contrato de modo explícito utilizado por video_generate, las pruebas de contrato y el barrido compartido en vivo.

Proveedor	generate	imageToVideo	videoToVideo	Carriles compartidos en vivo hoy
Alibaba	Sí	Sí	Sí	generate, imageToVideo; videoToVideo omitido porque este proveedor necesita URLs de vídeo http(s) remotas
BytePlus	Sí	Sí	No	generate, imageToVideo
ComfyUI	Sí	Sí	No	No está en el barrido compartido; la cobertura específica del workflow reside en las pruebas de Comfy
fal	Sí	Sí	No	generate, imageToVideo
Google	Sí	Sí	Sí	generate, imageToVideo; videoToVideo compartido omitido porque el barrido actual de Gemini/Veo basado en buffer no acepta esa entrada
MiniMax	Sí	Sí	No	generate, imageToVideo
OpenAI	Sí	Sí	Sí	generate, imageToVideo; videoToVideo compartido omitido porque esta ruta de organización/entrada necesita actualmente acceso a inpaint/remix del lado del proveedor
Qwen	Sí	Sí	Sí	generate, imageToVideo; videoToVideo omitido porque este proveedor necesita URLs de vídeo http(s) remotas
Runway	Sí	Sí	Sí	generate, imageToVideo; videoToVideo se ejecuta solo cuando el modelo seleccionado es runway/gen4_aleph
Together	Sí	Sí	No	generate, imageToVideo
Vydra	Sí	Sí	No	generate; imageToVideo compartido omitido porque veo3 incluido es solo texto y kling incluido requiere una URL de imagen remota
xAI	Sí	Sí	Sí	generate, imageToVideo; videoToVideo omitido porque este proveedor necesita actualmente una URL MP4 remota

Parámetros de la herramienta

Obligatorios

Parámetro	Tipo	Descripción
prompt	string	Descripción en texto del vídeo a generar (obligatorio para action: "generate")

Entradas de contenido

Parámetro	Tipo	Descripción
image	string	Imagen de referencia única (ruta o URL)
images	string[]	Múltiples imágenes de referencia (hasta 5)
video	string	Vídeo de referencia único (ruta o URL)
videos	string[]	Múltiples vídeos de referencia (hasta 4)

Controles de estilo

Parámetro	Tipo	Descripción
aspectRatio	string	1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
resolution	string	480P, 720P, 768P o 1080P
durationSeconds	number	Duración objetivo en segundos (redondeada al valor más cercano compatible con el proveedor)
size	string	Sugerencia de tamaño cuando el proveedor lo admite
audio	boolean	Activa el audio generado cuando sea compatible
watermark	boolean	Alterna la marca de agua del proveedor cuando sea compatible

Avanzados

Parámetro	Tipo	Descripción
action	string	"generate" (predeterminado), "status" o "list"
model	string	Sobrescritura de proveedor/modelo (ej. runway/gen4.5)
filename	string	Sugerencia de nombre de archivo de salida

No todos los proveedores admiten todos los parámetros. OpenClaw ya normaliza la duración al valor más cercano compatible con el proveedor y también reasigna sugerencias de geometría traducidas, como de tamaño a relación de aspecto, cuando un proveedor de respaldo expone una interfaz de control diferente. Las sobrescrituras que realmente no son compatibles se ignoran y se informan como advertencias en el resultado de la herramienta. Los límites de capacidad estrictos (como demasiadas entradas de referencia) fallan antes del envío.

Los resultados de la herramienta informan los ajustes aplicados. Cuando OpenClaw reasigna la duración o la geometría durante el fallback de un proveedor, los valores devueltos de durationSeconds, size, aspectRatio y resolution reflejan lo que se envió, y details.normalization captura la traducción de lo solicitado a lo aplicado.

Las entradas de referencia también seleccionan el modo de ejecución:

• Sin medios de referencia: generate
• Cualquier referencia de imagen: imageToVideo
• Cualquier referencia de vídeo: videoToVideo

Las referencias mixtas de imagen y vídeo no son una superficie de capacidad compartida estable. Es mejor usar un solo tipo de referencia por solicitud.

Acciones

• generate (por defecto) — crea un video a partir del prompt indicado y entradas de referencia opcionales.
• status — revisa el estado de la tarea de video en curso para la sesión actual sin iniciar otra generación.
• list — muestra los proveedores y modelos disponibles, junto con sus capacidades.

Selección de modelos

Cuando generas un video, OpenClaw resuelve qué modelo usar en este orden:

1. Parámetro de herramienta model — si el agente especifica uno en la llamada.
2. videoGenerationModel.primary — desde la configuración.
3. videoGenerationModel.fallbacks — se prueban en orden.
4. Detección automática — usa proveedores que tengan una auth válida, empezando por el proveedor predeterminado actual y siguiendo con los demás en orden alfabético.

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

Configura agents.defaults.mediaGenerationAutoProviderFallback: false si quieres que la generación de video use solo las entradas explícitas de model, primary y fallbacks.

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

Puedes fijar el video-agent de HeyGen en fal con:

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "fal/fal-ai/heygen/v2/video-agent",
      },
    },
  },
}

Puedes fijar Seedance 2.0 en fal con:

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
      },
    },
  },
}

Notas de los proveedores

Provider	Notas
Alibaba	Usa el endpoint asíncrono de DashScope/Model Studio. Las imágenes y videos de referencia deben ser URLs http(s) remotas.
BytePlus	Solo permite una referencia de imagen.
ComfyUI	Ejecución local o en la nube basada en workflows. Soporta text-to-video e image-to-video mediante el grafo configurado.
fal	Usa un flujo basado en colas para tareas largas. Solo permite una referencia de imagen. Incluye referencias a modelos HeyGen video-agent y Seedance 2.0 (text-to-video e image-to-video).
Google	Usa Gemini/Veo. Soporta una referencia de imagen o una de video.
MiniMax	Solo permite una referencia de imagen.
OpenAI	Solo se envía el override de size. Otros overrides de estilo (aspectRatio, resolution, audio, watermark) se ignoran y generan una advertencia.
Qwen	Mismo backend de DashScope que Alibaba. Las entradas de referencia deben ser URLs http(s) remotas; los archivos locales se rechazan de inmediato.
Runway	Soporta archivos locales mediante data URIs. Video-to-video requiere runway/gen4_aleph. Las ejecuciones de solo texto ofrecen relaciones de aspecto 16:9 y 9:16.
Together	Solo permite una referencia de imagen.
Vydra	Usa https://www.vydra.ai/api/v1 directamente para evitar redirecciones que pierdan la autenticación. veo3 se incluye solo como text-to-video; kling requiere una URL de imagen remota.
xAI	Soporta flujos de transformación (text-to-video e image-to-video) y flujos de edición o extensión de video remoto.

Modos de capacidad de los proveedores

El contrato compartido para la generación de video ahora permite que los proveedores declaren capacidades específicas por modo. Esto es mejor que usar solo límites agregados generales. Si vas a implementar nuevos proveedores, te recomiendo usar bloques de modo explícitos:

capabilities: {
  generate: {
    maxVideos: 1,
    maxDurationSeconds: 10,
    supportsResolution: true,
  },
  imageToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputImages: 1,
    maxDurationSeconds: 5,
  },
  videoToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputVideos: 1,
    maxDurationSeconds: 5,
  },
}

Los campos agregados como maxInputImages y maxInputVideos no bastan para anunciar el soporte del modo de transformación. Es necesario que los proveedores declaren los modos generate y de transformación (imageToVideo o videoToVideo) de forma explícita. De esta manera, los tests (tanto en vivo como de contrato) y la herramienta video_generate pueden validar el soporte de cada modo con total seguridad.

Pruebas en vivo

Activa la cobertura en vivo para los providers integrados:

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

Wrapper del repositorio:

pnpm test:live:media video

Este archivo de pruebas carga las variables de entorno que faltan desde ~/.profile. Por defecto, prefiere las API keys de las variables de entorno antes que los perfiles de autenticación guardados. Ejecuta los modos que puede probar de forma segura con archivos locales:

• generate para cada provider en el sweep
• imageToVideo cuando capabilities.imageToVideo.enabled está activo
• videoToVideo cuando capabilities.videoToVideo.enabled está activo y el provider o modelo acepta video local respaldado por buffer en el sweep compartido

Actualmente, el carril de pruebas en vivo para videoToVideo cubre:

• runway solo cuando seleccionas runway/gen4_aleph

Configuración

Configura el modelo de generación de video por defecto en tu archivo de 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

• Tools Overview
• Background Tasks — seguimiento de tareas para generación de video asíncrona
• Alibaba Model Studio
• BytePlus
• ComfyUI
• fal
• Google (Gemini)
• MiniMax
• OpenAI
• Qwen
• Runway
• Together AI
• Vydra
• xAI
• Configuration Reference
• Models

AI Setup Assistant