v1.0.56

Changes

Prompture has been quietly competent at text and image generation for a while — this PR drags it the rest of the way into the multi-modal world. It adds a brand-new video generation modality (with Grok Imagine and seven Runway video models behind it) and rounds out the Runway surface across image, TTS, sound effects, and voice transforms, all under a single API key.

Highlights

• Generate videos from text or image inputs via get_video_gen_driver_for_model("grok/grok-imagine-video") or get_video_gen_driver_for_model("runway/gen4.5"), with polling, cost reporting, and the same provider/model routing as the rest of the library.
• One Runway key (RUNWAY_API_KEY or RUNWAYML_API_SECRET) now unlocks image generation (gen4_image, gen4_image_turbo, gpt_image_2, gemini_image3_pro, gemini_2.5_flash), video (gen4.5, gen4_turbo, gen3a_turbo, gen4_aleph, veo3, veo3.1, veo3.1_fast), TTS (eleven_multilingual_v2 with 49 preset voices), and sound effects (eleven_text_to_sound_v2).
• New RunwayAudioTransformDriver covers voice dubbing across 29 languages, voice isolation, and speech-to-speech voice conversion — operations that don't fit STT/TTS shape and so live as a standalone helper.
• A capability registry (get_runway_model_info, get_runway_models_by_op, get_runway_models_by_modality) lets callers ask "which Runway models do text_to_video?" as data, without instantiating drivers.
• get_available_video_gen_models() joins the existing image / audio / embedding discovery helpers, and auto-detects video-capable models from configured provider keys plus the models.dev fallback.
• Three runnable examples in examples/ for video, image, and audio Runway flows, plus a Grok video example.

Technical changes

• New video generation modality:
  • prompture/drivers/video_gen_base.py adds VideoGenDriver with the response contract (videos, meta.video_count, duration_seconds, aspect_ratio, resolution, cost, model_name, raw_response), capability flags (supports_image_input, supports_reference_images, supports_video_input, supports_audio, supports_polling, supported_aspect_ratios, supported_resolutions, max_seconds), and generate_video_with_hooks for on_request / on_response / on_error callbacks.
  • async_video_gen_base.py mirrors it for async.
  • prompture/drivers/registry.py gains _video_gen_sync / _video_gen_async DriverRegistry instances plus the full set of public functions (register_video_gen_driver, unregister_video_gen_driver, list_registered_video_gen_drivers, is_video_gen_driver_registered, get_video_gen_driver_factory, load_video_gen_entry_point_drivers, async siblings, and _get_video_gen_registry / _get_async_video_gen_registry). Both registries are reset by _reset_registries.
  • prompture/drivers/video_gen_registry.py exposes the get_video_gen_driver_for_model / get_async_video_gen_driver_for_model factories that parse "provider/model" strings.
• VideoCostMixin added to prompture/infra/cost_mixin.py. _calculate_video_cost resolves cost in this order: resolution-specific per_second_by_resolution[resolution] × duration_seconds, then generic per_second × duration_seconds, then per_video, then default.
• prompture/media/video.py introduces VideoContent (frozen dataclass with data, media_type, source_type, url, duration_seconds, width, height), the VideoInput type alias, and constructors video_from_bytes, video_from_base64, video_from_file, video_from_url, and make_video. MIME detection covers MP4 / MOV / WebM / MKV / AVI / MPEG via extension lookup, magic-byte sniffing (EBML for WebM, ftyp box for MP4/MOV), and a _DATA_URI_RE matcher for data:video/... URIs.
• New Grok video generation driver prompture/drivers/grok_video_gen_driver.py (sync) and async_grok_video_gen_driver.py (async) targeting the xAI POST /videos/generations + GET /videos/{id} endpoints. Validates duration (1-15 s, max 10 s when reference images are used), aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3), resolution (480p / 720p), and rejects image + reference_images combinations. Reference images limited to seven. VIDEO_PRICING uses per_second_by_resolution: $0.05/s at 480p, $0.07/s at 720p. Accepts GROK_API_KEY or XAI_API_KEY, polls the task with configurable poll_interval / timeout, returns request_id-only response when poll=False. Supports ImageInput / dict / data-URI inputs through make_image.
• New Runway image driver runway_img_gen_driver.py (+ async) hits POST /v1/text_to_image then polls GET /v1/tasks/{id} until SUCCEEDED / FAILED / CANCELLED. Enforces the 16 documented text_to_image ratios, requires reference_images for gen4_image_turbo, rejects quality on models other than gpt_image_2, normalizes reference image dicts to {uri, tag}, and parses Runway's structured error / issues body into a single error string via _format_error. Pricing covers all five models with size/quality buckets where Runway differentiates. Default ratios per model live in _DEFAULT_RATIOS. Header X-Runway-Version: 2024-11-06.
• New Runway video driver runway_video_gen_driver.py (+ async) handles all three video endpoints (/v1/text_to_video, /v1/image_to_video, /v1/video_to_video) in one class. _detect_mode picks the endpoint from an explicit mode option or auto-detects from video / image presence in options. Per-mode model allow-lists (_KNOWN_MODELS_BY_MODE) and per-endpoint ratio sets (_T2V_RATIOS, _I2V_RATIOS). _normalize_prompt_image accepts strings, dicts, or lists of keyframe dicts and emits the right promptImage shape. VIDEO_PRICING is per-second per model ($0.05–$0.40/s).
• New Runway TTS driver runway_tts_driver.py (+ async) routes by model: any eleven_text_to_sound_v2 request hits /v1/sound_effect, anything else hits /v1/text_to_speech. Sound effects accept duration (0.5–30 s) and loop. TTS requires a preset voice — either a string preset name resolved to {type: runway-preset, presetId: ...} or a full voice dict. The 49 Runway preset voice names are exposed as available_voices. AudioCostMixin provides per-character TTS pricing ($0.000030/char) and per-second sound-effect pricing ($0.04/s).
• New runway_audio_transform_driver.py adds RunwayAudioTransformDriver for the three operations that take audio and return audio: dub(audio, target_lang, ...) (29 ISO-639-1 codes validated against DUBBING_LANGUAGES), isolate(audio, ...), and convert_voice(media, voice_preset_id, media_kind="audio"|"video", ...). All three submit a task, poll until terminal, download the resulting audio via the _fetch_audio helper, and return {audio, media_type, meta}. Lives outside the modality registry by design — STT and TTS contracts don't apply.
• runway_capabilities.py declares RUNWAY_MODEL_INFO: dict[str, RunwayModelInfo] covering 16 Runway models with modality, operations, endpoints, and cost notes. Exposes get_runway_model_info(model_id_or_provider_path), get_runway_models_by_op(operation), and get_runway_models_by_modality(modality), plus ALL_OPERATIONS / ALL_MODALITIES sorted lists.
• provider_descriptors.py adds video_gen_sync / video_gen_async fields to ProviderDescriptor, a full Runway descriptor wiring image + video + TTS modalities, a new _runway_kw lookup (runway_api_key, runway_endpoint), and a runwayml alias for runway covering {img_gen, video_gen, tts}. The xai alias for grok now also covers video_gen. The descriptor-driven register_all_builtin_drivers() learns the two new modalities via register_video_gen_driver / register_async_video_gen_driver. Grok descriptor adds video_gen_sync / video_gen_async pointing at the new drivers with grok_video_model as the default key.
• prompture/infra/settings.py adds xai_api_key, grok_video_model (default grok-imagine-video), runway_api_key, and runway_endpoint. provider_env.py adds xai_api_key to ProviderEnvironment for per-consumer isolation.
• prompture/infra/discovery.py adds get_available_video_gen_models() (Grok + Runway via static KNOWN_MODELS, plus a models.dev fallback that scans caps.modalities_output for "video"), and extends get_available_image_gen_models and get_available_audio_models to include Runway when the key is present.
• prompture/drivers/__init__.py exports all new drivers, registry functions, the Runway capability helpers, and VideoGenDriver / AsyncVideoGenDriver base classes. __all__ updated. prompture/infra/__init__.py re-exports VideoCostMixin and get_available_video_gen_models.
• New examples: examples/grok_video_generation_example.py, examples/runway_image_generation_example.py, examples/runway_video_generation_example.py, examples/runway_audio_example.py.
• .env.copy documents XAI_API_KEY, GROK_VIDEO_MODEL, and the Runway block. .gitignore adds entries for example output artifacts.
• README.md and CLAUDE.md document the new video modality, the Runway surface, the capability registry, and the discovery helpers. Provider count bumped from 17+ to 18+.

Details

• Version: v1.0.56
• PR: #83 by @jhd3197
• PR URL: #83