Skip to content
opencodex

Video Bridge

Overview

Section titled “Overview”

The Video Bridge lets you use xAI’s Grok Imagine Video generation through any non-OpenAI model routed by opencodex. When enabled, a synthetic video_gen tool is injected into the conversation. The model calls it like any function tool; opencodex intercepts the call, submits a video generation job to xAI, polls until completion, and downloads the result.

Prerequisites

Section titled “Prerequisites”
  • An xai provider entry with an API key (ocx login xai alone is not sufficient — the video bridge requires key auth, not OAuth)
  • A non-OpenAI model as your routed provider (e.g. Anthropic Claude, Google Gemini)
  • opencodex configured to route through the non-OpenAI provider

⚠ Provider key required: The video bridge only activates when the xai provider uses API key auth. Add this to your config:

{
  "providers": {
    "xai": { "adapter": "openai-chat", "apiKey": "xai-…", "authMode": "key" }
  }
}

If you onboarded via ocx login xai (OAuth), the provider stays in authMode: "oauth" and the bridge silently won’t activate. Set XAI_API_KEY in the environment or hard-code the key as shown above.

Configuration

Section titled “Configuration”

Add videoBridgeEnabled: true to your images config:

{
  "images": {
    "bridgeEnabled": true,
    "videoBridgeEnabled": true,
    "videoBridgeModel": "grok-imagine-video",
    "videoMaxRounds": 2,
    "videoTimeoutMs": 300000
  }
}
Option Default Description
videoBridgeEnabled false Master switch. Must be explicitly enabled.
videoBridgeModel "grok-imagine-video" xAI video model id.
videoMaxRounds 2 Max video-gen rounds before forced final answer.
videoTimeoutMs 300000 (5 min) Per-video timeout including polling.

How It Works

Section titled “How It Works”
  1. opencodex detects a non-OpenAI routed model with videoBridgeEnabled: true
  2. A synthetic video_gen function tool is injected into the conversation
  3. When the model calls video_gen, opencodex submits a job to xAI’s /videos/generations
  4. The bridge polls the job status every 5-15 seconds, sending heartbeat messages to keep the stream alive
  5. When the video is ready, it’s downloaded to the artifacts directory
  6. The local file path is returned to the model as a tool result

Supported Parameters

Section titled “Supported Parameters”

The video_gen tool accepts:

Parameter Type Range Description
prompt string required Detailed video generation prompt
duration integer 1-15 Video length in seconds
resolution string "480p", "720p" Video resolution
aspect_ratio string 7 ratios 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3

Limitations

Section titled “Limitations”
  • xAI only: Video generation is only available through xAI’s Grok Imagine Video API
  • Asynchronous: Video generation takes 30-120 seconds
  • Cost: Video generation is a paid xAI feature (~$0.05/sec @480p, ~$0.07/sec @720p)
  • One video per call: Each video_gen call produces one video
  • Coexists with Image Bridge: Both bridges can be enabled simultaneously
  • Web search priority: When a web search sidecar is active for a turn (non-runTurn adapter), the video bridge is skipped — the two cannot run concurrently. A console.warn is emitted so you can detect this in logs.
  • Timeout covers submit + poll: The videoTimeoutMs budget starts before job submission, so the submit call (60 s) and subsequent polling share the same deadline.