prompture 1.0.55.dev2__tar.gz → 1.0.56.dev1__tar.gz

{prompture-1.0.55.dev2 → prompture-1.0.56.dev1}/.env.copy

@@ -53,7 +53,10 @@ OPENROUTER_MODEL=openai/gpt-4o-mini
 
 # ─── Grok (xAI) ─────────────────────────────────────────────────────────────
 GROK_API_KEY=your-grok-api-key
+# XAI_API_KEY is also supported for xAI docs compatibility.
+XAI_API_KEY=
 GROK_MODEL=grok-4-fast-reasoning
+GROK_VIDEO_MODEL=grok-imagine-video
 
 # ─── Moonshot AI (Kimi) ─────────────────────────────────────────────────────
 MOONSHOT_API_KEY=your-moonshot-api-key
@@ -86,4 +89,4 @@ AIRLLM_MODEL=meta-llama/Llama-2-7b-hf
 AIRLLM_COMPRESSION=
 
 # ─── Stability AI (image generation) ────────────────────────────────────────
-STABILITY_API_KEY=
+STABILITY_API_KEY=

{prompture-1.0.55.dev2 → prompture-1.0.56.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.0.55.dev2
+Version: 1.0.56.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -96,7 +96,7 @@ print(person.name)  # Maria
 
 - **Structured output** — JSON schema enforcement and direct Pydantic model population
 - **17+ providers** — OpenAI, Claude, Google, Groq, Grok, Azure, Ollama, LM Studio, OpenRouter, HuggingFace, Moonshot, ModelScope, Z.ai, Vertex AI, AirLLM, CachiBot, and generic HTTP
-- **Multi-modal** — Drivers for embeddings, image generation (DALL-E, Imagen, Grok, Stability), text-to-speech, and speech-to-text (Whisper, ElevenLabs)
+- **Multi-modal** — Drivers for embeddings, image generation (DALL-E, Imagen, Grok, Stability), video generation (Grok Imagine Video), text-to-speech, and speech-to-text (Whisper, ElevenLabs)
 - **Multi-model fallback** — Try a list of models in sequence with per-attempt cost, token, and capability accounting
 - **Strategy cascade** — Auto-selects between provider-native JSON mode, tool-call extraction, and prompted repair so extraction works on any model
 - **TOON input conversion** — 45-60% token savings when sending structured data via [Token-Oriented Object Notation](https://github.com/jhd3197/python-toon)
@@ -141,6 +141,8 @@ ANTHROPIC_API_KEY=sk-ant-...
 GOOGLE_API_KEY=...
 GROQ_API_KEY=...
 GROK_API_KEY=...
+# optional xAI-compatible alias for Grok APIs
+XAI_API_KEY=...
 OPENROUTER_API_KEY=...
 AZURE_OPENAI_ENDPOINT=...
 AZURE_OPENAI_API_KEY=...
@@ -198,6 +200,7 @@ Beyond text LLMs, Prompture exposes drivers for adjacent modalities under the sa
 
 - **Embeddings** — OpenAI (`text-embedding-3-*`) and Ollama (`nomic-embed-text`)
 - **Image generation** — OpenAI DALL-E, Google Imagen, Grok, Stability AI
+- **Video generation** — Grok Imagine Video (`grok-imagine-video`) with text-to-video, image-to-video, reference images, and polling
 - **Text-to-speech** — OpenAI (`tts-1`) and ElevenLabs
 - **Speech-to-text** — OpenAI Whisper and ElevenLabs
 
@@ -212,6 +215,26 @@ result = driver.generate_image(
 print(result["meta"]["cost"], result["meta"]["image_count"])
 ```
 
+Video generation uses the same provider/model routing. Set `GROK_API_KEY` or `XAI_API_KEY`, then request a Grok video model:
+
+```python
+from prompture import get_video_gen_driver_for_model
+
+driver = get_video_gen_driver_for_model("grok/grok-imagine-video")
+result = driver.generate_video(
+    "wide shot of a crystal-powered rocket launching from red desert dunes",
+    {"duration": 8, "aspect_ratio": "16:9", "resolution": "720p"},
+)
+
+video = result["videos"][0]
+print(video.url)
+print(result["meta"]["request_id"], result["meta"]["cost"])
+```
+
+For local smoke tests without waiting on the render, pass `{"poll": False}` to get the provider request ID. The async factory is available as `get_async_video_gen_driver_for_model()`.
+
+Runnable example: `python examples/grok_video_generation_example.py`.
+
 ## Usage
 
 ### One-Shot Pydantic Extraction

{prompture-1.0.55.dev2 → prompture-1.0.56.dev1}/README.md

@@ -32,7 +32,7 @@ print(person.name)  # Maria
 
 - **Structured output** — JSON schema enforcement and direct Pydantic model population
 - **17+ providers** — OpenAI, Claude, Google, Groq, Grok, Azure, Ollama, LM Studio, OpenRouter, HuggingFace, Moonshot, ModelScope, Z.ai, Vertex AI, AirLLM, CachiBot, and generic HTTP
-- **Multi-modal** — Drivers for embeddings, image generation (DALL-E, Imagen, Grok, Stability), text-to-speech, and speech-to-text (Whisper, ElevenLabs)
+- **Multi-modal** — Drivers for embeddings, image generation (DALL-E, Imagen, Grok, Stability), video generation (Grok Imagine Video), text-to-speech, and speech-to-text (Whisper, ElevenLabs)
 - **Multi-model fallback** — Try a list of models in sequence with per-attempt cost, token, and capability accounting
 - **Strategy cascade** — Auto-selects between provider-native JSON mode, tool-call extraction, and prompted repair so extraction works on any model
 - **TOON input conversion** — 45-60% token savings when sending structured data via [Token-Oriented Object Notation](https://github.com/jhd3197/python-toon)
@@ -77,6 +77,8 @@ ANTHROPIC_API_KEY=sk-ant-...
 GOOGLE_API_KEY=...
 GROQ_API_KEY=...
 GROK_API_KEY=...
+# optional xAI-compatible alias for Grok APIs
+XAI_API_KEY=...
 OPENROUTER_API_KEY=...
 AZURE_OPENAI_ENDPOINT=...
 AZURE_OPENAI_API_KEY=...
@@ -134,6 +136,7 @@ Beyond text LLMs, Prompture exposes drivers for adjacent modalities under the sa
 
 - **Embeddings** — OpenAI (`text-embedding-3-*`) and Ollama (`nomic-embed-text`)
 - **Image generation** — OpenAI DALL-E, Google Imagen, Grok, Stability AI
+- **Video generation** — Grok Imagine Video (`grok-imagine-video`) with text-to-video, image-to-video, reference images, and polling
 - **Text-to-speech** — OpenAI (`tts-1`) and ElevenLabs
 - **Speech-to-text** — OpenAI Whisper and ElevenLabs
 
@@ -148,6 +151,26 @@ result = driver.generate_image(
 print(result["meta"]["cost"], result["meta"]["image_count"])
 ```
 
+Video generation uses the same provider/model routing. Set `GROK_API_KEY` or `XAI_API_KEY`, then request a Grok video model:
+
+```python
+from prompture import get_video_gen_driver_for_model
+
+driver = get_video_gen_driver_for_model("grok/grok-imagine-video")
+result = driver.generate_video(
+    "wide shot of a crystal-powered rocket launching from red desert dunes",
+    {"duration": 8, "aspect_ratio": "16:9", "resolution": "720p"},
+)
+
+video = result["videos"][0]
+print(video.url)
+print(result["meta"]["request_id"], result["meta"]["cost"])
+```
+
+For local smoke tests without waiting on the render, pass `{"poll": False}` to get the provider request ID. The async factory is available as `get_async_video_gen_driver_for_model()`.
+
+Runnable example: `python examples/grok_video_generation_example.py`.
+
 ## Usage
 
 ### One-Shot Pydantic Extraction

{prompture-1.0.55.dev2 → prompture-1.0.56.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.55.dev2'
-__version_tuple__ = version_tuple = (1, 0, 55, 'dev2')
+__version__ = version = '1.0.56.dev1'
+__version_tuple__ = version_tuple = (1, 0, 56, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.0.55.dev2 → prompture-1.0.56.dev1}/prompture/drivers/__init__.py

@@ -41,6 +41,7 @@ from .async_google_driver import AsyncGoogleDriver
 from .async_google_img_gen_driver import AsyncGoogleImageGenDriver
 from .async_grok_driver import AsyncGrokDriver
 from .async_grok_img_gen_driver import AsyncGrokImageGenDriver
+from .async_grok_video_gen_driver import AsyncGrokVideoGenDriver
 from .async_groq_driver import AsyncGroqDriver
 from .async_hugging_driver import AsyncHuggingFaceDriver
 from .async_img_gen_base import AsyncImageGenDriver
@@ -59,6 +60,7 @@ from .async_openrouter_driver import AsyncOpenRouterDriver
 from .async_stability_img_gen_driver import AsyncStabilityImageGenDriver
 from .async_stt_base import AsyncSTTDriver
 from .async_tts_base import AsyncTTSDriver
+from .async_video_gen_base import AsyncVideoGenDriver
 from .async_zai_driver import AsyncZaiDriver
 from .azure_config import (
     clear_azure_configs,
@@ -76,6 +78,7 @@ from .google_driver import GoogleDriver
 from .google_img_gen_driver import GoogleImageGenDriver
 from .grok_driver import GrokDriver
 from .grok_img_gen_driver import GrokImageGenDriver
+from .grok_video_gen_driver import GrokVideoGenDriver
 from .groq_driver import GroqDriver
 from .hugging_driver import HuggingFaceDriver
 from .img_gen_base import ImageGenDriver
@@ -104,59 +107,70 @@ from .registry import (
     get_async_img_gen_driver_factory,
     get_async_stt_driver_factory,
     get_async_tts_driver_factory,
+    get_async_video_gen_driver_factory,
     get_driver_factory,
     get_embedding_driver_factory,
     get_img_gen_driver_factory,
     get_stt_driver_factory,
     get_tts_driver_factory,
+    get_video_gen_driver_factory,
     is_async_driver_registered,
     is_async_embedding_driver_registered,
     is_async_img_gen_driver_registered,
     is_async_stt_driver_registered,
     is_async_tts_driver_registered,
+    is_async_video_gen_driver_registered,
     is_driver_registered,
     is_embedding_driver_registered,
     is_img_gen_driver_registered,
     is_stt_driver_registered,
     is_tts_driver_registered,
+    is_video_gen_driver_registered,
     list_registered_async_drivers,
     list_registered_async_embedding_drivers,
     list_registered_async_img_gen_drivers,
     list_registered_async_stt_drivers,
     list_registered_async_tts_drivers,
+    list_registered_async_video_gen_drivers,
     list_registered_drivers,
     list_registered_embedding_drivers,
     list_registered_img_gen_drivers,
     list_registered_stt_drivers,
     list_registered_tts_drivers,
+    list_registered_video_gen_drivers,
     load_entry_point_drivers,
     register_async_driver,
     register_async_embedding_driver,
     register_async_img_gen_driver,
     register_async_stt_driver,
     register_async_tts_driver,
+    register_async_video_gen_driver,
     register_driver,
     register_embedding_driver,
     register_img_gen_driver,
     register_stt_driver,
     register_tts_driver,
+    register_video_gen_driver,
     unregister_async_driver,
     unregister_async_embedding_driver,
     unregister_async_img_gen_driver,
     unregister_async_stt_driver,
     unregister_async_tts_driver,
+    unregister_async_video_gen_driver,
     unregister_driver,
     unregister_embedding_driver,
     unregister_img_gen_driver,
     unregister_stt_driver,
     unregister_tts_driver,
+    unregister_video_gen_driver,
 )
 from .stability_img_gen_driver import StabilityImageGenDriver
 from .stt_base import STTDriver
 from .tts_base import TTSDriver
+from .video_gen_base import VideoGenDriver
 from .zai_driver import ZaiDriver
 
-# Register all built-in drivers (LLM sync/async, STT, TTS, img_gen, embedding)
+# Register all built-in drivers (LLM sync/async, STT, TTS, img_gen, video_gen, embedding)
 # from the unified ProviderDescriptor list — replaces ~200 lines of individual
 # register_*() calls that were previously scattered across this file,
 # async_registry.py, audio_registry.py, embedding_registry.py, and img_gen_registry.py.
@@ -185,6 +199,10 @@ from .img_gen_registry import (
     get_async_img_gen_driver_for_model,
     get_img_gen_driver_for_model,
 )
+from .video_gen_registry import (
+    get_async_video_gen_driver_for_model,
+    get_video_gen_driver_for_model,
+)
 
 # Backwards compatibility: expose registry dict (read-only view recommended)
 DRIVER_REGISTRY = _get_sync_registry()
@@ -449,6 +467,7 @@ __all__ = [
     "AsyncGoogleImageGenDriver",
     "AsyncGrokDriver",
     "AsyncGrokImageGenDriver",
+    "AsyncGrokVideoGenDriver",
     "AsyncGroqDriver",
     "AsyncHuggingFaceDriver",
     "AsyncImageGenDriver",
@@ -467,6 +486,7 @@ __all__ = [
     "AsyncSTTDriver",
     "AsyncStabilityImageGenDriver",
     "AsyncTTSDriver",
+    "AsyncVideoGenDriver",
     "AsyncZaiDriver",
     # Sync LLM drivers
     "AzureDriver",
@@ -482,6 +502,7 @@ __all__ = [
     "GoogleImageGenDriver",
     "GrokDriver",
     "GrokImageGenDriver",
+    "GrokVideoGenDriver",
     "GroqDriver",
     "HuggingFaceDriver",
     # Image gen base class
@@ -502,6 +523,7 @@ __all__ = [
     "STTDriver",
     "StabilityImageGenDriver",
     "TTSDriver",
+    "VideoGenDriver",
     "ZaiDriver",
     # Azure config API
     "clear_azure_configs",
@@ -521,6 +543,10 @@ __all__ = [
     "get_async_stt_driver_for_model",
     "get_async_tts_driver_factory",
     "get_async_tts_driver_for_model",
+    # Video gen registry query functions
+    "get_async_video_gen_driver_factory",
+    # Video gen factory functions
+    "get_async_video_gen_driver_for_model",
     # LLM factory functions
     "get_driver",
     "get_driver_for_model",
@@ -532,27 +558,33 @@ __all__ = [
     "get_stt_driver_for_model",
     "get_tts_driver_factory",
     "get_tts_driver_for_model",
+    "get_video_gen_driver_factory",
+    "get_video_gen_driver_for_model",
     # Other registry query functions
     "is_async_driver_registered",
     "is_async_embedding_driver_registered",
     "is_async_img_gen_driver_registered",
     "is_async_stt_driver_registered",
     "is_async_tts_driver_registered",
+    "is_async_video_gen_driver_registered",
     "is_driver_registered",
     "is_embedding_driver_registered",
     "is_img_gen_driver_registered",
     "is_stt_driver_registered",
     "is_tts_driver_registered",
+    "is_video_gen_driver_registered",
     "list_registered_async_drivers",
     "list_registered_async_embedding_drivers",
     "list_registered_async_img_gen_drivers",
     "list_registered_async_stt_drivers",
     "list_registered_async_tts_drivers",
+    "list_registered_async_video_gen_drivers",
     "list_registered_drivers",
     "list_registered_embedding_drivers",
     "list_registered_img_gen_drivers",
     "list_registered_stt_drivers",
     "list_registered_tts_drivers",
+    "list_registered_video_gen_drivers",
     "load_entry_point_drivers",
     "parse_model_string",
     "provider_for_model",
@@ -562,6 +594,7 @@ __all__ = [
     "register_async_img_gen_driver",
     "register_async_stt_driver",
     "register_async_tts_driver",
+    "register_async_video_gen_driver",
     "register_azure_config",
     # Registry functions (public API)
     "register_driver",
@@ -569,16 +602,19 @@ __all__ = [
     "register_img_gen_driver",
     "register_stt_driver",
     "register_tts_driver",
+    "register_video_gen_driver",
     "set_azure_config_resolver",
     "unregister_async_driver",
     "unregister_async_embedding_driver",
     "unregister_async_img_gen_driver",
     "unregister_async_stt_driver",
     "unregister_async_tts_driver",
+    "unregister_async_video_gen_driver",
     "unregister_azure_config",
     "unregister_driver",
     "unregister_embedding_driver",
     "unregister_img_gen_driver",
     "unregister_stt_driver",
     "unregister_tts_driver",
+    "unregister_video_gen_driver",
 ]

prompture-1.0.56.dev1/prompture/drivers/async_grok_video_gen_driver.py

@@ -0,0 +1,194 @@
+"""Async xAI Grok Imagine video generation driver."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any
+
+import httpx
+
+from ..infra.cost_mixin import VideoCostMixin
+from .async_video_gen_base import AsyncVideoGenDriver
+from .grok_video_gen_driver import (
+    _DEFAULT_ENDPOINT,
+    _duration_from_options,
+    _error_text,
+    _extract_video_content,
+    _get_xai_api_key,
+    _image_payload,
+)
+
+
+class AsyncGrokVideoGenDriver(VideoCostMixin, AsyncVideoGenDriver):
+    """Async video generation via xAI Grok Imagine Video REST API."""
+
+    supports_image_input = True
+    supports_reference_images = True
+    supports_video_input = False
+    supports_audio = True
+    supports_polling = True
+    supported_aspect_ratios = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"]
+    supported_resolutions = ["480p", "720p"]
+    max_seconds = 15
+
+    KNOWN_MODELS = ["grok-imagine-video"]
+    VIDEO_PRICING: dict[str, dict[str, Any]] = {
+        "grok-imagine-video": {
+            "per_second": 0.05,
+            "per_second_by_resolution": {
+                "480p": 0.05,
+                "720p": 0.07,
+            },
+        }
+    }
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "grok-imagine-video",
+        endpoint: str | None = None,
+    ):
+        self.api_key = _get_xai_api_key(api_key)
+        self.model = model
+        self.endpoint = (endpoint or os.getenv("GROK_ENDPOINT") or _DEFAULT_ENDPOINT).rstrip("/")
+
+    @classmethod
+    def list_models(cls, *, api_key: str | None = None, **kw: object) -> list[str] | None:
+        """Return known xAI video models when an API key is configured."""
+        key = _get_xai_api_key(api_key)
+        if not key:
+            return None
+        return list(cls.KNOWN_MODELS)
+
+    async def generate_video(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
+        """Generate a video using xAI Grok Imagine Video (async)."""
+        if not self.api_key:
+            raise RuntimeError("GROK_API_KEY or XAI_API_KEY environment variable is required")
+        if not prompt:
+            raise ValueError("prompt cannot be empty")
+
+        model = options.get("model", self.model)
+        duration = _duration_from_options(options)
+        aspect_ratio = options.get("aspect_ratio", "16:9")
+        resolution = options.get("resolution", "480p")
+
+        if aspect_ratio not in self.supported_aspect_ratios:
+            raise ValueError(f"Unsupported aspect_ratio '{aspect_ratio}'")
+        if resolution not in self.supported_resolutions:
+            raise ValueError(f"Unsupported resolution '{resolution}'")
+
+        image = options.get("image")
+        reference_images = options.get("reference_images")
+        if image is not None and reference_images:
+            raise ValueError("image and reference_images cannot be used together")
+        if reference_images:
+            if len(reference_images) > 7:
+                raise ValueError("reference_images supports at most 7 images")
+            if duration > 10:
+                raise ValueError("duration must be 10 seconds or less when using reference_images")
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+            "duration": duration,
+            "aspect_ratio": aspect_ratio,
+            "resolution": resolution,
+        }
+        if image is not None:
+            payload["image"] = _image_payload(image)
+        if reference_images:
+            payload["reference_images"] = [_image_payload(img) for img in reference_images]
+
+        headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.endpoint}/videos/generations",
+                headers=headers,
+                json=payload,
+                timeout=120.0,
+            )
+            if response.status_code >= 400:
+                raise RuntimeError(
+                    f"Grok video generation failed: HTTP {response.status_code}: {_error_text(response)}"
+                )
+
+            start_data = response.json()
+            request_id = start_data.get("request_id")
+            if not request_id:
+                raise RuntimeError("Grok video generation response did not include request_id")
+
+            if not options.get("poll", True):
+                return {
+                    "videos": [],
+                    "meta": {
+                        "video_count": 0,
+                        "request_id": request_id,
+                        "status": start_data.get("status", "pending"),
+                        "duration_seconds": duration,
+                        "aspect_ratio": aspect_ratio,
+                        "resolution": resolution,
+                        "cost": 0.0,
+                        "model_name": f"grok/{model}",
+                        "raw_response": start_data,
+                    },
+                }
+
+            final_data = await self._poll_until_done(
+                client,
+                request_id,
+                headers=headers,
+                poll_interval=float(options.get("poll_interval", 5)),
+                timeout_seconds=float(options.get("timeout", 600)),
+            )
+
+        video = _extract_video_content(final_data)
+        duration_seconds = video.duration_seconds or float(duration)
+        cost = self._calculate_video_cost(
+            "grok",
+            model,
+            duration_seconds=duration_seconds,
+            n=1,
+            resolution=resolution,
+        )
+
+        return {
+            "videos": [video],
+            "meta": {
+                "video_count": 1,
+                "request_id": request_id,
+                "status": final_data.get("status"),
+                "duration_seconds": duration_seconds,
+                "aspect_ratio": aspect_ratio,
+                "resolution": resolution,
+                "cost": cost,
+                "model_name": f"grok/{model}",
+                "raw_response": {"start": start_data, "final": final_data},
+            },
+        }
+
+    async def _poll_until_done(
+        self,
+        client: httpx.AsyncClient,
+        request_id: str,
+        *,
+        headers: dict[str, str],
+        poll_interval: float,
+        timeout_seconds: float,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            response = await client.get(f"{self.endpoint}/videos/{request_id}", headers=headers, timeout=30.0)
+            if response.status_code >= 400:
+                raise RuntimeError(f"Grok video status failed: HTTP {response.status_code}: {_error_text(response)}")
+
+            data = response.json()
+            status = data.get("status")
+            if status == "done":
+                return data
+            if status in {"failed", "expired"}:
+                raise RuntimeError(f"Grok video generation {status}: {data}")
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Grok video generation timed out for request_id={request_id}")
+            await asyncio.sleep(poll_interval)

prompture-1.0.56.dev1/prompture/drivers/async_video_gen_base.py

@@ -0,0 +1,78 @@
+"""Async base class for video generation drivers."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from ..infra.callbacks import DriverCallbacks
+
+logger = logging.getLogger("prompture.async_video_gen_driver")
+
+
+class AsyncVideoGenDriver:
+    """Async adapter base for video generation. Implement ``async generate_video(prompt, options)``."""
+
+    supports_image_input: bool = False
+    supports_reference_images: bool = False
+    supports_video_input: bool = False
+    supports_audio: bool = False
+    supports_polling: bool = True
+    supported_aspect_ratios: list[str] = []
+    supported_resolutions: list[str] = []
+    max_seconds: int | None = None
+
+    callbacks: DriverCallbacks | None = None
+
+    async def generate_video(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
+        """Generate video(s) from a text prompt (async)."""
+        raise NotImplementedError
+
+    async def generate_video_with_hooks(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
+        """Wrap :meth:`generate_video` with on_request / on_response / on_error callbacks."""
+        driver_name = getattr(self, "model", self.__class__.__name__)
+        self._fire_callback(
+            "on_request",
+            {"prompt_length": len(prompt), "options": options, "driver": driver_name},
+        )
+        t0 = time.perf_counter()
+        try:
+            resp = await self.generate_video(prompt, options)
+        except Exception as exc:
+            self._fire_callback(
+                "on_error",
+                {"error": exc, "prompt_length": len(prompt), "options": options, "driver": driver_name},
+            )
+            raise
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        meta = resp.get("meta", {})
+        logger.debug(
+            "[video_gen] async generate driver=%s videos=%d cost=%.6f elapsed=%.0fms",
+            driver_name,
+            meta.get("video_count", 0),
+            meta.get("cost", 0.0),
+            elapsed_ms,
+        )
+        self._fire_callback(
+            "on_response",
+            {
+                "video_count": meta.get("video_count", 0),
+                "meta": meta,
+                "driver": driver_name,
+                "elapsed_ms": elapsed_ms,
+            },
+        )
+        return resp
+
+    def _fire_callback(self, event: str, payload: dict[str, Any]) -> None:
+        """Invoke a single callback, swallowing and logging any exception."""
+        if self.callbacks is None:
+            return
+        cb = getattr(self.callbacks, event, None)
+        if cb is None:
+            return
+        try:
+            cb(payload)
+        except Exception:
+            logger.exception("Callback %s raised an exception", event)