@danhachuel/thunderbolt 0.3.41 → 0.3.43

package/hermes_ui/api_key_tests.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import os
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, Mapping
 from urllib.parse import quote, urlsplit, urlunsplit
 
 import requests
@@ -110,6 +110,38 @@ def test_nano_banana_credentials(api_key: str, model: str) -> dict[str, Any]:
     )
 
 
+def test_media_provider_card(card: Mapping[str, Any]) -> dict[str, Any]:
+    """Run a bounded, non-generative check for an image/video provider card."""
+    source = dict(card) if isinstance(card, Mapping) else {}
+    provider = str(source.get("provider") or "").strip().lower()
+    api_key = str(source.get("api_key") or "").strip()
+    model = str(source.get("model") or "").strip()
+    base_url = str(source.get("base_url") or "").strip().rstrip("/")
+    api_style = str(source.get("api_style") or "").strip().lower()
+    if provider == "nano_banana":
+        return test_nano_banana_credentials(api_key, model)
+    if not base_url:
+        return _result("missing", "Complete a Base URL antes de testar.")
+    if provider not in {"inferenceport", "ollama", "lmstudio"} and not api_key:
+        return _missing("Introduza a API key/token antes de testar este provider.")
+    if not model and provider not in {"inferenceport", "cloudflare_workers_ai"}:
+        return _result("missing", "Complete o modelo antes de testar.")
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    if provider == "cloudflare_workers_ai":
+        account_id = str(source.get("account_id") or "").strip()
+        if not account_id:
+            return _result("missing", "Complete o Account ID do Cloudflare antes de testar.")
+        endpoint = f"{base_url}/accounts/{quote(account_id, safe='')}/ai/models/search"
+        return _get(endpoint, headers=headers, params={"search": model or "stable-diffusion"})
+    if api_style in {"openai_compatible", "huggingface", "agnes", "kie"} or provider in {"pollinations", "huggingface", "agnes", "kie_ai", "inferenceport"}:
+        endpoint = _models_endpoint(base_url)
+    elif provider == "fal_ai":
+        endpoint = f"{base_url}/models" if base_url.endswith("/v1") else base_url
+    else:
+        endpoint = base_url
+    return _get(endpoint, headers=headers)
+
+
 def test_azure_speech_credentials(api_key: str, region: str) -> dict[str, Any]:
     """Validate Azure Speech by listing voices; this does not synthesize audio."""
     api_key = str(api_key or "").strip()

package/hermes_ui/creative_generation.py

@@ -3,12 +3,13 @@ from __future__ import annotations
 import json
 import re
 from functools import lru_cache
-from pathlib import Path
-from typing import Any
 
 import requests
+from pathlib import Path
+from typing import Any
 
 from .llm_providers import active_llm_card, provider_definition
+from .provider_routing import ProviderRoutingError, route_llm_json
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -86,31 +87,22 @@ def _json_content(payload: dict[str, Any]) -> dict[str, Any]:
 
 
 def _chat_json(settings: dict[str, Any], system_prompt: str, user_prompt: str) -> dict[str, Any]:
-    _provider, api_key, base_url, model = _provider_config(settings)
-    headers = {"Content-Type": "application/json"}
-    if api_key:
-        headers["Authorization"] = f"Bearer {api_key}"
-    body = {
-        "model": model,
-        "messages": [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt},
-        ],
-        "response_format": {"type": "json_object"},
-    }
-    endpoint = f"{base_url}/chat/completions"
-    try:
-        response = requests.post(endpoint, headers=headers, json=body, timeout=120)
-    except requests.RequestException as exc:
-        raise CreativeGenerationError(f"Não foi possível contactar o provider LLM: {exc}") from exc
-    if response.status_code >= 400:
-        detail = response.text[:500].replace(api_key, "[REDACTED]") if api_key else response.text[:500]
-        raise CreativeGenerationError(f"O provider LLM devolveu HTTP {response.status_code}: {detail}")
+    # Keep the actionable legacy validation for an entirely unconfigured setup;
+    # the router still skips incomplete cards when a configured fallback exists.
+    cards = settings.get("llm_provider_cards") if isinstance(settings, dict) else None
+    if not isinstance(cards, list) or not any(
+        isinstance(card, dict)
+        and bool(card.get("enabled", True))
+        and str(card.get("api_key") or "").strip()
+        and str(card.get("model") or card.get("model_name") or "").strip()
+        for card in cards
+    ):
+        _provider_config(settings)
     try:
-        payload = response.json()
-    except ValueError as exc:
-        raise CreativeGenerationError("O provider LLM devolveu uma resposta que não é JSON.") from exc
-    return _json_content(payload)
+        routed = route_llm_json(settings, system_prompt, user_prompt)
+    except ProviderRoutingError as exc:
+        raise CreativeGenerationError(str(exc)) from exc
+    return _json_content(routed.payload)
 
 
 def channel_context(channel: dict[str, Any], blueprint: dict[str, Any] | None = None) -> dict[str, Any]:

package/hermes_ui/domain.py

@@ -135,7 +135,16 @@ def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
                 topic = f"Vídeo para {channel.get('name', 'Canal')}"
             title = str(payload.get("title") or topic).strip()
             artifacts = dict(payload.get("artifacts") or {})
-            thumbnail_path = str(payload.get("thumbnail_path") or "").strip()
+            thumbnail_variants = payload.get("thumbnail_variants") if isinstance(payload.get("thumbnail_variants"), list) else []
+            thumbnail_variant = payload.get("thumbnail_variant") if isinstance(payload.get("thumbnail_variant"), dict) else {}
+            if count > 1 and thumbnail_variants:
+                candidate = thumbnail_variants[index % len(thumbnail_variants)]
+                if isinstance(candidate, dict):
+                    thumbnail_variant = candidate
+            thumbnail_path = str(thumbnail_variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
+            thumbnail_prompt = str(thumbnail_variant.get("image_prompt") or payload.get("thumbnail_prompt") or "").strip()
+            thumbnail_text = str(thumbnail_variant.get("overlay_text") or payload.get("thumbnail_text") or "").strip()
+            thumbnail_status = str(payload.get("thumbnail_status") or ("generated" if thumbnail_path else "not_generated"))
             if thumbnail_path:
                 artifacts.setdefault("thumbnail", thumbnail_path)
             task = {
@@ -161,11 +170,11 @@ def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
                 "voice": payload.get("voice") or channel.get("default_voice") or channel.get("voice", ""),
                 "automation_on": bool(channel.get("automation_on", False)),
                 "automation_time": channel.get("automation_time", "00:00"),
-                "thumbnail_variant": payload.get("thumbnail_variant", {}),
-                "thumbnail_variants": payload.get("thumbnail_variants", []),
-                "thumbnail_prompt": payload.get("thumbnail_prompt", ""),
-                "thumbnail_text": payload.get("thumbnail_text", ""),
-                "thumbnail_status": payload.get("thumbnail_status", "not_generated"),
+                "thumbnail_variant": thumbnail_variant,
+                "thumbnail_variants": thumbnail_variants,
+                "thumbnail_prompt": thumbnail_prompt,
+                "thumbnail_text": thumbnail_text,
+                "thumbnail_status": thumbnail_status,
                 "title_candidates": payload.get("title_candidates", []),
                 "ai_generation": payload.get("ai_generation", {}),
                 "stage": "script",

package/hermes_ui/languages.py

@@ -235,8 +235,14 @@ _API_KEY_EXPANDER_TRANSLATIONS: dict[str, dict[str, str]] = {
 for _language_code, _api_key_values in _API_KEY_EXPANDER_TRANSLATIONS.items():
     UI_TRANSLATIONS[_language_code].update(_api_key_values)
 
+# This expander is intentionally kept as a stable product label while the
+# provider cards themselves expose their capability labels in the current UI.
+for _language_code in UI_TRANSLATIONS:
+    UI_TRANSLATIONS[_language_code].setdefault("Imagem e Video", "Imagem e Video")
 
-# Labels introduced by the reorganised sidebar. They are merged into the
+
+# Labels introduced by the reorganised sidebar.
+# They are merged into the
 # existing UI translation index so every navigation control uses the same
 # translation path as the legacy pages.
 UI_NAV_TRANSLATIONS: dict[str, dict[str, str]] = {
@@ -968,7 +974,7 @@ _CONTENT_TRANSLATION_ROWS = (
     ("Niche Finder — execução remota no Kaggle", "Niche Finder — execução remota no Kaggle", "Niche Finder — remote execution on Kaggle", "Niche Finder — Kaggle 远程执行", "Niche Finder — Remoteausführung auf Kaggle", "Niche Finder — chạy từ xa trên Kaggle", "Niche Finder — Kaggle'da uzaktan çalıştırma", "Niche Finder — удалённый запуск на Kaggle", "Niche Finder — ejecución remota en Kaggle", "Niche Finder — eksekusi jarak jauh di Kaggle", "Niche Finder — esecuzione remota su Kaggle"),
     ("O dataset permanece no Kaggle. O Thunderbolt usa estas credenciais apenas para publicar/executar a kernel e obter os resultados pequenos da análise.", "O dataset permanece no Kaggle. O Thunderbolt usa estas credenciais apenas para publicar/executar a kernel e obter os resultados pequenos da análise.", "The dataset remains on Kaggle. Thunderbolt uses these credentials only to publish/run the kernel and retrieve small analysis results.", "数据集保留在 Kaggle。Thunderbolt 仅使用这些凭证发布/运行 kernel 并获取小型分析结果。", "Der Datensatz bleibt auf Kaggle. Thunderbolt verwendet diese Zugangsdaten nur zum Veröffentlichen/Ausführen des Kernels und zum Abrufen kleiner Analyseergebnisse.", "Dataset vẫn ở Kaggle. Thunderbolt chỉ dùng thông tin xác thực để xuất bản/chạy kernel và lấy kết quả phân tích nhỏ.", "Veri kümesi Kaggle'da kalır. Thunderbolt bu kimlik bilgilerini yalnızca kernel'ı yayınlamak/çalıştırmak ve küçük analiz sonuçlarını almak için kullanır.", "Датасет остаётся на Kaggle. Thunderbolt использует эти данные только для публикации/запуска kernel и получения небольших результатов анализа.", "El dataset permanece en Kaggle. Thunderbolt usa estas credenciales solo para publicar/ejecutar el kernel y obtener pequeños resultados del análisis.", "Dataset tetap di Kaggle. Thunderbolt menggunakan kredensial ini hanya untuk menerbitkan/menjalankan kernel dan mengambil hasil analisis kecil.", "Il dataset resta su Kaggle. Thunderbolt usa queste credenziali solo per pubblicare/eseguire il kernel e ottenere piccoli risultati dell'analisi."),
     ("Niche Finder — execução através da Apify", "Niche Finder — execução através da Apify", "Niche Finder — execution through Apify", "Niche Finder — 通过 Apify 执行", "Niche Finder — Ausführung über Apify", "Niche Finder — chạy qua Apify", "Niche Finder — Apify üzerinden çalıştırma", "Niche Finder — запуск через Apify", "Niche Finder — ejecución mediante Apify", "Niche Finder — eksekusi melalui Apify", "Niche Finder — esecuzione tramite Apify"),
-    ("Nano Banana — geração de thumbnails", "Nano Banana — geração de thumbnails", "Nano Banana — thumbnail generation", "Nano Banana — 缩略图生成", "Nano Banana — Thumbnail-Generierung", "Nano Banana — tạo thumbnail", "Nano Banana — küçük resim oluşturma", "Nano Banana — создание миниатюр", "Nano Banana — generación de miniaturas", "Nano Banana — pembuatan thumbnail", "Nano Banana — generazione miniature"),
+    ("Imagem e Video", "Imagem e Video", "Image and Video", "图像和视频", "Bild und Video", "Hình ảnh và video", "Görüntü ve Video", "Изображение и видео", "Imagen y vídeo", "Gambar dan Video", "Immagine e Video"),
     ("A Nano Banana gera a imagem final das thumbnails a partir da variante escolhida. A chave é guardada apenas no storage local e é distinta da chave do Gemini usado como LLM textual.", "A Nano Banana gera a imagem final das thumbnails a partir da variante escolhida. A chave é guardada apenas no storage local e é distinta da chave do Gemini usado como LLM textual.", "Nano Banana generates the final thumbnail image from the selected variant. The key is stored locally and is separate from the Gemini key used as a text LLM.", "Nano Banana 根据所选变体生成最终缩略图。密钥仅保存在本地存储中，与用于文本 LLM 的 Gemini 密钥分开。", "Nano Banana erzeugt das endgültige Thumbnail aus der ausgewählten Variante. Der Schlüssel wird nur lokal gespeichert und ist vom Gemini-Schlüssel für das Text-LLM getrennt.", "Nano Banana tạo ảnh thumbnail cuối từ biến thể đã chọn. Key chỉ lưu cục bộ và tách biệt với key Gemini dùng cho LLM văn bản.", "Nano Banana, seçilen varyanttan son küçük resim görselini oluşturur. Anahtar yalnızca yerel depolamada tutulur ve metin LLM'i için kullanılan Gemini anahtarından ayrıdır.", "Nano Banana создаёт финальное изображение миниатюры из выбранного варианта. Ключ хранится локально отдельно от ключа Gemini для текстовой LLM.", "Nano Banana genera la miniatura final a partir de la variante elegida. La clave se guarda localmente y es distinta de la clave de Gemini del LLM de texto.", "Nano Banana menghasilkan gambar thumbnail akhir dari varian yang dipilih. Kunci disimpan secara lokal dan terpisah dari kunci Gemini untuk LLM teks.", "Nano Banana genera l'immagine finale della miniatura dalla variante scelta. La chiave è salvata localmente ed è separata da quella Gemini usata per l'LLM testuale."),
     ("LLM — providers e modelos", "LLM — providers e modelos", "LLM — providers and models", "LLM — 服务商和模型", "LLM — Anbieter und Modelle", "LLM — provider và mô hình", "LLM — sağlayıcılar ve modeller", "LLM — провайдеры и модели", "LLM — proveedores y modelos", "LLM — penyedia dan model", "LLM — provider e modelli"),
     ("OpenAI/ NVIDIA NIM — API key, Base URL e modelo", "OpenAI/ NVIDIA NIM — API key, Base URL e modelo", "OpenAI/NVIDIA NIM — API key, Base URL and model", "OpenAI/NVIDIA NIM — API 密钥、基础 URL 和模型", "OpenAI/NVIDIA NIM — API-Schlüssel, Basis-URL und Modell", "OpenAI/NVIDIA NIM — API key, Base URL và mô hình", "OpenAI/NVIDIA NIM — API anahtarı, Temel URL ve model", "OpenAI/NVIDIA NIM — API-ключ, базовый URL и модель", "OpenAI/NVIDIA NIM — clave API, URL base y modelo", "OpenAI/NVIDIA NIM — kunci API, URL Dasar, dan model", "OpenAI/NVIDIA NIM — API key, URL di base e modello"),

package/hermes_ui/llm_providers.py

@@ -397,6 +397,10 @@ def test_llm_provider_card(card: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
+# This callable is a production diagnostic helper, not a pytest test function.
+test_llm_provider_card.__test__ = False
+
+
 def stamp_test_result(result: Mapping[str, Any]) -> dict[str, Any]:
     status = "success" if result.get("ok") else "error"
     return {

package/hermes_ui/media_generation.py

@@ -0,0 +1,383 @@
+"""Provider adapters for the independent image and video pools.
+
+Adapters are intentionally small and response-shape tolerant: providers can return
+base64, data URLs, direct URLs, or asynchronous task identifiers. The router owns
+failover; this module owns provider-specific HTTP contracts.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import time
+from pathlib import Path
+from typing import Any, Mapping
+from urllib.parse import urljoin
+
+import requests
+
+from .media_providers import media_cards_for_pool, media_provider_definition
+from .provider_routing import (
+    POOL_IMAGE,
+    POOL_VIDEO,
+    ProviderCallError,
+    ProviderRoutingError,
+    route_json_request,
+)
+from .storage import STORAGE, ensure_storage
+from .thumbnail_generation import generate_thumbnail_image
+
+
+class MediaGenerationError(RuntimeError):
+    """Raised when an image/video adapter cannot produce a usable artifact."""
+
+
+def _api_key(card: Mapping[str, Any]) -> str:
+    return str(card.get("api_key") or "").strip()
+
+
+def _model(card: Mapping[str, Any]) -> str:
+    return str(card.get("model") or "").strip()
+
+
+def _base_url(card: Mapping[str, Any]) -> str:
+    return str(card.get("base_url") or "").strip().rstrip("/")
+
+
+def _headers(card: Mapping[str, Any], *, fal: bool = False) -> dict[str, str]:
+    key = _api_key(card)
+    headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    if key:
+        headers["Authorization"] = f"Key {key}" if fal else f"Bearer {key}"
+    return headers
+
+
+def _decode_data(value: Any) -> bytes | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    raw = value.strip()
+    if raw.startswith("data:") and "," in raw:
+        raw = raw.split(",", 1)[1]
+    try:
+        return base64.b64decode(raw, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+
+
+def _image_value(payload: Any) -> tuple[bytes | None, str]:
+    if isinstance(payload, (bytes, bytearray)):
+        return bytes(payload), ""
+    if not isinstance(payload, Mapping):
+        return None, ""
+    direct = payload.get("image") or payload.get("output_image")
+    if isinstance(direct, Mapping):
+        direct = direct.get("data") or direct.get("url")
+    data = _decode_data(direct)
+    if data:
+        return data, ""
+    if isinstance(direct, str) and direct.startswith(("http://", "https://")):
+        return None, direct
+    entries = payload.get("data") or payload.get("outputs") or payload.get("images")
+    if isinstance(entries, list) and entries:
+        first = entries[0]
+        if isinstance(first, Mapping):
+            data = _decode_data(first.get("b64_json") or first.get("base64") or first.get("data"))
+            if data:
+                return data, ""
+            url = str(first.get("url") or first.get("image_url") or "").strip()
+            if url:
+                return None, url
+    result = payload.get("result")
+    if isinstance(result, Mapping):
+        data = _decode_data(result.get("image") or result.get("b64_json") or result.get("data"))
+        if data:
+            return data, ""
+        url = str(result.get("url") or result.get("image_url") or "").strip()
+        if url:
+            return None, url
+    return None, ""
+
+
+def _download_or_write(image_bytes: bytes | None, url: str, destination: Path, card: Mapping[str, Any]) -> Path:
+    if image_bytes is None and url:
+        try:
+            response = requests.get(url, headers={"Authorization": f"Bearer {_api_key(card)}"} if _api_key(card) else {}, timeout=180)
+            response.raise_for_status()
+            image_bytes = response.content
+        except requests.RequestException as exc:
+            raise MediaGenerationError(f"Não foi possível descarregar a imagem devolvida pelo provider: {exc}") from exc
+    if not image_bytes:
+        raise MediaGenerationError("O provider concluiu a chamada mas não devolveu uma imagem utilizável.")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(image_bytes)
+    return destination
+
+
+def _image_endpoint(card: Mapping[str, Any]) -> str:
+    definition = media_provider_definition(card.get("provider"))
+    style = str(card.get("api_style") or definition.api_style)
+    base = _base_url(card)
+    explicit = str(card.get("image_endpoint") or "").strip()
+    if explicit:
+        return explicit
+    if style in {"openai_compatible", "huggingface", "agnes", "kie"}:
+        return f"{base}/images/generations"
+    if style == "cloudflare":
+        account_id = str(card.get("account_id") or "").strip()
+        if not account_id:
+            raise MediaGenerationError("Cloudflare Workers AI requer Account ID no cartão de media.")
+        model = _model(card) or "@cf/stabilityai/stable-diffusion-xl-base-1.0"
+        model = model if model.startswith("@") else f"@{model}"
+        return f"{base}/accounts/{account_id}/ai/run/{model}"
+    if style == "fal_queue":
+        if not _model(card):
+            raise MediaGenerationError("FAL AI requer o identificador da rota/modelo para gerar imagem.")
+        return f"{base}/{_model(card).lstrip('/')}"
+    if style == "dashscope":
+        return f"{base}/services/aigc/text2image/image-synthesis"
+    raise MediaGenerationError(f"O provider {card.get('provider')} não tem endpoint de imagem configurado.")
+
+
+def _image_request(card: dict[str, Any], prompt: str) -> Any:
+    provider = str(card.get("provider") or "").strip().lower()
+    style = str(card.get("api_style") or media_provider_definition(provider).api_style)
+    endpoint = _image_endpoint(card)
+    if style == "cloudflare":
+        return requests.post(endpoint, headers=_headers(card), json={"prompt": prompt}, timeout=180)
+    if style == "fal_queue":
+        return requests.post(endpoint, headers=_headers(card, fal=True), json={"prompt": prompt, "num_images": 1}, timeout=180)
+    if style == "dashscope":
+        body = {"model": _model(card), "input": {"prompt": prompt}, "parameters": {"size": "1024*1024", "n": 1}}
+        return requests.post(endpoint, headers=_headers(card), json=body, timeout=180)
+    body = {"model": _model(card), "prompt": prompt, "n": 1, "response_format": "b64_json"}
+    return requests.post(endpoint, headers=_headers(card), json=body, timeout=180)
+
+
+def generate_image_for_card(
+    settings: Mapping[str, Any],
+    card: Mapping[str, Any],
+    prompt: str,
+    *,
+    topic: str = "",
+    variant_index: int = 0,
+    lettering_text: str = "",
+    lettering_prompt: str = "",
+    reference_image: Path | None = None,
+) -> Path:
+    """Generate one image with the selected media card."""
+    card = dict(card)
+    provider = str(card.get("provider") or "").strip().lower()
+    if provider == "nano_banana":
+        merged = dict(settings)
+        merged["gemini_image_api_key"] = _api_key(card)
+        merged["gemini_image_model"] = _model(card) or merged.get("gemini_image_model") or "gemini-3.1-flash-image"
+        try:
+            return generate_thumbnail_image(
+                merged,
+                prompt,
+                topic=topic,
+                variant_index=variant_index,
+                lettering_text=lettering_text,
+                lettering_prompt=lettering_prompt,
+                reference_image=reference_image,
+            )
+        except Exception as exc:
+            raise MediaGenerationError(str(exc)) from exc
+
+    ensure_storage()
+    destination = STORAGE / "thumbnails" / f"media-{provider}-{abs(hash((topic, prompt, variant_index))) & 0xffffffffffffffff:x}.jpg"
+
+    def request(current: dict[str, Any]) -> Any:
+        return _image_request(current, prompt)
+
+    try:
+        routed = route_json_request(settings, pool=POOL_IMAGE, cards=[card], request=request)
+    except ProviderRoutingError as exc:
+        raise MediaGenerationError(str(exc)) from exc
+    image_bytes, url = _image_value(routed.payload)
+    return _download_or_write(image_bytes, url, destination, routed.card)
+
+
+def _is_retryable_media_error(exc: BaseException) -> bool:
+    text = str(exc).lower()
+    if any(marker in text for marker in ("http 400", "http 401", "http 403", "http 404", "invalid request", "missing", "não tem endpoint")):
+        return False
+    return any(marker in text for marker in ("http 408", "http 425", "http 429", "http 500", "http 502", "http 503", "http 504", "timeout", "timed out", "connection", "temporarily", "cooldown"))
+
+
+def generate_image_from_pool(
+    settings: Mapping[str, Any],
+    prompt: str,
+    *,
+    topic: str = "",
+    variant_index: int = 0,
+    lettering_text: str = "",
+    lettering_prompt: str = "",
+    reference_image: Path | None = None,
+) -> Path:
+    """Try eligible image cards in priority order, without cross-pool fallback."""
+    cards = media_cards_for_pool(settings, "image")
+    if not cards:
+        raise MediaGenerationError("Não existem providers activos no pool de imagem.")
+    errors: list[str] = []
+    for card in cards:
+        try:
+            return generate_image_for_card(
+                settings,
+                card,
+                prompt,
+                topic=topic,
+                variant_index=variant_index,
+                lettering_text=lettering_text,
+                lettering_prompt=lettering_prompt,
+                reference_image=reference_image,
+            )
+        except MediaGenerationError as exc:
+            errors.append(f"{card.get('provider')}: {str(exc)[:180]}")
+            if not _is_retryable_media_error(exc):
+                raise
+    raise MediaGenerationError("Todos os providers do pool de imagem falharam: " + " | ".join(errors))
+
+
+def _video_endpoint(card: Mapping[str, Any]) -> str:
+    explicit = str(card.get("video_endpoint") or "").strip()
+    if explicit:
+        return explicit
+    definition = media_provider_definition(card.get("provider"))
+    style = str(card.get("api_style") or definition.api_style)
+    base = _base_url(card)
+    if style == "fal_queue":
+        if not _model(card):
+            raise MediaGenerationError("FAL AI requer o identificador da rota/modelo para gerar vídeo.")
+        return f"{base}/{_model(card).lstrip('/')}"
+    if style in {"openai_compatible", "agnes", "kie"}:
+        return f"{base}/videos/generations"
+    if style == "dashscope":
+        return f"{base}/services/aigc/video-generation/video-synthesis"
+    raise MediaGenerationError(f"O provider {card.get('provider')} não tem endpoint de vídeo configurado.")
+
+
+def _video_request(card: dict[str, Any], prompt: str, image_url: str = "") -> Any:
+    style = str(card.get("api_style") or media_provider_definition(card.get("provider")).api_style)
+    endpoint = _video_endpoint(card)
+    body: dict[str, Any] = {"model": _model(card), "prompt": prompt}
+    if image_url:
+        body["image_url"] = image_url
+    if style == "fal_queue":
+        body.pop("model", None)
+        return requests.post(endpoint, headers=_headers(card, fal=True), json=body, timeout=180)
+    return requests.post(endpoint, headers=_headers(card), json=body, timeout=180)
+
+
+def _video_result(payload: Mapping[str, Any]) -> tuple[str, str]:
+    direct = str(payload.get("video_url") or payload.get("url") or payload.get("output") or "").strip()
+    if direct:
+        return direct, ""
+    result = payload.get("result")
+    if isinstance(result, Mapping):
+        direct = str(result.get("video_url") or result.get("url") or result.get("output") or "").strip()
+        if direct:
+            return direct, ""
+    for key in ("request_id", "id", "task_id", "job_id"):
+        value = str(payload.get(key) or "").strip()
+        if value:
+            return "", value
+    data = payload.get("data")
+    if isinstance(data, list) and data and isinstance(data[0], Mapping):
+        first = data[0]
+        direct = str(first.get("url") or first.get("video_url") or "").strip()
+        if direct:
+            return direct, ""
+    return "", ""
+
+
+def _poll_video(card: Mapping[str, Any], request_id: str, *, attempts: int = 24, interval_seconds: float = 5.0) -> str:
+    definition = media_provider_definition(card.get("provider"))
+    style = str(card.get("api_style") or definition.api_style)
+    explicit_status = str(card.get("status_endpoint") or "").strip()
+    base = _base_url(card)
+    if explicit_status:
+        endpoint = explicit_status.replace("{id}", request_id)
+    elif style == "fal_queue":
+        endpoint = f"{base}/requests/{request_id}/status"
+    else:
+        endpoint = f"{base}/videos/{request_id}"
+    headers = _headers(card, fal=style == "fal_queue")
+    for index in range(max(1, attempts)):
+        try:
+            response = requests.get(endpoint, headers=headers, timeout=60)
+            if response.status_code >= 400:
+                category = "quota" if response.status_code == 429 else "transient" if response.status_code >= 500 else "endpoint_or_model"
+                raise ProviderCallError(f"Consulta de vídeo devolveu HTTP {response.status_code}.", status_code=response.status_code, category=category, retryable=category in {"quota", "transient"})
+            payload = response.json()
+        except requests.RequestException as exc:
+            raise ProviderCallError(f"Falha ao consultar o vídeo: {str(exc)[:180]}", category="transient", retryable=True) from exc
+        url, _ = _video_result(payload if isinstance(payload, Mapping) else {})
+        if url:
+            return url
+        status = str((payload or {}).get("status") or "").lower() if isinstance(payload, Mapping) else ""
+        if status in {"failed", "error", "cancelled"}:
+            raise ProviderCallError("O provider marcou a tarefa de vídeo como falhada.", category="provider", retryable=False)
+        if index + 1 < attempts:
+            time.sleep(max(0.2, interval_seconds))
+    raise ProviderCallError("O provider de vídeo não concluiu dentro do limite de polling.", category="transient", retryable=True)
+
+
+def generate_video_for_card(
+    settings: Mapping[str, Any],
+    card: Mapping[str, Any],
+    prompt: str,
+    *,
+    image_url: str = "",
+    output_path: Path | None = None,
+) -> Path:
+    """Submit and resolve one video generation request."""
+    card = dict(card)
+    provider = str(card.get("provider") or "").strip().lower()
+
+    def request(current: dict[str, Any]) -> Any:
+        return _video_request(current, prompt, image_url=image_url)
+
+    try:
+        routed = route_json_request(settings, pool=POOL_VIDEO, cards=[card], request=request)
+    except ProviderRoutingError as exc:
+        raise MediaGenerationError(str(exc)) from exc
+    url, request_id = _video_result(routed.payload)
+    if not url and request_id:
+        try:
+            url = _poll_video(routed.card, request_id)
+        except ProviderCallError as exc:
+            raise MediaGenerationError(str(exc)) from exc
+    if not url:
+        raise MediaGenerationError(f"O provider {provider} não devolveu URL nem identificador de vídeo.")
+    destination = output_path or (STORAGE / "videos" / f"media-{provider}-{abs(hash((prompt, url))) & 0xffffffffffffffff:x}.mp4")
+    try:
+        response = requests.get(url, headers={"Authorization": f"Bearer {_api_key(routed.card)}"} if _api_key(routed.card) else {}, timeout=300)
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise MediaGenerationError(f"Não foi possível descarregar o vídeo gerado: {exc}") from exc
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(response.content)
+    return destination
+
+
+def generate_video_from_pool(
+    settings: Mapping[str, Any],
+    prompt: str,
+    *,
+    image_url: str = "",
+    output_path: Path | None = None,
+) -> Path:
+    """Try eligible video cards in priority order, keeping image and video pools separate."""
+    cards = media_cards_for_pool(settings, "video")
+    if not cards:
+        raise MediaGenerationError("Não existem providers activos no pool de vídeo.")
+    errors: list[str] = []
+    for card in cards:
+        try:
+            return generate_video_for_card(settings, card, prompt, image_url=image_url, output_path=output_path)
+        except MediaGenerationError as exc:
+            errors.append(f"{card.get('provider')}: {str(exc)[:180]}")
+            if not _is_retryable_media_error(exc):
+                raise
+    raise MediaGenerationError("Todos os providers do pool de vídeo falharam: " + " | ".join(errors))