feat: VideoClient + Grok Imagine models + GCS-backed image response fields

- New VideoClient (blockrun_llm/video.py) for xai/grok-imagine-video at $0.05/sec, 8s default. Blocks until polling completes (~30-120s).
- VideoResponse / VideoClip / VideoModel types added.
- ImageData gains optional source_url + backed_up fields for gateway-mirrored assets.
- README documents new Grok Imagine image + video models.
- Bumped to 0.13.0.

Author: 1bcMax

CHANGELOG.md

@@ -2,7 +2,16 @@
 
 All notable changes to blockrun-llm will be documented in this file.
 
-## 0.11.0 (Current)
+## 0.13.0
+
+- **New `VideoClient`** — generate AI videos via `xai/grok-imagine-video` ($0.05/sec, 8s default).
+- `VideoResponse`, `VideoClip`, `VideoModel` types added.
+- Text-to-video and image-to-video supported; client blocks until polling completes (~30-120s).
+- `ImageData` now exposes `source_url` and `backed_up` for gateway-mirrored assets.
+- Grok Imagine image models (`xai/grok-imagine-image`, `-pro`) routable via `ImageClient`.
+- Grok 4.20 chat models (`xai/grok-4.20-reasoning`, `-non-reasoning`, `-multi-agent`) routable via the chat API.
+
+## 0.11.0
 
 - 43+ models supported
 - Base and Solana chain payments

README.md

@@ -245,6 +245,29 @@ All models below have been tested end-to-end via the Python SDK (Mar 2026):
 | `black-forest/flux-1.1-pro` | $0.04/image |
 | `google/nano-banana` | $0.05/image |
 | `google/nano-banana-pro` | $0.10-0.15/image |
+| `xai/grok-imagine-image` | $0.02/image |
+| `xai/grok-imagine-image-pro` | $0.07/image |
+| `zai/cogview-4` | $0.015/image |
+
+### Video Generation
+| Model | Price |
+|-------|-------|
+| `xai/grok-imagine-video` | $0.05/sec (8s default → $0.42/clip) |
+
+```python
+from blockrun_llm import VideoClient
+
+client = VideoClient()
+result = client.generate("a red apple slowly spinning on a wooden table")
+print(result.data[0].url)            # permanent MP4 URL
+print(result.data[0].duration_seconds)  # 8
+
+# Image-to-video
+result = client.generate(
+    "the subject turns its head and smiles",
+    image_url="https://example.com/portrait.jpg",
+)
+```
 
 ## X/Twitter Data (Powered by AttentionVC)
 

blockrun_llm/__init__.py

@@ -29,6 +29,13 @@
     result = client.generate("A cute cat wearing a space helmet")
     print(result.data[0].url)
 
+Video generation:
+    from blockrun_llm import VideoClient
+
+    client = VideoClient()
+    result = client.generate("a red apple slowly spinning on a wooden table")
+    print(result.data[0].url)  # permanent MP4 URL
+
 Other Chains:
     - XRPL (RLUSD): Use blockrun-llm-xrpl (pip install blockrun-llm-xrpl)
     - Solana (USDC): Use SolanaLLMClient (pip install blockrun-llm[solana])
@@ -46,6 +53,7 @@
 from .solana_client import SolanaLLMClient
 from .image import ImageClient
 from .music import MusicClient
+from .video import VideoClient
 from .types import (
     ChatMessage,
     ChatResponse,
@@ -59,6 +67,10 @@
     MusicResponse,
     AudioTrack,
     AudioModel,
+    # Video types
+    VideoResponse,
+    VideoClip,
+    VideoModel,
     # Live Search types
     SearchParameters,
     WebSearchSource,
@@ -121,7 +133,7 @@
 )
 from .cache import clear_cache, get_cost_log_summary
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 __all__ = [
     "LLMClient",
     "AsyncLLMClient",
@@ -138,6 +150,7 @@
     "list_image_models",
     "ImageClient",
     "MusicClient",
+    "VideoClient",
     "ChatMessage",
     "ChatResponse",
     "Model",
@@ -149,6 +162,9 @@
     "MusicResponse",
     "AudioTrack",
     "AudioModel",
+    "VideoResponse",
+    "VideoClip",
+    "VideoModel",
     # Live Search types
     "SearchParameters",
     "WebSearchSource",

blockrun_llm/types.py

@@ -138,6 +138,12 @@ class ImageData(BaseModel):
     """A single generated image."""
 
     url: str
+    # When the gateway mirrors the asset to its own storage, `url` is the
+    # permanent blockrun-hosted URL and `source_url` is the original upstream.
+    # `backed_up` is True iff the mirror step succeeded. For data-URI results
+    # (e.g. openai/gpt-image-1) both fields are omitted.
+    source_url: Optional[str] = None
+    backed_up: Optional[bool] = None
     revised_prompt: Optional[str] = None
 
 
@@ -187,6 +193,40 @@ class AudioModel(BaseModel):
     description: str
     price_per_track: float
     max_duration_seconds: int
+
+
+# Video generation types
+
+class VideoClip(BaseModel):
+    """A single generated video clip."""
+
+    url: str  # Permanent blockrun-hosted URL (falls back to upstream if backup fails)
+    source_url: Optional[str] = None  # Original upstream URL (e.g. vidgen.x.ai)
+    duration_seconds: Optional[int] = None
+    request_id: Optional[str] = None  # Upstream provider's request id (xAI)
+    backed_up: Optional[bool] = None
+
+
+class VideoResponse(BaseModel):
+    """Response from video generation."""
+
+    created: int
+    model: str
+    data: List[VideoClip]
+    txHash: Optional[str] = None
+
+
+class VideoModel(BaseModel):
+    """Available video model information."""
+
+    id: str
+    name: str
+    provider: str
+    description: str
+    price_per_second: float
+    default_duration_seconds: int
+    max_duration_seconds: int
+    supports_image_input: bool = False
     supports_lyrics: bool
     supports_instrumental: bool
     available: bool = True