@danhachuel/thunderbolt 0.3.24 → 0.3.26

package/app/main.py

@@ -46,9 +46,17 @@ from hermes_ui.script_documents import list_script_documents, read_script_docume
 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.thumbnails import list_thumbnail_tasks, regenerate_thumbnail
+from hermes_ui.thumbnails import (
+    generate_thumbnail_for_task,
+    list_thumbnail_tasks,
+    regenerate_thumbnail,
+    regenerate_thumbnail_lettering,
+    regenerate_thumbnail_prompt,
+    regenerate_thumbnail_prompt_and_image,
+    upload_thumbnail_image,
+)
 from hermes_ui.draft_video import DRAFT_SETTING_SECTIONS, missing_content_fields, missing_setting_sections, normalise_saved_script, setting_widget_suffixes
-from hermes_ui.creative_generation import CreativeGenerationError, generate_creative_package, generate_topic_for_channel, generate_video_keywords
+from hermes_ui.creative_generation import CreativeGenerationError, generate_creative_package, generate_thumbnail_prompt, generate_topic_for_channel, generate_video_keywords
 from integrations.platforms import IntegrationResult, TikTokAdapter, YouTubeAdapter, fetch_channel_videos_public
 from integrations.tiktok_public import fetch_public_tiktok_profile, normalize_tiktok_reference
 from integrations.postiz import PostizAdapter
@@ -2144,7 +2152,16 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                             thumbnail_path = str(variant.get("image_path") or payload.get("thumbnail_path") or "").strip()
                             if st.button("Gerar imagem com Nano Banana", key=f"{prefix}_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))
+                                    thumbnail_path = str(
+                                        generate_thumbnail_image(
+                                            read_json("settings.json", {}),
+                                            variant.get("image_prompt", ""),
+                                            topic=str(payload.get("topic") or ""),
+                                            variant_index=variant_index,
+                                            lettering_text=str(variant.get("overlay_text") or payload.get("thumbnail_text") or ""),
+                                            lettering_prompt=str(variant.get("lettering_prompt") or ""),
+                                        )
+                                    )
                                     variant["image_path"] = thumbnail_path
                                     payload["thumbnail_path"] = thumbnail_path
                                     payload["thumbnail_status"] = "generated"
@@ -2208,7 +2225,16 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                         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=f"{prefix}_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))
+                                thumbnail_path = str(
+                                    generate_thumbnail_image(
+                                        read_json("settings.json", {}),
+                                        variant.get("image_prompt", ""),
+                                        topic=str(payload.get("topic") or ""),
+                                        variant_index=variant_index,
+                                        lettering_text=str(variant.get("overlay_text") or payload.get("thumbnail_text") or ""),
+                                        lettering_prompt=str(variant.get("lettering_prompt") or ""),
+                                    )
+                                )
                                 variant["image_path"] = thumbnail_path
                                 payload["thumbnail_path"] = thumbnail_path
                                 payload["thumbnail_status"] = "generated"
@@ -3215,9 +3241,31 @@ def render_videos():
                         st.rerun()
 
 
+def _thumbnail_editor_context(record: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Resolve the persisted task channel/Blueprint without requiring either one to remain registered."""
+    channel_id = str(record.get("channel_id") or "").strip()
+    channels = read_json("channels.json", [])
+    channel = next(
+        (item for item in channels if isinstance(item, dict) and str(item.get("id") or "") == channel_id),
+        None,
+    ) if isinstance(channels, list) else None
+    if not channel:
+        channel = {
+            "id": channel_id,
+            "name": record.get("channel_name") or "Canal sem nome",
+            "language": record.get("language") or "Português",
+            "default_blueprint_id": record.get("blueprint_id") or "",
+            "blueprint_id": record.get("blueprint_id") or "",
+        }
+    blueprint = blueprint_for_channel(channel)
+    if not blueprint and record.get("blueprint_id"):
+        blueprint = {"id": record.get("blueprint_id"), "name": record.get("blueprint_name") or record.get("blueprint_id")}
+    return channel, blueprint
+
+
 def render_thumbnails():
     st.title("Thumbnails")
-    st.caption("Biblioteca de thumbnails associadas às tarefas da pipeline. A refacção actualiza apenas a imagem da tarefa e preserva o histórico local.")
+    st.caption("Biblioteca de thumbnails associadas às tarefas da pipeline. Cada acção preserva a imagem anterior no histórico local.")
     records = list_thumbnail_tasks()
     if not records:
         st.info("Ainda não existem tarefas com thumbnail gerada ou prompt de imagem disponível.")
@@ -3225,8 +3273,9 @@ def render_thumbnails():
 
     settings = read_json("settings.json", {})
     for record in records:
+        task_id = record["task_id"]
         with st.container(border=True):
-            image_col, details_col, action_col = st.columns([1.35, 2.65, 1.25])
+            image_col, details_col, action_col = st.columns([1.25, 2.35, 1.7])
             with image_col:
                 image_path = record.get("image_path")
                 if image_path and image_path.is_file():
@@ -3236,32 +3285,157 @@ def render_thumbnails():
                     st.caption("Imagem ainda não gerada")
             with details_col:
                 st.write(f"**{record['title']}**")
-                st.caption(f"Canal: {record['channel_name']} · Tarefa: {record['task_id']}")
+                st.caption(f"Canal: {record['channel_name']} · Tarefa: {task_id}")
                 st.caption(f"Estado: {record['status']} · Variante: {record['variant_index'] + 1}")
                 if record["prompt"]:
                     with st.expander("Ver prompt da thumbnail", expanded=False):
                         st.code(record["prompt"], language="text")
                 else:
-                    st.warning("Esta tarefa não tem prompt de imagem. Não é possível refazer a thumbnail.")
+                    st.warning("A thumbnail não tem um prompt de imagem para gerar.")
+
             with action_col:
                 if st.button(
-                    "Refazer thumbnail",
-                    key=f"regenerate_thumbnail_{record['task_id']}",
+                    "Refazer Prompt Thumb",
+                    key=f"regenerate_thumbnail_{task_id}",
                     icon=":material/refresh:",
                     use_container_width=True,
+                    disabled=not bool(record["title"] or record["topic"]),
+                ):
+                    try:
+                        with st.spinner("A refazer apenas o prompt da thumbnail…"):
+                            channel, blueprint = _thumbnail_editor_context(record)
+                            _task, prompt_variant = regenerate_thumbnail_prompt(
+                                task_id,
+                                settings,
+                                channel,
+                                blueprint=blueprint,
+                                language=str(record.get("language") or current_ui_language()),
+                            )
+                        record_notification(
+                            "thumbnail_generation_completed",
+                            "Prompt da thumbnail refeito",
+                            "Prompt da thumbnail actualizado; a imagem existente foi preservada.",
+                            metadata={
+                                "task_id": task_id,
+                                "channel_name": record["channel_name"],
+                                "prompt_regenerated": True,
+                                "prompt_only": True,
+                                "image_path": str(record.get("image_path") or ""),
+                            },
+                            dedupe_key=f"thumbnail:prompt-only:{task_id}:{prompt_variant.get('image_prompt', '')}",
+                        )
+                        st.success("Prompt da thumbnail actualizado; a imagem existente foi preservada.")
+                        st.rerun()
+                    except (CreativeGenerationError, ThumbnailGenerationError) as exc:
+                        st.error(str(exc))
+
+                if st.button(
+                    "Gerar Imagem",
+                    key=f"generate_thumbnail_image_{task_id}",
+                    icon=":material/image:",
+                    use_container_width=True,
                     disabled=not bool(record["prompt"]),
                 ):
                     try:
-                        with st.spinner("A refazer a thumbnail…"):
-                            _task, image_path = regenerate_thumbnail(record["task_id"], settings)
+                        with st.spinner("A gerar a imagem com Nano Banana…"):
+                            _task, generated_path = generate_thumbnail_for_task(task_id, settings)
+                        record_notification(
+                            "thumbnail_generation_completed",
+                            f"Thumbnail gerada: {record['title']}",
+                            "Thumbnail gerada com sucesso.",
+                            metadata={"task_id": task_id, "channel_name": record["channel_name"], "image_path": str(generated_path)},
+                            dedupe_key=f"thumbnail:generated:{task_id}:{generated_path}",
+                        )
+                        st.success("Thumbnail gerada com sucesso.")
+                        st.rerun()
+                    except ThumbnailGenerationError as exc:
+                        st.error(str(exc))
+
+                if st.button(
+                    "Refazer Prompt e Gerar Imagem",
+                    key=f"regenerate_thumbnail_prompt_{task_id}",
+                    icon=":material/auto_awesome:",
+                    use_container_width=True,
+                    disabled=not bool(record["title"] or record["topic"]),
+                ):
+                    try:
+                        with st.spinner("A refazer o prompt e a imagem…"):
+                            channel, blueprint = _thumbnail_editor_context(record)
+                            variant = generate_thumbnail_prompt(
+                                settings,
+                                channel,
+                                record["title"] or record["topic"],
+                                current_prompt=record["prompt"],
+                                blueprint=blueprint,
+                                language=str(record.get("language") or current_ui_language()),
+                            )
+                            _task, generated_path = regenerate_thumbnail_prompt_and_image(task_id, settings, variant)
+                        record_notification(
+                            "thumbnail_generation_completed",
+                            f"Thumbnail renovada: {record['title']}",
+                            "Prompt da thumbnail e imagem actualizados.",
+                            metadata={"task_id": task_id, "channel_name": record["channel_name"], "image_path": str(generated_path), "prompt_regenerated": True},
+                            dedupe_key=f"thumbnail:prompt-regenerated:{task_id}:{generated_path}",
+                        )
+                        st.success("Prompt da thumbnail e imagem actualizados.")
+                        st.rerun()
+                    except (CreativeGenerationError, ThumbnailGenerationError) as exc:
+                        st.error(str(exc))
+
+                if st.button(
+                    "Refazer Lettering",
+                    key=f"regenerate_thumbnail_lettering_{task_id}",
+                    icon=":material/title:",
+                    use_container_width=True,
+                    disabled=not bool(record.get("image_path") and record["image_path"].is_file()),
+                ):
+                    try:
+                        with st.spinner("A refazer apenas o lettering…"):
+                            _task, generated_path = regenerate_thumbnail_lettering(
+                                task_id,
+                                settings,
+                                lettering_prompt=record.get("lettering_prompt") or "",
+                            )
+                        record_notification(
+                            "thumbnail_generation_completed",
+                            f"Lettering refeito: {record['title']}",
+                            "Lettering refeito; a imagem original foi usada como base.",
+                            metadata={"task_id": task_id, "channel_name": record["channel_name"], "image_path": str(generated_path), "lettering_only": True},
+                            dedupe_key=f"thumbnail:lettering:{task_id}:{generated_path}",
+                        )
+                        st.success("Lettering refeito; a imagem original foi usada como base.")
+                        st.rerun()
+                    except ThumbnailGenerationError as exc:
+                        st.error(str(exc))
+
+            uploaded = st.file_uploader(
+                "Upload Image",
+                type=["png", "jpg", "jpeg", "webp"],
+                key=f"thumbnail_upload_{task_id}",
+                help="Suba uma imagem para a associar a esta tarefa e à pipeline.",
+            )
+            if uploaded is not None:
+                uploaded_bytes = uploaded.getvalue()
+                uploaded_digest = hashlib.sha256(uploaded_bytes).hexdigest()
+                digest_key = f"thumbnail_upload_digest_{task_id}"
+                if st.session_state.get(digest_key) != uploaded_digest:
+                    try:
+                        with st.spinner("A guardar a imagem carregada…"):
+                            _task, uploaded_path = upload_thumbnail_image(
+                                task_id,
+                                uploaded_bytes,
+                                uploaded.name,
+                                uploaded.type,
+                            )
+                        st.session_state[digest_key] = uploaded_digest
                         record_notification(
                             "thumbnail_generation_completed",
-                            f"Thumbnail refeita: {record['title']}",
-                            "A thumbnail da tarefa foi regenerada com sucesso.",
-                            metadata={"task_id": record["task_id"], "channel_name": record["channel_name"], "image_path": str(image_path)},
-                            dedupe_key=f"thumbnail:regenerated:{record['task_id']}:{image_path}",
+                            f"Thumbnail carregada: {record['title']}",
+                            "Imagem carregada e vinculada à tarefa.",
+                            metadata={"task_id": task_id, "channel_name": record["channel_name"], "image_path": str(uploaded_path), "source": "upload"},
+                            dedupe_key=f"thumbnail:uploaded:{task_id}:{uploaded_digest}",
                         )
-                        st.success("Thumbnail refeita com sucesso.")
+                        st.success("Imagem carregada e vinculada à tarefa.")
                         st.rerun()
                     except ThumbnailGenerationError as exc:
                         st.error(str(exc))

package/hermes_ui/creative_generation.py

@@ -249,6 +249,64 @@ def _keywords_from_text(*values: str) -> list[str]:
     return result[:15]
 
 
+def generate_thumbnail_prompt(
+    settings: dict[str, Any],
+    channel: dict[str, Any],
+    topic: str,
+    current_prompt: str = "",
+    blueprint: dict[str, Any] | None = None,
+    language: str = "",
+) -> dict[str, Any]:
+    """Create one image prompt while keeping visual direction and lettering separate."""
+    topic = str(topic or "").strip()
+    if not topic:
+        raise CreativeGenerationError("É necessário um tópico para refazer o prompt da thumbnail.")
+    context = channel_context(channel, blueprint)
+    system = (
+        "És um director de arte de thumbnails para YouTube. Refaz um prompt de imagem forte e específico "
+        "para o tópico fornecido, mantendo a intenção visual quando já existir um prompt. "
+        "Separa rigorosamente a imagem sem texto do lettering: image_prompt nunca deve pedir texto renderizado, "
+        "enquanto overlay_text é obrigatório, deve ser curto, legível e ter entre três e quatro palavras. "
+        "Responde apenas com JSON válido nas chaves concept, overlay_text, composition, color_palette, subject, "
+        "image_prompt, title_synergy e lettering_prompt."
+    )
+    user = json.dumps(
+        {
+            "channel": context,
+            "language": language or context["language"],
+            "topic": topic,
+            "current_prompt": str(current_prompt or "").strip(),
+            "reference_rules": reference_bundle(),
+            "requirements": {
+                "image_prompt": "cinematic visual direction, no words, letters, logos or watermarks rendered in the image",
+                "overlay_text": "required, 3 to 4 words, emotionally strong, not the full title",
+                "lettering_prompt": "required instructions for rendering the exact overlay_text after the base image exists",
+            },
+        },
+        ensure_ascii=False,
+    )
+    result = _chat_json(settings, system, user)
+    image_prompt = str(result.get("image_prompt") or "").strip()
+    if not image_prompt:
+        raise CreativeGenerationError("O provider não devolveu um prompt de imagem válido.")
+    overlay_text = _short_overlay(result.get("overlay_text")) or _short_overlay(topic) or "WATCH NOW"
+    lettering_prompt = str(result.get("lettering_prompt") or "").strip() or (
+        "Render the exact overlay_text as bold, readable, high-contrast sans-serif lettering with an outline or shadow, "
+        "inside a safe zone and away from the main face or subject."
+    )
+    return {
+        "concept": str(result.get("concept") or "Thumbnail renovada").strip(),
+        "overlay_text": overlay_text,
+        "composition": str(result.get("composition") or "").strip(),
+        "color_palette": str(result.get("color_palette") or "").strip(),
+        "subject": str(result.get("subject") or topic).strip(),
+        "image_prompt": image_prompt,
+        "title_synergy": str(result.get("title_synergy") or "").strip(),
+        "lettering_prompt": lettering_prompt,
+        "status": "prompt_ready",
+    }
+
+
 def generate_creative_package(
     settings: dict[str, Any],
     channel: dict[str, Any],
@@ -263,7 +321,7 @@ def generate_creative_package(
         "És director editorial e de thumbnails para YouTube. Cria um pacote coerente de título e thumbnail "
         "para o tópico fornecido. Gera exactamente pelo menos 20 títulos candidatos e entre 3 e 5 variantes de thumbnail. "
         "O título deve carregar keywords no início, ter curiosidade, especificidade e emoção, sem clickbait falso. "
-        "A thumbnail deve ter no máximo três elementos, alto contraste, uma composição clara, texto opcional de até 4 palavras, "
+        "A thumbnail deve ter no máximo três elementos, alto contraste, uma composição clara e lettering obrigatório de 3 a 4 palavras, "
         "safe zones e leitura em 120px. O texto da thumbnail não pode repetir o título integralmente. Remove AI tells. "
         "Responde apenas com JSON válido nas chaves selected_title, title_candidates, keywords e thumbnail_variants."
     )
@@ -283,12 +341,13 @@ def generate_creative_package(
             },
             "thumbnail_variant_schema": {
                 "concept": "string",
-                "overlay_text": "string, maximum 4 words",
+                "overlay_text": "required string, 3 to 4 words",
                 "composition": "string",
                 "color_palette": "string",
                 "subject": "string",
-                "image_prompt": "string, no text rendered in the image",
+                "image_prompt": "string describing the clean image base, without rendered text; lettering is specified separately",
                 "title_synergy": "string",
+                "lettering_prompt": "string describing how to render the exact overlay_text",
             },
         },
         ensure_ascii=False,
@@ -330,15 +389,21 @@ def generate_creative_package(
             continue
         if not str(item.get("concept") or "").strip() or not str(item.get("image_prompt") or "").strip():
             continue
+        overlay_text = _short_overlay(item.get("overlay_text")) or _short_overlay(topic) or "WATCH NOW"
+        lettering_prompt = str(item.get("lettering_prompt") or "").strip() or (
+            "Render the exact overlay_text as bold, readable, high-contrast sans-serif lettering with an outline or shadow, "
+            "inside a safe zone and away from the main face or subject."
+        )
         variants.append(
             {
                 "concept": str(item.get("concept") or "").strip(),
-                "overlay_text": _short_overlay(item.get("overlay_text")),
+                "overlay_text": overlay_text,
                 "composition": str(item.get("composition") or "").strip(),
                 "color_palette": str(item.get("color_palette") or "").strip(),
                 "subject": str(item.get("subject") or "").strip(),
                 "image_prompt": str(item.get("image_prompt") or "").strip(),
                 "title_synergy": str(item.get("title_synergy") or "").strip(),
+                "lettering_prompt": lettering_prompt,
                 "status": "prompt_ready",
             }
         )

package/hermes_ui/languages.py

@@ -934,6 +934,35 @@ _CONTENT_TRANSLATION_ROWS = (
     ("Modo de ligação", "Modo de ligação", "Connection mode", "连接模式", "Verbindungsmodus", "Chế độ kết nối", "Bağlantı modu", "Режим подключения", "Modo de conexión", "Mode koneksi", "Modalità di connessione"),
     ("Metadados removidos e nova cópia criada. O original continua preservado.", "Metadados removidos e nova cópia criada. O original continua preservado.", "Metadata removed and a new copy created. The original remains preserved.", "元数据已移除并创建新副本。原文件仍然保留。", "Metadaten entfernt und eine neue Kopie erstellt. Das Original bleibt erhalten.", "Đã xóa siêu dữ liệu và tạo bản sao mới. Bản gốc vẫn được giữ nguyên.", "Üst veriler kaldırıldı ve yeni bir kopya oluşturuldu. Orijinal korunur.", "Метаданные удалены и создана новая копия. Оригинал сохранён.", "Metadatos eliminados y nueva copia creada. El original se conserva.", "Metadata dihapus dan salinan baru dibuat. File asli tetap dipertahankan.", "Metadati rimossi e nuova copia creata. L'originale è preservato."),
     ("Detalhes da conta Google", "Detalhes da conta Google", "Google account details", "Google 账户详情", "Details des Google-Kontos", "Chi tiết tài khoản Google", "Google hesap ayrıntıları", "Сведения об аккаунте Google", "Detalles de la cuenta de Google", "Detail akun Google", "Dettagli dell'account Google"),
+    ("Refazer Prompt Thumb", "Refazer Prompt Thumb", "Regenerate Thumbnail Prompt", "重新生成缩略图提示词", "Thumbnail-Prompt neu erstellen", "Tạo lại prompt thumbnail", "Küçük resim istemini yeniden oluştur", "Перегенерировать промпт миниатюры", "Regenerar prompt de miniatura", "Buat ulang prompt thumbnail", "Rigenera prompt miniatura"),
+    ("Gerar Imagem", "Gerar Imagem", "Generate Image", "生成图片", "Bild generieren", "Tạo hình ảnh", "Görsel oluştur", "Создать изображение", "Generar imagen", "Buat gambar", "Genera immagine"),
+    ("Refazer Prompt e Gerar Imagem", "Refazer Prompt e Gerar Imagem", "Regenerate Prompt and Generate Image", "重新生成提示词并生成图片", "Prompt neu erstellen und Bild generieren", "Tạo lại prompt và hình ảnh", "İstemi Yeniden Oluştur ve Görseli Üret", "Перегенерировать промпт и создать изображение", "Regenerar prompt y generar imagen", "Buat Ulang Prompt dan Gambar", "Rigenera prompt e genera immagine"),
+    ("Refazer Lettering", "Refazer Lettering", "Regenerate Lettering", "重新生成文字", "Lettering neu erstellen", "Tạo lại chữ", "Yazıyı Yeniden Oluştur", "Перегенерировать надпись", "Regenerar lettering", "Buat ulang lettering", "Rigenera lettering"),
+    ("Upload Image", "Upload Image", "Upload Image", "上传图片", "Bild hochladen", "Tải hình ảnh lên", "Görsel Yükle", "Загрузить изображение", "Subir imagen", "Unggah gambar", "Carica immagine"),
+    ("A gerar a imagem com Nano Banana…", "A gerar a imagem com Nano Banana…", "Generating image with Nano Banana…", "正在使用 Nano Banana 生成图片…", "Bild wird mit Nano Banana generiert…", "Đang tạo ảnh bằng Nano Banana…", "Nano Banana ile görsel oluşturuluyor…", "Создание изображения с помощью Nano Banana…", "Generando imagen con Nano Banana…", "Membuat gambar dengan Nano Banana…", "Generazione immagine con Nano Banana…"),
+    ("A refazer o prompt e a imagem…", "A refazer o prompt e a imagem…", "Regenerating the prompt and image…", "正在重新生成提示词和图片…", "Prompt und Bild werden neu erstellt…", "Đang tạo lại prompt và hình ảnh…", "İstem ve görsel yeniden oluşturuluyor…", "Перегенерация промпта и изображения…", "Regenerando el prompt y la imagen…", "Membuat ulang prompt dan gambar…", "Rigenerazione del prompt e dell'immagine…"),
+    ("A refazer apenas o prompt da thumbnail…", "A refazer apenas o prompt da thumbnail…", "Regenerating only the thumbnail prompt…", "仅重新生成缩略图提示词…", "Nur der Thumbnail-Prompt wird neu erstellt…", "Chỉ tạo lại prompt thumbnail…", "Yalnızca küçük resim istemi yeniden oluşturuluyor…", "Перегенерация только промпта миниатюры…", "Regenerando solo el prompt de la miniatura…", "Membuat ulang prompt thumbnail saja…", "Rigenerazione del solo prompt della miniatura…"),
+    ("A refazer apenas o lettering…", "A refazer apenas o lettering…", "Regenerating only the lettering…", "仅重新生成文字…", "Nur das Lettering wird neu erstellt…", "Chỉ tạo lại chữ…", "Yalnızca yazı yeniden oluşturuluyor…", "Перегенерация только надписи…", "Regenerando solo el lettering…", "Membuat ulang lettering saja…", "Rigenerazione del solo lettering…"),
+    ("Prompt da thumbnail refeito", "Prompt da thumbnail refeito", "Thumbnail prompt regenerated", "缩略图提示词已重新生成", "Thumbnail-Prompt neu erstellt", "Đã tạo lại prompt thumbnail", "Küçük resim istemi yeniden oluşturuldu", "Промпт миниатюры перегенерирован", "Prompt de miniatura regenerado", "Prompt thumbnail dibuat ulang", "Prompt della miniatura rigenerato"),
+    ("Prompt da thumbnail actualizado; a imagem existente foi preservada.", "Prompt da thumbnail actualizado; a imagem existente foi preservada.", "Thumbnail prompt updated; the existing image was preserved.", "缩略图提示词已更新；现有图片已保留。", "Thumbnail-Prompt aktualisiert; das vorhandene Bild wurde beibehalten.", "Đã cập nhật prompt thumbnail; ảnh hiện tại được giữ nguyên.", "Küçük resim istemi güncellendi; mevcut görsel korundu.", "Промпт миниатюры обновлён; существующее изображение сохранено.", "Prompt de miniatura actualizado; la imagen existente se conservó.", "Prompt thumbnail diperbarui; gambar yang ada dipertahankan.", "Prompt della miniatura aggiornato; l'immagine esistente è stata preservata."),
+    ("Thumbnail gerada com sucesso.", "Thumbnail gerada com sucesso.", "Thumbnail generated successfully.", "缩略图生成成功。", "Thumbnail erfolgreich generiert.", "Đã tạo thumbnail thành công.", "Küçük resim başarıyla oluşturuldu.", "Миниатюра успешно создана.", "Miniatura generada correctamente.", "Thumbnail berhasil dibuat.", "Miniatura generata con successo."),
+    ("Prompt da thumbnail e imagem actualizados.", "Prompt da thumbnail e imagem actualizados.", "Thumbnail prompt and image updated.", "缩略图提示词和图片已更新。", "Thumbnail-Prompt und Bild aktualisiert.", "Đã cập nhật prompt và hình ảnh thumbnail.", "Küçük resim istemi ve görsel güncellendi.", "Промпт и изображение миниатюры обновлены.", "Prompt e imagen de miniatura actualizados.", "Prompt dan gambar thumbnail diperbarui.", "Prompt e immagine della miniatura aggiornati."),
+    ("Lettering refeito; a imagem original foi usada como base.", "Lettering refeito; a imagem original foi usada como base.", "Lettering regenerated; the original image was used as the base.", "文字已重新生成；原图用作基础。", "Lettering neu erstellt; das Originalbild wurde als Grundlage verwendet.", "Đã tạo lại chữ; ảnh gốc được dùng làm nền.", "Yazı yeniden oluşturuldu; orijinal görsel temel olarak kullanıldı.", "Надпись перегенерирована; исходное изображение использовано как основа.", "Lettering regenerado; la imagen original se usó como base.", "Lettering dibuat ulang; gambar asli digunakan sebagai dasar.", "Lettering rigenerato; l'immagine originale è stata usata come base."),
+    ("Imagem carregada e vinculada à tarefa.", "Imagem carregada e vinculada à tarefa.", "Image uploaded and linked to the task.", "图片已上传并关联到任务。", "Bild hochgeladen und mit der Aufgabe verknüpft.", "Đã tải ảnh lên và liên kết với tác vụ.", "Görsel yüklendi ve göreve bağlandı.", "Изображение загружено и привязано к задаче.", "Imagen subida y vinculada a la tarea.", "Gambar diunggah dan ditautkan ke tugas.", "Immagine caricata e collegata all'attività."),
+    ("A thumbnail não tem um prompt de imagem para gerar.", "A thumbnail não tem um prompt de imagem para gerar.", "This thumbnail has no image prompt to generate.", "此缩略图没有可生成的图片提示词。", "Für dieses Thumbnail ist kein Bild-Prompt zum Generieren vorhanden.", "Thumbnail này không có prompt hình ảnh để tạo.", "Bu küçük resim için oluşturulacak bir görsel istemi yok.", "У этой миниатюры нет промпта для создания изображения.", "Esta miniatura no tiene un prompt de imagen para generar.", "Thumbnail ini tidak memiliki prompt gambar untuk dibuat.", "Questa miniatura non ha un prompt immagine da generare."),
+    ("A thumbnail precisa de uma imagem existente para refazer o lettering.", "A thumbnail precisa de uma imagem existente para refazer o lettering.", "An existing image is required to regenerate the lettering.", "需要现有图片才能重新生成文字。", "Für die Neugenerierung des Letterings ist ein vorhandenes Bild erforderlich.", "Cần có ảnh hiện tại để tạo lại chữ.", "Lettering'i yeniden oluşturmak için mevcut bir görsel gerekir.", "Для перегенерации надписи требуется существующее изображение.", "Se necesita una imagen existente para regenerar el lettering.", "Diperlukan gambar yang ada untuk membuat ulang lettering.", "È necessaria un'immagine esistente per rigenerare il lettering."),
+    ("Thumbnails", "Thumbnails", "Thumbnails", "缩略图", "Thumbnails", "Thumbnails", "Küçük Resimler", "Миниатюры", "Miniaturas", "Thumbnail", "Miniature"),
+    ("Biblioteca de thumbnails associadas às tarefas da pipeline. Cada acção preserva a imagem anterior no histórico local.", "Biblioteca de thumbnails associadas às tarefas da pipeline. Cada acção preserva a imagem anterior no histórico local.", "Thumbnail library linked to pipeline tasks. Each action preserves the previous image in local history.", "与流程任务关联的缩略图库。每项操作都会在本地历史记录中保留上一张图片。", "Thumbnail-Bibliothek für Pipeline-Aufgaben. Jede Aktion bewahrt das vorherige Bild im lokalen Verlauf.", "Thư viện thumbnail liên kết với các tác vụ pipeline. Mỗi thao tác đều giữ ảnh trước đó trong lịch sử cục bộ.", "Pipeline görevlerine bağlı küçük resim kitaplığı. Her işlem önceki görseli yerel geçmişte korur.", "Библиотека миниатюр, связанная с задачами конвейера. Каждое действие сохраняет предыдущее изображение в локальной истории.", "Biblioteca de miniaturas vinculada a las tareas del flujo. Cada acción conserva la imagen anterior en el historial local.", "Pustaka thumbnail yang terhubung ke tugas alur. Setiap tindakan menyimpan gambar sebelumnya dalam riwayat lokal.", "Libreria di miniature collegata alle attività della pipeline. Ogni azione conserva l'immagine precedente nella cronologia locale."),
+    ("Ainda não existem tarefas com thumbnail gerada ou prompt de imagem disponível.", "Ainda não existem tarefas com thumbnail gerada ou prompt de imagem disponível.", "There are no tasks with a generated thumbnail or available image prompt yet.", "目前没有已生成缩略图或可用图片提示词的任务。", "Es gibt noch keine Aufgaben mit generiertem Thumbnail oder verfügbarem Bild-Prompt.", "Chưa có tác vụ nào có thumbnail được tạo hoặc prompt hình ảnh khả dụng.", "Henüz oluşturulmuş küçük resmi veya kullanılabilir görsel istemi olan görev yok.", "Пока нет задач с созданной миниатюрой или доступным промптом изображения.", "Aún no hay tareas con miniatura generada o prompt de imagen disponible.", "Belum ada tugas dengan thumbnail yang dibuat atau prompt gambar yang tersedia.", "Non ci sono ancora attività con miniatura generata o prompt immagine disponibile."),
+    ("Sem imagem", "Sem imagem", "No image", "无图片", "Kein Bild", "Không có ảnh", "Görsel yok", "Нет изображения", "Sin imagen", "Tidak ada gambar", "Nessuna immagine"),
+    ("Imagem ainda não gerada", "Imagem ainda não gerada", "Image not generated yet", "图片尚未生成", "Bild noch nicht generiert", "Ảnh chưa được tạo", "Görsel henüz oluşturulmadı", "Изображение ещё не создано", "Imagen aún no generada", "Gambar belum dibuat", "Immagine non ancora generata"),
+    ("Canal", "Canal", "Channel", "频道", "Kanal", "Kênh", "Kanal", "Канал", "Canal", "Kanal", "Canale"),
+    ("Tarefa", "Tarefa", "Task", "任务", "Aufgabe", "Tác vụ", "Görev", "Задача", "Tarea", "Tugas", "Attività"),
+    ("Estado", "Estado", "Status", "状态", "Status", "Trạng thái", "Durum", "Статус", "Estado", "Status", "Stato"),
+    ("Variante", "Variante", "Variant", "变体", "Variante", "Biến thể", "Varyant", "Вариант", "Variante", "Varian", "Variante"),
+    ("Ver prompt da thumbnail", "Ver prompt da thumbnail", "View thumbnail prompt", "查看缩略图提示词", "Thumbnail-Prompt anzeigen", "Xem prompt thumbnail", "Küçük resim istemini görüntüle", "Просмотреть промпт миниатюры", "Ver prompt de miniatura", "Lihat prompt thumbnail", "Visualizza prompt miniatura"),
+    ("Suba uma imagem para a associar a esta tarefa e à pipeline.", "Suba uma imagem para a associar a esta tarefa e à pipeline.", "Upload an image to link it to this task and the pipeline.", "上传图片以将其关联到此任务和流程。", "Laden Sie ein Bild hoch, um es mit dieser Aufgabe und der Pipeline zu verknüpfen.", "Tải ảnh lên để liên kết với tác vụ này và pipeline.", "Bu göreve ve pipeline'a bağlamak için bir görsel yükleyin.", "Загрузите изображение, чтобы связать его с этой задачей и конвейером.", "Suba una imagen para vincularla a esta tarea y al flujo.", "Unggah gambar untuk menautkannya ke tugas dan alur ini.", "Carica un'immagine per collegarla a questa attività e alla pipeline."),
+    ("A guardar a imagem carregada…", "A guardar a imagem carregada…", "Saving uploaded image…", "正在保存上传的图片…", "Hochgeladenes Bild wird gespeichert…", "Đang lưu ảnh đã tải lên…", "Yüklenen görsel kaydediliyor…", "Сохранение загруженного изображения…", "Guardando la imagen subida…", "Menyimpan gambar yang diunggah…", "Salvataggio dell'immagine caricata…"),
 )
 UI_CONTENT_TRANSLATIONS: dict[str, dict[str, str]] = {code: {} for code in _CONTENT_TRANSLATION_CODES}
 for _row in _CONTENT_TRANSLATION_ROWS:

package/hermes_ui/pipeline_worker.py

@@ -223,12 +223,33 @@ def _run_task(task: dict[str, Any]) -> dict[str, Any]:
 
     _update(task_id, stage="keywords", state="doing", progress=48)
     variant = creative.get("thumbnail_variant") if isinstance(creative.get("thumbnail_variant"), dict) else {}
-    prompt_payload = {"topic": topic, "title": title, "keywords": keywords, "thumbnail": variant, "requirements": {"aspect_ratio": "16:9", "resolution": "1920x1080", "max_elements": 3, "max_overlay_words": 4}}
+    prompt_payload = {
+        "topic": topic,
+        "title": title,
+        "keywords": keywords,
+        "thumbnail": variant,
+        "requirements": {
+            "aspect_ratio": "16:9",
+            "resolution": "1920x1080",
+            "max_elements": 3,
+            "max_overlay_words": 4,
+            "lettering_required": True,
+            "lettering_text": str(variant.get("overlay_text") or ""),
+            "lettering_prompt": str(variant.get("lettering_prompt") or ""),
+        },
+    }
     prompt_artifact = _save_json_artifact(task_id, "thumbnail-prompt", prompt_payload)
     artifacts = {**artifacts, "thumbnail_prompt_json": prompt_artifact}
     _update(task_id, stage="thumbnail_prompt", state="doing", progress=52, thumbnail_prompt=str(variant.get("image_prompt") or ""), thumbnail_text=str(variant.get("overlay_text") or ""), thumbnail_status="prompt_ready", artifacts=artifacts)
     _update(task_id, stage="thumbnail", state="doing", progress=56, thumbnail_prompt=str(variant.get("image_prompt") or ""), thumbnail_text=str(variant.get("overlay_text") or ""), thumbnail_status="prompt_ready", artifacts=artifacts)
-    thumbnail_path = generate_thumbnail_image(settings, str(variant.get("image_prompt") or ""), topic=topic, variant_index=0)
+    thumbnail_path = generate_thumbnail_image(
+        settings,
+        str(variant.get("image_prompt") or ""),
+        topic=topic,
+        variant_index=0,
+        lettering_text=str(variant.get("overlay_text") or ""),
+        lettering_prompt=str(variant.get("lettering_prompt") or ""),
+    )
     artifacts["thumbnail"] = str(thumbnail_path)
     _update(task_id, artifacts=artifacts, thumbnail_status="generated", progress=62)
 

package/hermes_ui/thumbnail_generation.py

@@ -1,8 +1,10 @@
 import base64
 import binascii
 import hashlib
+import mimetypes
 import json
 import os
+import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -29,6 +31,51 @@ def _clean_detail(value: Any, api_key: str) -> str:
     return detail.replace(api_key, "[REDACTED]") if api_key else detail
 
 
+def _fallback_lettering(topic: str) -> str:
+    """Return a short headline when an older task has no overlay_text."""
+    words = re.findall(r"[\wÀ-ÿ$%'-]+", str(topic or ""), flags=re.UNICODE)
+    headline = " ".join(words[:4]).strip()
+    return headline.upper() if headline else "WATCH NOW"
+
+
+def _normalise_lettering_text(value: Any, topic: str) -> str:
+    """Keep the required thumbnail headline concise and never empty."""
+    words = re.findall(r"[\wÀ-ÿ$%'-]+", str(value or ""), flags=re.UNICODE)
+    if not words:
+        return _fallback_lettering(topic)
+    return " ".join(words[:4]).strip()
+
+
+def _compose_thumbnail_prompt(
+    base_prompt: str,
+    *,
+    topic: str = "",
+    lettering_text: str = "",
+    lettering_prompt: str = "",
+) -> tuple[str, str]:
+    """Combine the visual base and a mandatory, model-readable lettering layer."""
+    headline = _normalise_lettering_text(lettering_text, topic)
+    lettering_guidance = str(lettering_prompt or "").strip() or (
+        "Use a bold sans-serif headline with high contrast, a thick outline or shadow, "
+        "safe margins and placement that does not cover the face or main subject."
+    )
+    effective_prompt = (
+        "IMAGE BASE LAYER — create the requested cinematic YouTube thumbnail composition, subject, "
+        "lighting, colour palette and visual hierarchy. Keep the base image clean and uncluttered.\n"
+        f"{str(base_prompt or '').strip()}\n\n"
+        "MANDATORY LETTERING LAYER — the final image MUST visibly contain readable lettering. "
+        "If the image-base description says no text, no words or no lettering, that restriction is overridden "
+        "by this layer. Render the exact headline between the delimiters below; do not omit it, paraphrase it, "
+        "translate it, replace it with placeholder text or hide it.\n"
+        f"EXACT HEADLINE TO RENDER: <<<{headline}>>>\n"
+        f"LETTERING DESIGN: {lettering_guidance}\n"
+        "Use no more than three or four words, bold sans-serif typography, strong contrast, outline/shadow, "
+        "a safe-zone margin and a position that does not cover the face or main object. Do not add unrelated text, "
+        "logos or watermarks. The thumbnail must not be delivered without the exact headline visible."
+    )
+    return effective_prompt, headline
+
+
 def _decode_image_data(value: Any) -> bytes | None:
     if not isinstance(value, str) or not value.strip():
         return None
@@ -72,6 +119,25 @@ def _extract_image_bytes(payload: dict[str, Any]) -> bytes:
     raise ThumbnailGenerationError("O Gemini concluiu a interação, mas não devolveu uma imagem inline.")
 
 
+def _image_input(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        raise ThumbnailGenerationError("A imagem de referência da thumbnail não está disponível no storage.")
+    try:
+        image_data = path.read_bytes()
+    except OSError as exc:
+        raise ThumbnailGenerationError("Não foi possível ler a imagem de referência da thumbnail.") from exc
+    if not image_data:
+        raise ThumbnailGenerationError("A imagem de referência da thumbnail está vazia.")
+    mime_type = mimetypes.guess_type(path.name)[0] or "image/jpeg"
+    if not mime_type.startswith("image/"):
+        mime_type = "image/jpeg"
+    return {
+        "type": "image",
+        "mime_type": mime_type,
+        "data": base64.b64encode(image_data).decode("ascii"),
+    }
+
+
 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]
@@ -84,6 +150,9 @@ def generate_thumbnail_image(
     *,
     topic: str = "",
     variant_index: int = 0,
+    reference_image: str | Path | None = None,
+    lettering_text: str = "",
+    lettering_prompt: str = "",
 ) -> Path:
     api_key = str(settings.get("gemini_image_api_key") or "").strip()
     if not api_key:
@@ -91,13 +160,25 @@ def generate_thumbnail_image(
     clean_prompt = str(prompt or "").strip()
     if not clean_prompt:
         raise ThumbnailGenerationError("A thumbnail não tem um prompt de imagem para gerar.")
+    effective_prompt, headline = _compose_thumbnail_prompt(
+        clean_prompt,
+        topic=topic,
+        lettering_text=lettering_text,
+        lettering_prompt=lettering_prompt,
+    )
 
     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()
+    request_input: str | list[dict[str, str]] = effective_prompt
+    if reference_image:
+        request_input = [
+            {"type": "text", "text": effective_prompt},
+            _image_input(Path(reference_image)),
+        ]
     body = {
         "model": model,
-        "input": clean_prompt,
+        "input": request_input,
         "response_format": {
             "type": "image",
             "mime_type": DEFAULT_MIME_TYPE,
@@ -134,7 +215,12 @@ def generate_thumbnail_image(
     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)
+    destination = output_dir / _thumbnail_filename(
+        f"{effective_prompt}\nEXACT HEADLINE TO RENDER: {headline}",
+        topic,
+        variant_index,
+        model,
+    )
     fd, temp_name = tempfile.mkstemp(prefix=f".{destination.name}.", dir=output_dir)
     try:
         with os.fdopen(fd, "wb") as handle:

package/hermes_ui/thumbnails.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+import os
 import shutil
+import tempfile
 import uuid
 from pathlib import Path
 from typing import Any
 
+from .creative_generation import generate_thumbnail_prompt
 from .storage import STORAGE, now, read_json, write_json
 from .thumbnail_generation import ThumbnailGenerationError, generate_thumbnail_image
 
@@ -51,13 +54,18 @@ def normalize_thumbnail_task(task: dict[str, Any]) -> dict[str, Any]:
         "task_id": str(task.get("id") or ""),
         "title": title,
         "topic": str(task.get("topic") or "").strip(),
+        "channel_id": str(task.get("channel_id") or "").strip(),
         "channel_name": str(task.get("channel_name") or "Canal sem nome").strip(),
+        "blueprint_id": str(task.get("blueprint_id") or "").strip(),
+        "blueprint_name": str(task.get("blueprint_name") or "").strip(),
         "status": str(task.get("thumbnail_status") or "not_generated"),
         "prompt": str(prompt or "").strip(),
         "image_path": _as_path(image_path),
         "variant": variant,
         "variants": variants,
         "variant_index": _variant_index(task, variant, variants),
+        "thumbnail_text": str(variant.get("overlay_text") or task.get("thumbnail_text") or "").strip(),
+        "lettering_prompt": str(variant.get("lettering_prompt") or task.get("thumbnail_lettering_prompt") or "").strip(),
     }
 
 
@@ -82,46 +90,282 @@ def list_thumbnail_tasks() -> list[dict[str, Any]]:
     return records
 
 
-def regenerate_thumbnail(task_id: str, settings: dict[str, Any]) -> tuple[dict[str, Any], Path]:
+def _archive_image(task_id: str, image_path: Path | None) -> Path | None:
+    if not image_path or not image_path.is_file():
+        return None
+    history_dir = STORAGE / "thumbnails" / "history"
+    history_dir.mkdir(parents=True, exist_ok=True)
+    history_path = history_dir / f"{task_id}-{uuid.uuid4().hex[:10]}-{image_path.name}"
+    shutil.copy2(image_path, history_path)
+    return history_path
+
+
+def _variant_for_record(record: dict[str, Any]) -> dict[str, Any]:
+    variant = dict(record.get("variant") or {})
+    variants = record.get("variants") if isinstance(record.get("variants"), list) else []
+    index = int(record.get("variant_index") or 0)
+    if not variant and 0 <= index < len(variants) and isinstance(variants[index], dict):
+        variant = dict(variants[index])
+    return variant
+
+
+def _persist_thumbnail_result(
+    tasks: list[dict[str, Any]],
+    task: dict[str, Any],
+    record: dict[str, Any],
+    image_path: Path,
+    *,
+    variant: dict[str, Any] | None = None,
+    source: str = "generated",
+    lettering_prompt: str = "",
+) -> dict[str, Any]:
+    selected_variant = _variant_for_record(record)
+    if variant:
+        selected_variant.update({key: value for key, value in variant.items() if value is not None})
+    selected_variant["image_path"] = str(image_path)
+    selected_variant["status"] = "generated"
+    selected_variant.setdefault("image_prompt", record.get("prompt") or "")
+    task["thumbnail_variant"] = selected_variant
+    variants = task.get("thumbnail_variants")
+    if not isinstance(variants, list):
+        variants = []
+    variants = list(variants)
+    index = int(record.get("variant_index") or 0)
+    while len(variants) <= index:
+        variants.append({})
+    variants[index] = {**(variants[index] if isinstance(variants[index], dict) else {}), **selected_variant}
+    task["thumbnail_variants"] = variants
+    task["thumbnail_prompt"] = str(selected_variant.get("image_prompt") or record.get("prompt") or "")
+    task["thumbnail_text"] = str(selected_variant.get("overlay_text") or task.get("thumbnail_text") or "")
+    if lettering_prompt:
+        task["thumbnail_lettering_prompt"] = lettering_prompt
+    task["thumbnail_source"] = source
+    task["thumbnail_status"] = "generated"
+    artifacts = dict(task.get("artifacts") or {})
+    artifacts["thumbnail"] = str(image_path)
+    task["artifacts"] = artifacts
+    task["thumbnail_path"] = str(image_path)
+    task["updated_at"] = now()
+    return task
+
+
+def _persist_thumbnail_prompt_result(
+    task: dict[str, Any],
+    record: dict[str, Any],
+    variant: dict[str, Any],
+) -> dict[str, Any]:
+    """Persist a prompt-only update while leaving the active image and artifacts untouched."""
+    selected_variant = _variant_for_record(record)
+    selected_variant.update({key: value for key, value in variant.items() if value is not None})
+    if record.get("image_path"):
+        selected_variant.setdefault("image_path", str(record["image_path"]))
+    selected_variant["status"] = "prompt_ready"
+    variants = task.get("thumbnail_variants")
+    if not isinstance(variants, list):
+        variants = []
+    variants = list(variants)
+    index = int(record.get("variant_index") or 0)
+    while len(variants) <= index:
+        variants.append({})
+    variants[index] = {
+        **(variants[index] if isinstance(variants[index], dict) else {}),
+        **selected_variant,
+    }
+    task["thumbnail_variant"] = selected_variant
+    task["thumbnail_variants"] = variants
+    task["thumbnail_prompt"] = str(selected_variant.get("image_prompt") or "")
+    task["thumbnail_text"] = str(selected_variant.get("overlay_text") or task.get("thumbnail_text") or "")
+    task["thumbnail_lettering_prompt"] = str(
+        selected_variant.get("lettering_prompt") or task.get("thumbnail_lettering_prompt") or ""
+    )
+    task["thumbnail_source"] = "prompt_regenerated"
+    task["thumbnail_status"] = "prompt_ready"
+    task["updated_at"] = now()
+    return task
+
+
+def _find_task(tasks: list[Any], task_id: str) -> tuple[dict[str, Any], dict[str, Any]]:
+    for task in tasks:
+        if isinstance(task, dict) and str(task.get("id") or "") == str(task_id):
+            return task, normalize_thumbnail_task(task)
+    raise ThumbnailGenerationError(f"A tarefa {task_id} não foi encontrada.")
+
+
+def generate_thumbnail_for_task(task_id: str, settings: dict[str, Any]) -> tuple[dict[str, Any], Path]:
+    """Generate an image from the task's current prompt and persist it on the task."""
     tasks = read_json("tasks.json", [])
     if not isinstance(tasks, list):
         raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
-    for task in tasks:
-        if not isinstance(task, dict) or str(task.get("id") or "") != str(task_id):
-            continue
-        record = normalize_thumbnail_task(task)
-        if not record["prompt"]:
-            raise ThumbnailGenerationError("Esta tarefa não tem um prompt de imagem para refazer a thumbnail.")
-        previous_image = record.get("image_path")
-        if previous_image and previous_image.is_file():
-            history_dir = STORAGE / "thumbnails" / "history"
-            history_dir.mkdir(parents=True, exist_ok=True)
-            history_path = history_dir / f"{task_id}-{uuid.uuid4().hex[:10]}-{previous_image.name}"
-            shutil.copy2(previous_image, history_path)
-        image_path = generate_thumbnail_image(
-            settings,
-            record["prompt"],
-            topic=record["title"] or record["topic"],
-            variant_index=record["variant_index"],
-        )
-        artifacts = dict(task.get("artifacts") or {})
-        artifacts["thumbnail"] = str(image_path)
-        task["artifacts"] = artifacts
-        task["thumbnail_path"] = str(image_path)
-        task["thumbnail_status"] = "generated"
-        variant = dict(record["variant"])
-        if variant:
-            variant["image_path"] = str(image_path)
-            task["thumbnail_variant"] = variant
-        variants = task.get("thumbnail_variants")
-        if isinstance(variants, list) and 0 <= record["variant_index"] < len(variants) and isinstance(variants[record["variant_index"]], dict):
-            variants[record["variant_index"]] = {**variants[record["variant_index"]], "image_path": str(image_path)}
-            task["thumbnail_variants"] = variants
-        task["updated_at"] = now()
-        write_json("tasks.json", tasks)
-        return task, image_path
-    raise ThumbnailGenerationError(f"A tarefa {task_id} não foi encontrada.")
+    task, record = _find_task(tasks, task_id)
+    if not record["prompt"]:
+        raise ThumbnailGenerationError("A thumbnail não tem um prompt de imagem para gerar.")
+    _archive_image(str(task_id), record.get("image_path"))
+    image_path = generate_thumbnail_image(
+        settings,
+        record["prompt"],
+        topic=record["title"] or record["topic"],
+        variant_index=record["variant_index"],
+        lettering_text=record.get("thumbnail_text") or "",
+        lettering_prompt=record.get("lettering_prompt") or "",
+    )
+    _persist_thumbnail_result(tasks, task, record, image_path)
+    write_json("tasks.json", tasks)
+    return task, image_path
+
+
+def regenerate_thumbnail_prompt(
+    task_id: str,
+    settings: dict[str, Any],
+    channel: dict[str, Any],
+    blueprint: dict[str, Any] | None = None,
+    language: str = "",
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Regenerate and persist only the thumbnail prompt, keeping the existing image unchanged."""
+    tasks = read_json("tasks.json", [])
+    if not isinstance(tasks, list):
+        raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
+    task, record = _find_task(tasks, task_id)
+    topic = record["topic"] or record["title"]
+    if not topic:
+        raise ThumbnailGenerationError("A tarefa não tem tópico para refazer o prompt da thumbnail.")
+    variant = generate_thumbnail_prompt(
+        settings,
+        channel or {},
+        topic,
+        current_prompt=record["prompt"],
+        blueprint=blueprint,
+        language=language,
+    )
+    _persist_thumbnail_prompt_result(task, record, variant)
+    write_json("tasks.json", tasks)
+    return task, variant
+
+
+def regenerate_thumbnail_prompt_and_image(
+    task_id: str,
+    settings: dict[str, Any],
+    variant: dict[str, Any],
+) -> tuple[dict[str, Any], Path]:
+    """Persist a newly generated prompt and render its image as one atomic task update."""
+    tasks = read_json("tasks.json", [])
+    if not isinstance(tasks, list):
+        raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
+    task, record = _find_task(tasks, task_id)
+    prompt = str((variant or {}).get("image_prompt") or "").strip()
+    if not prompt:
+        raise ThumbnailGenerationError("O provider não devolveu um prompt de imagem válido.")
+    _archive_image(str(task_id), record.get("image_path"))
+    image_path = generate_thumbnail_image(
+        settings,
+        prompt,
+        topic=record["title"] or record["topic"],
+        variant_index=record["variant_index"],
+        lettering_text=str((variant or {}).get("overlay_text") or ""),
+        lettering_prompt=str((variant or {}).get("lettering_prompt") or ""),
+    )
+    _persist_thumbnail_result(tasks, task, record, image_path, variant=variant, source="prompt_regenerated")
+    write_json("tasks.json", tasks)
+    return task, image_path
+
+
+def regenerate_thumbnail_lettering(
+    task_id: str,
+    settings: dict[str, Any],
+    lettering_prompt: str = "",
+) -> tuple[dict[str, Any], Path]:
+    """Edit only the lettering while sending the existing image as a Nano Banana reference."""
+    tasks = read_json("tasks.json", [])
+    if not isinstance(tasks, list):
+        raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
+    task, record = _find_task(tasks, task_id)
+    previous_image = record.get("image_path")
+    if not previous_image or not previous_image.is_file():
+        raise ThumbnailGenerationError("A thumbnail precisa de uma imagem existente para refazer o lettering.")
+    base_prompt = record["prompt"] or "Cria uma thumbnail de YouTube cinematográfica e de alto contraste."
+    edit_prompt = str(lettering_prompt or "").strip() or (
+        f"Refaz apenas o lettering da thumbnail para o vídeo {record['title']!r}. "
+        "Escolhe uma frase curta e forte, com no máximo quatro palavras, relacionada com o título."
+    )
+    combined_prompt = (
+        "BASE IMAGE LAYER — preserva exactamente a composição, enquadramento, sujeitos, fundo, iluminação, "
+        "cores, objectos e estilo da imagem de referência. Não recries nem movas nenhum elemento.\n"
+        f"{base_prompt}\n\n"
+        "LETTERING EDIT LAYER — altera exclusivamente o texto/lettering visível da thumbnail. "
+        "Mantém tudo o que pertence à BASE IMAGE LAYER pixelmente tão próximo quanto possível, sem mudar a imagem.\n"
+        f"{edit_prompt}\n"
+        "Não adicionar logótipos, marcas de água ou outros elementos."
+    )
+    _archive_image(str(task_id), previous_image)
+    image_path = generate_thumbnail_image(
+        settings,
+        combined_prompt,
+        topic=record["title"] or record["topic"],
+        variant_index=record["variant_index"],
+        reference_image=previous_image,
+        lettering_prompt=edit_prompt,
+    )
+    variant = _variant_for_record(record)
+    variant["image_prompt"] = base_prompt
+    variant["lettering_prompt"] = edit_prompt
+    _persist_thumbnail_result(tasks, task, record, image_path, variant=variant, source="lettering_regenerated", lettering_prompt=edit_prompt)
+    write_json("tasks.json", tasks)
+    return task, image_path
+
+
+def upload_thumbnail_image(
+    task_id: str,
+    image_bytes: bytes,
+    filename: str,
+    content_type: str = "",
+) -> tuple[dict[str, Any], Path]:
+    """Store a user-provided image, preserve the old one, and attach it to the task."""
+    if not isinstance(image_bytes, (bytes, bytearray)) or not image_bytes:
+        raise ThumbnailGenerationError("O ficheiro de imagem está vazio.")
+    if len(image_bytes) > 20 * 1024 * 1024:
+        raise ThumbnailGenerationError("A imagem excede o limite de 20 MB.")
+    suffix = Path(str(filename or "")).suffix.lower()
+    allowed = {".png", ".jpg", ".jpeg", ".webp"}
+    if suffix not in allowed:
+        raise ThumbnailGenerationError("Use uma imagem PNG, JPG, JPEG ou WEBP.")
+    if content_type and not str(content_type).lower().startswith("image/"):
+        raise ThumbnailGenerationError("O ficheiro enviado não é uma imagem válida.")
+    tasks = read_json("tasks.json", [])
+    if not isinstance(tasks, list):
+        raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
+    task, record = _find_task(tasks, task_id)
+    _archive_image(str(task_id), record.get("image_path"))
+    output_dir = STORAGE / "thumbnails" / "uploads"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    destination = output_dir / f"uploaded-{task_id}-{uuid.uuid4().hex[:12]}{suffix}"
+    fd, temp_name = tempfile.mkstemp(prefix=f".{destination.name}.", dir=output_dir)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(bytes(image_bytes))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, destination)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+    variant = _variant_for_record(record)
+    _persist_thumbnail_result(tasks, task, record, destination, variant=variant, source="uploaded")
+    write_json("tasks.json", tasks)
+    return task, destination
+
+
+def regenerate_thumbnail(task_id: str, settings: dict[str, Any]) -> tuple[dict[str, Any], Path]:
+    """Backward-compatible alias for regenerating from the current prompt."""
+    return generate_thumbnail_for_task(task_id, settings)
 
 
-__all__ = ["list_thumbnail_tasks", "normalize_thumbnail_task", "regenerate_thumbnail"]
+__all__ = [
+    "generate_thumbnail_for_task",
+    "list_thumbnail_tasks",
+    "normalize_thumbnail_task",
+    "regenerate_thumbnail",
+    "regenerate_thumbnail_lettering",
+    "regenerate_thumbnail_prompt",
+    "regenerate_thumbnail_prompt_and_image",
+    "upload_thumbnail_image",
+]
 

package/package.json

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