@danhachuel/thunderbolt 0.2.63 → 0.2.65

package/app/main.py

@@ -22,7 +22,7 @@ except (OSError, json.JSONDecodeError):
 
 from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_for_batch, delete_channel, pipeline_summary, set_channel_defaults, transition_task, update_channel, update_channel_video
 from hermes_ui.automation_worker import load_worker_status
-from hermes_ui.storage import BLUEPRINTS, STORAGE, TIKTOK_PROMPT_MASTERS, ensure_storage, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, write_json
+from hermes_ui.storage import BLUEPRINTS, STORAGE, TIKTOK_PROMPT_MASTERS, ensure_storage, get_display_name, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, set_display_name, write_json
 from app.modules.niche_finder.apify import ApifyError, DEFAULT_ACTOR_ID, abort_actor_run, build_actor_input, get_dataset_items, normalize_video_items, start_actor_run, wait_for_actor_run
 from app.modules.niche_finder.core import NicheAnalysisError, run_niche_analysis
 from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset
@@ -37,6 +37,7 @@ from hermes_ui.music import list_music_files, materialize_suno_audio, request_su
 from hermes_ui.script_documents import list_script_documents, read_script_document, save_script_document, script_storage_path
 from hermes_ui.script_generation import generate_script_document
 from hermes_ui.voice_preview import DEFAULT_SAMPLE, load_preview_file, synthesize_preview
+from hermes_ui.thumbnail_generation import ThumbnailGenerationError, generate_thumbnail_image
 from hermes_ui.creative_generation import CreativeGenerationError, generate_creative_package, generate_topic_for_channel
 from integrations.platforms import IntegrationResult, TikTokAdapter, YouTubeAdapter, fetch_channel_videos_public
 from integrations.postiz import PostizAdapter
@@ -204,6 +205,41 @@ def card(label: str, value: str | int, note: str = ""):
     st.markdown(f'<div class="content-card"><div class="content-label">{label}</div><div class="content-value">{value}</div><div class="small-muted">{note}</div></div>', unsafe_allow_html=True)
 
 
+def _library_card_key(kind: str, path: Path) -> str:
+    return hashlib.sha1(f"{kind}:{path.resolve()}".encode("utf-8")).hexdigest()[:12]
+
+
+def _render_library_name_editor(kind: str, path: Path, current_name: str) -> str:
+    """Render the inline name editor while keeping the physical filename unchanged."""
+    edit_key = f"rename_{kind}_{_library_card_key(kind, path)}"
+    if st.session_state.get(edit_key):
+        with st.form(f"{edit_key}_form", border=False):
+            edited_name = st.text_input("Nome de apresentação", value=current_name, max_chars=120, key=f"{edit_key}_input")
+            save_col, cancel_col = st.columns(2)
+            with save_col:
+                save_name = st.form_submit_button("Guardar nome", type="primary", use_container_width=True)
+            with cancel_col:
+                cancel_name = st.form_submit_button("Cancelar", use_container_width=True)
+        if save_name:
+            try:
+                set_display_name(kind, path, edited_name)
+                st.session_state.pop(edit_key, None)
+                st.success("Nome actualizado.")
+                st.rerun()
+            except ValueError as exc:
+                st.error(str(exc))
+        if cancel_name:
+            st.session_state.pop(edit_key, None)
+            st.rerun()
+    return edit_key
+
+
+def _render_card_pencil(edit_key: str) -> None:
+    if st.button("✏️", help="Editar nome de apresentação", key=f"pencil_{edit_key}", type="tertiary", use_container_width=True):
+        st.session_state[edit_key] = True
+        st.rerun()
+
+
 def channel_options() -> list[dict]:
     return [c for c in read_json("channels.json", []) if c.get("active", True)]
 
@@ -214,7 +250,7 @@ def blueprint_catalog() -> list[tuple[str, str]]:
         try:
             data = load_blueprint_file(path)
             identifier = str(data.get("id") or path.stem)
-            label = str(data.get("name") or path.stem)
+            label = get_display_name("blueprints", path, str(data.get("name") or data.get("title") or path.stem))
             options.append((identifier, label))
         except (OSError, ValueError, json.JSONDecodeError):
             continue
@@ -231,11 +267,11 @@ def blueprint_for_channel(channel: dict) -> dict[str, Any]:
             data = load_blueprint_file(path)
         except (OSError, ValueError, json.JSONDecodeError):
             continue
-        identifiers = {str(data.get("id") or ""), path.stem, str(data.get("name") or "")}
+        identifiers = {str(data.get("id") or ""), path.stem, str(data.get("name") or ""), get_display_name("blueprints", path, str(data.get("name") or path.stem))}
         if blueprint_id in identifiers:
             resolved = dict(data)
             resolved.setdefault("id", blueprint_id)
-            resolved.setdefault("name", str(data.get("name") or path.stem))
+            resolved["name"] = get_display_name("blueprints", path, str(data.get("name") or path.stem))
             return resolved
     return {"id": blueprint_id, "name": blueprint_id}
 
@@ -665,14 +701,21 @@ def render_blueprints():
         if not files:
             st.info("Ainda não existem blueprints na pasta local.")
         for path in files:
-            if search and search.lower() not in path.name.lower():
-                continue
             try:
                 data = load_blueprint_file(path)
-                title = data.get("channel_name") or data.get("name") or data.get("title") or path.stem
-                with st.expander(f"{title} — {path.relative_to(BLUEPRINTS)}"):
-                    st.caption(f"Ficheiro: {path}")
-                    st.json(data)
+                fallback_title = str(data.get("channel_name") or data.get("name") or data.get("title") or path.stem)
+                title = get_display_name("blueprints", path, fallback_title)
+                if search and search.lower() not in f"{title}\n{path.name}".lower():
+                    continue
+                card_key = _library_card_key("blueprints", path)
+                header_cols = st.columns([0.93, 0.07], vertical_alignment="center")
+                with header_cols[0]:
+                    with st.expander(f"{title} — {path.relative_to(BLUEPRINTS)}"):
+                        st.caption(f"Ficheiro: {path}")
+                        st.json(data)
+                with header_cols[1]:
+                    _render_card_pencil(f"rename_blueprints_{card_key}")
+                _render_library_name_editor("blueprints", path, title)
             except Exception as exc:
                 with st.expander(f"Inválido — {path.name}"):
                     st.error(str(exc))
@@ -752,7 +795,8 @@ def render_tiktok_prompt_masters():
                 content = load_prompt_master_file(path)
             except (OSError, ValueError):
                 content = ""
-            if search and search.lower() not in f"{path.name}\n{content}".lower():
+            display_heading = get_display_name("prompt_masters", path, next((line.lstrip("#").strip() for line in content.splitlines() if line.startswith("#")), path.stem))
+            if search and search.lower() not in f"{display_heading}\n{path.name}\n{content}".lower():
                 continue
             visible_files.append(path)
         if not visible_files:
@@ -760,24 +804,31 @@ def render_tiktok_prompt_masters():
         for path in visible_files:
             try:
                 content = load_prompt_master_file(path)
-                heading = next((line.lstrip("#").strip() for line in content.splitlines() if line.startswith("#")), path.stem)
-                with st.expander(f"{heading} — {path.name}", expanded=False):
-                    st.caption(f"Ficheiro TikTok: `{path}`")
-                    edited_content = st.text_area("Conteúdo Markdown", value=content, height=360, key=f"tiktok_prompt_master_editor_{path.stem}")
-                    prompt_cols = st.columns(3)
-                    with prompt_cols[0]:
-                        if st.button("Guardar alterações", type="primary", use_container_width=True, key=f"save_prompt_master_{path.stem}"):
-                            path.write_text(edited_content.rstrip() + "\n", encoding="utf-8")
-                            st.success("Prompt Master actualizado.")
-                            st.rerun()
-                    with prompt_cols[1]:
-                        st.download_button("Descarregar", data=content.encode("utf-8"), file_name=path.name, mime="text/markdown", use_container_width=True, key=f"download_prompt_master_{path.stem}")
-                    with prompt_cols[2]:
-                        if st.button("Apagar", use_container_width=True, key=f"delete_prompt_master_{path.stem}"):
-                            path.unlink(missing_ok=True)
-                            st.success("Prompt Master removido da biblioteca TikTok.")
-                            st.rerun()
-                    st.markdown(content)
+                fallback_heading = next((line.lstrip("#").strip() for line in content.splitlines() if line.startswith("#")), path.stem)
+                heading = get_display_name("prompt_masters", path, fallback_heading)
+                card_key = _library_card_key("prompt_masters", path)
+                header_cols = st.columns([0.93, 0.07], vertical_alignment="center")
+                with header_cols[0]:
+                    with st.expander(f"{heading} — {path.name}", expanded=False):
+                        st.caption(f"Ficheiro TikTok: `{path}`")
+                        edited_content = st.text_area("Conteúdo Markdown", value=content, height=360, key=f"tiktok_prompt_master_editor_{path.stem}")
+                        prompt_cols = st.columns(3)
+                        with prompt_cols[0]:
+                            if st.button("Guardar alterações", type="primary", use_container_width=True, key=f"save_prompt_master_{path.stem}"):
+                                path.write_text(edited_content.rstrip() + "\n", encoding="utf-8")
+                                st.success("Prompt Master actualizado.")
+                                st.rerun()
+                        with prompt_cols[1]:
+                            st.download_button("Descarregar", data=content.encode("utf-8"), file_name=path.name, mime="text/markdown", use_container_width=True, key=f"download_prompt_master_{path.stem}")
+                        with prompt_cols[2]:
+                            if st.button("Apagar", use_container_width=True, key=f"delete_prompt_master_{path.stem}"):
+                                path.unlink(missing_ok=True)
+                                st.success("Prompt Master removido da biblioteca TikTok.")
+                                st.rerun()
+                        st.markdown(content)
+                with header_cols[1]:
+                    _render_card_pencil(f"rename_prompt_masters_{card_key}")
+                _render_library_name_editor("prompt_masters", path, heading)
             except (OSError, ValueError) as exc:
                 with st.expander(f"Ficheiro inválido — {path.name}"):
                     st.error(str(exc))
@@ -1317,11 +1368,30 @@ def render_new_video(page_title: str = "Criação de Vídeos"):
                         if variants:
                             labels = [f"{idx + 1}. {item.get('concept', 'Variante')}" for idx, item in enumerate(variants)]
                             selected_variant_label = st.selectbox("Thumbnail escolhida", labels, key=f"new_video_general_thumbnail_{channel['id']}")
-                            variant = variants[labels.index(selected_variant_label)]
+                            variant_index = labels.index(selected_variant_label)
+                            variant = variants[variant_index]
                             payload["thumbnail_variant"] = variant
                             payload["thumbnail_prompt"] = variant.get("image_prompt", "")
                             payload["thumbnail_text"] = variant.get("overlay_text", "")
                             st.caption(f"{variant.get('composition', '')} · {variant.get('color_palette', '')}")
+                            thumbnail_path = str(variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
+                            if st.button("Gerar imagem com Nano Banana", key=f"new_video_general_generate_thumbnail_{channel['id']}", use_container_width=True):
+                                try:
+                                    thumbnail_path = str(generate_thumbnail_image(read_json("settings.json", {}), variant.get("image_prompt", ""), topic=str(payload.get("topic") or ""), variant_index=variant_index))
+                                    variant["image_path"] = thumbnail_path
+                                    payload["thumbnail_path"] = thumbnail_path
+                                    payload["thumbnail_status"] = "generated"
+                                    st.session_state["new_video_general_payloads"] = payloads
+                                    st.success("Thumbnail gerada com Nano Banana.")
+                                    st.rerun()
+                                except ThumbnailGenerationError as exc:
+                                    st.error(str(exc))
+                            if thumbnail_path and Path(thumbnail_path).is_file():
+                                st.image(thumbnail_path, caption="Thumbnail gerada pelo Nano Banana", use_container_width=True)
+                                payload["thumbnail_path"] = thumbnail_path
+                                payload["thumbnail_status"] = "generated"
+                            else:
+                                st.caption("A imagem ainda não foi gerada. Configure a API key em Configurações Técnicas > API Keys.")
                         st.caption(f"Estado da thumbnail: {payload.get('thumbnail_status', 'prompt_ready')} · texto: {payload.get('thumbnail_text') or 'sem texto'}")
             else:
                 topic_for_creative = str(st.session_state.get("new_video_topic", "") or "").strip()
@@ -1351,13 +1421,31 @@ def render_new_video(page_title: str = "Criação de Vídeos"):
                     if variants:
                         labels = [f"{idx + 1}. {item.get('concept', 'Variante')}" for idx, item in enumerate(variants)]
                         selected_variant_label = st.selectbox("Thumbnail escolhida", labels, key="new_video_thumbnail_choice")
-                        variant = variants[labels.index(selected_variant_label)]
+                        variant_index = labels.index(selected_variant_label)
+                        variant = variants[variant_index]
                         payload["thumbnail_variant"] = variant
                         payload["thumbnail_prompt"] = variant.get("image_prompt", "")
                         payload["thumbnail_text"] = variant.get("overlay_text", "")
                         st.caption(f"Composição: {variant.get('composition', '')} · Cores: {variant.get('color_palette', '')}")
                         st.code(variant.get("image_prompt", ""), language="text")
-                        st.info("Prompt de thumbnail pronto — a imagem será criada quando existir um provider de imagem configurado; não é criado um ficheiro falso.")
+                        thumbnail_path = str(variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
+                        if st.button("Gerar imagem da thumbnail com Nano Banana", key="new_video_generate_thumbnail_image", use_container_width=True):
+                            try:
+                                thumbnail_path = str(generate_thumbnail_image(read_json("settings.json", {}), variant.get("image_prompt", ""), topic=str(payload.get("topic") or ""), variant_index=variant_index))
+                                variant["image_path"] = thumbnail_path
+                                payload["thumbnail_path"] = thumbnail_path
+                                payload["thumbnail_status"] = "generated"
+                                st.session_state["new_video_creative_payload"] = payload
+                                st.success("Thumbnail gerada com Nano Banana.")
+                                st.rerun()
+                            except ThumbnailGenerationError as exc:
+                                st.error(str(exc))
+                        if thumbnail_path and Path(thumbnail_path).is_file():
+                            st.image(thumbnail_path, caption="Thumbnail gerada pelo Nano Banana", use_container_width=True)
+                            payload["thumbnail_path"] = thumbnail_path
+                            payload["thumbnail_status"] = "generated"
+                        else:
+                            st.info("Escolha a variante e clique em **Gerar imagem da thumbnail com Nano Banana**. A API key é configurada em Configurações Técnicas > API Keys.")
                     st.session_state["new_video_creative_payload"] = payload
 
             with st.form("new_video_form"):
@@ -2873,6 +2961,16 @@ def render_settings():
                     proxy_https = text_setting("Proxy HTTPS", "proxy_https")
                     match_materials_to_script = st.checkbox("Alinhar materiais ao roteiro", bool(settings.get("match_materials_to_script", False)))
 
+            with st.expander("Nano Banana — geração de thumbnails", expanded=True):
+                st.caption("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_cols = st.columns(2)
+                with nano_cols[0]:
+                    gemini_image_api_key = text_setting("Nano Banana API key", "gemini_image_api_key", secret=True, help_text="Chave criada no Google AI Studio para a API Gemini. Nunca é incluída no código, logs ou pacote.")
+                    gemini_image_model = st.selectbox("Modelo Nano Banana", ["gemini-3.1-flash-image", "gemini-3-pro-image", "gemini-2.5-flash-image"], index=["gemini-3.1-flash-image", "gemini-3-pro-image", "gemini-2.5-flash-image"].index(str(settings.get("gemini_image_model") or "gemini-3.1-flash-image")) if str(settings.get("gemini_image_model") or "gemini-3.1-flash-image") in {"gemini-3.1-flash-image", "gemini-3-pro-image", "gemini-2.5-flash-image"} else 0)
+                with nano_cols[1]:
+                    gemini_image_aspect_ratio = st.selectbox("Proporção da thumbnail", ["16:9", "9:16", "1:1", "4:5"], index=["16:9", "9:16", "1:1", "4:5"].index(str(settings.get("gemini_image_aspect_ratio") or "16:9")) if str(settings.get("gemini_image_aspect_ratio") or "16:9") in {"16:9", "9:16", "1:1", "4:5"} else 0)
+                    gemini_image_size = st.selectbox("Tamanho da imagem", ["1K", "2K", "4K"], index=["1K", "2K", "4K"].index(str(settings.get("gemini_image_size") or "1K")) if str(settings.get("gemini_image_size") or "1K") in {"1K", "2K", "4K"} else 0)
+
             with st.expander("LLM — providers e modelos", expanded=True):
                 provider_options = ["moonshot", "shengsuanyun", "openai", "gemini", "deepseek", "qwen", "azure", "volcengine", "grok", "minimax", "mimo", "cloudflare", "modelscope", "aihubmix", "aimlapi", "evolink", "ollama", "oneapi", "litellm", "groq", "pollinations"]
                 llm_provider = st.selectbox("LLM provider", provider_options, index=provider_options.index(settings.get("llm_provider", "moonshot")) if settings.get("llm_provider", "moonshot") in provider_options else 0)
@@ -3013,6 +3111,7 @@ def render_settings():
                     "log_level": log_level, "listen_host": listen_host, "listen_port": listen_port, "video_source": video_source,
                     "endpoint": endpoint, "proxy_http": proxy_http, "proxy_https": proxy_https, "match_materials_to_script": match_materials_to_script,
                     "llm_provider": llm_provider, "openai_api_key": openai_api_key, "openai_base_url": openai_base_url, "openai_model_name": openai_model_name,
+                    "gemini_image_api_key": gemini_image_api_key, "gemini_image_model": gemini_image_model, "gemini_image_aspect_ratio": gemini_image_aspect_ratio, "gemini_image_size": gemini_image_size,
                     "azure_speech_key": azure_speech_key, "azure_speech_region": azure_speech_region,
                     "siliconflow_tts_api_key": siliconflow_tts_api_key, "minimax_tts_api_key": minimax_tts_api_key,
                     "minimax_tts_base_url": minimax_tts_base_url, "minimax_tts_model_id": minimax_tts_model_id, "minimax_tts_voice_id": minimax_tts_voice_id,

package/hermes_ui/storage.py

@@ -24,6 +24,7 @@ DEFAULTS: dict[str, Any] = {
     "queues.json": {"niche": [], "blueprint": [], "brand": [], "script": [], "title": [], "thumbnail": [], "video": [], "edit": [], "upload": []},
     "batches.json": [],
     "uploads.json": [],
+    "display_names.json": {"blueprints": {}, "prompt_masters": {}},
     "niche_apify_runs.json": [],
     "metadata_edits.json": [],
         "python_editor_edits.json": [],
@@ -108,6 +109,10 @@ DEFAULTS: dict[str, Any] = {
         "openai_model_name": "",
         "gemini_api_key": "",
         "gemini_model_name": "",
+        "gemini_image_api_key": "",
+        "gemini_image_model": "gemini-3.1-flash-image",
+        "gemini_image_aspect_ratio": "16:9",
+        "gemini_image_size": "1K",
         "deepseek_api_key": "",
         "deepseek_base_url": "",
         "deepseek_model_name": "",
@@ -306,6 +311,53 @@ def append_json(name: str, item: dict[str, Any]) -> dict[str, Any]:
     return item
 
 
+def _display_name_key(kind: str, path: Path) -> str:
+    """Return a stable storage-relative key without renaming the physical file."""
+    resolved = path.resolve()
+    if kind == "blueprints":
+        root = BLUEPRINTS.resolve()
+        try:
+            return resolved.relative_to(root).as_posix()
+        except ValueError as exc:
+            raise ValueError("O ficheiro não pertence ao storage de Blueprints.") from exc
+    if kind == "prompt_masters":
+        root = TIKTOK_PROMPT_MASTERS.resolve()
+        try:
+            return resolved.relative_to(root).as_posix()
+        except ValueError as exc:
+            raise ValueError("O ficheiro não pertence ao storage de Prompt Masters.") from exc
+    raise ValueError(f"Tipo de biblioteca inválido: {kind}")
+
+
+def get_display_name(kind: str, path: Path, fallback: str) -> str:
+    names = read_json("display_names.json", {"blueprints": {}, "prompt_masters": {}})
+    if not isinstance(names, dict):
+        return fallback
+    entries = names.get(kind, {})
+    if not isinstance(entries, dict):
+        return fallback
+    value = str(entries.get(_display_name_key(kind, path)) or "").strip()
+    return value or fallback
+
+
+def set_display_name(kind: str, path: Path, name: str) -> str:
+    clean_name = " ".join(str(name).split()).strip()
+    if not clean_name:
+        raise ValueError("Informe um nome para a biblioteca.")
+    if len(clean_name) > 120:
+        raise ValueError("O nome deve ter no máximo 120 caracteres.")
+    names = read_json("display_names.json", {"blueprints": {}, "prompt_masters": {}})
+    if not isinstance(names, dict):
+        names = {"blueprints": {}, "prompt_masters": {}}
+    entries = names.get(kind)
+    if not isinstance(entries, dict):
+        entries = {}
+        names[kind] = entries
+    entries[_display_name_key(kind, path)] = clean_name
+    write_json("display_names.json", names)
+    return clean_name
+
+
 def list_blueprint_files() -> list[Path]:
     ensure_storage()
     return sorted(BLUEPRINTS.rglob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)

package/hermes_ui/thumbnail_generation.py

@@ -0,0 +1,158 @@
+import base64
+import binascii
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from hermes_ui.storage import STORAGE, ensure_storage
+
+
+GEMINI_INTERACTIONS_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/interactions"
+DEFAULT_GEMINI_IMAGE_MODEL = "gemini-3.1-flash-image"
+DEFAULT_ASPECT_RATIO = "16:9"
+DEFAULT_IMAGE_SIZE = "1K"
+DEFAULT_MIME_TYPE = "image/jpeg"
+DEFAULT_IMAGE_EXTENSION = ".jpg"
+
+
+class ThumbnailGenerationError(RuntimeError):
+    """Raised when Nano Banana cannot produce a thumbnail image."""
+
+
+def _clean_detail(value: Any, api_key: str) -> str:
+    detail = str(value or "").strip()[:600]
+    return detail.replace(api_key, "[REDACTED]") if api_key else detail
+
+
+def _decode_image_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:
+        data = base64.b64decode(raw, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+    return data or None
+
+
+def _image_from_content(content: Any) -> bytes | None:
+    if not isinstance(content, dict) or content.get("type") != "image":
+        return None
+    return _decode_image_data(content.get("data"))
+
+
+def _extract_image_bytes(payload: dict[str, Any]) -> bytes:
+    """Extract the last inline image from an Interactions API response."""
+    steps = payload.get("steps") or []
+    for step in reversed(steps if isinstance(steps, list) else []):
+        content = step.get("content") if isinstance(step, dict) else None
+        for block in reversed(content if isinstance(content, list) else []):
+            image = _image_from_content(block)
+            if image:
+                return image
+
+    output_image = payload.get("output_image")
+    image = _image_from_content(output_image)
+    if image:
+        return image
+
+    outputs = payload.get("outputs")
+    for output in reversed(outputs if isinstance(outputs, list) else []):
+        image = _image_from_content(output)
+        if image:
+            return image
+
+    raise ThumbnailGenerationError("O Gemini concluiu a interação, mas não devolveu uma imagem inline.")
+
+
+def _thumbnail_filename(prompt: str, topic: str, variant_index: int, model: str) -> str:
+    source = f"{model}\n{topic.strip()}\n{variant_index}\n{prompt.strip()}".encode("utf-8")
+    digest = hashlib.sha256(source).hexdigest()[:20]
+    return f"gemini-thumbnail-{digest}{DEFAULT_IMAGE_EXTENSION}"
+
+
+def generate_thumbnail_image(
+    settings: dict[str, Any],
+    prompt: str,
+    *,
+    topic: str = "",
+    variant_index: int = 0,
+) -> Path:
+    api_key = str(settings.get("gemini_image_api_key") or "").strip()
+    if not api_key:
+        raise ThumbnailGenerationError("Configure a API key Nano Banana em Configurações Técnicas > API Keys.")
+    clean_prompt = str(prompt or "").strip()
+    if not clean_prompt:
+        raise ThumbnailGenerationError("A thumbnail não tem um prompt de imagem para gerar.")
+
+    model = str(settings.get("gemini_image_model") or DEFAULT_GEMINI_IMAGE_MODEL).strip()
+    aspect_ratio = str(settings.get("gemini_image_aspect_ratio") or DEFAULT_ASPECT_RATIO).strip()
+    image_size = str(settings.get("gemini_image_size") or DEFAULT_IMAGE_SIZE).strip()
+    body = {
+        "model": model,
+        "input": clean_prompt,
+        "response_format": {
+            "type": "image",
+            "mime_type": DEFAULT_MIME_TYPE,
+            "delivery": "inline",
+            "aspect_ratio": aspect_ratio,
+            "image_size": image_size,
+        },
+        "store": False,
+    }
+    headers = {"Content-Type": "application/json", "x-goog-api-key": api_key}
+    try:
+        response = requests.post(
+            GEMINI_INTERACTIONS_ENDPOINT,
+            headers=headers,
+            json=body,
+            timeout=180,
+        )
+    except requests.RequestException as exc:
+        raise ThumbnailGenerationError(f"Não foi possível contactar a API Nano Banana: {exc}") from exc
+    if response.status_code >= 400:
+        try:
+            detail = response.json().get("error", response.text)
+        except ValueError:
+            detail = response.text
+        raise ThumbnailGenerationError(f"A API Nano Banana devolveu HTTP {response.status_code}: {_clean_detail(detail, api_key)}")
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ThumbnailGenerationError("A API Nano Banana devolveu uma resposta que não é JSON.") from exc
+    if str(payload.get("status") or "completed").lower() not in {"completed", "succeeded"}:
+        raise ThumbnailGenerationError(f"A interação Nano Banana terminou com estado inesperado: {payload.get('status') or 'desconhecido'}.")
+    image_bytes = _extract_image_bytes(payload)
+
+    ensure_storage()
+    output_dir = STORAGE / "thumbnails"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    destination = output_dir / _thumbnail_filename(clean_prompt, topic, variant_index, model)
+    fd, temp_name = tempfile.mkstemp(prefix=f".{destination.name}.", dir=output_dir)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(image_bytes)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, destination)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+    return destination
+
+
+__all__ = [
+    "DEFAULT_ASPECT_RATIO",
+    "DEFAULT_GEMINI_IMAGE_MODEL",
+    "DEFAULT_IMAGE_SIZE",
+    "GEMINI_INTERACTIONS_ENDPOINT",
+    "ThumbnailGenerationError",
+    "generate_thumbnail_image",
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",