mohitagw15856/thumbnail-creator

Habilidade de Criador de Miniaturas (via Gemini)

Gera candidatos a miniaturas para artigos e newsletters atuando como um agente de geração de imagens dentro do Claude Code. Em vez de alternar entre ferramentas e solicitar imagens uma por uma na interface web do Gemini, esta habilidade faz o Claude executar o ciclo completo: ler o texto, propor composições, escrever prompts personalizados, chamar a API Gemini, avaliar os resultados e retornar resultados ranqueados com uma breve justificativa.

O resultado são candidatos a miniaturas prontos para produção, que você pode colocar diretamente no seu CMS, ferramenta de newsletter ou agendador de redes sociais.

---

Pré-requisitos

Ambos devem estar em vigor antes que a habilidade possa gerar imagens:

1. Chave da API Gemini

Obtenha uma chave gratuita em Google AI Studio.

Defina-a como uma variável de ambiente:

export GEMINI_API_KEY=<sua-chave>

Para mantê-la entre sessões, adicione ao seu perfil de shell (~/.zshrc ou ~/.bashrc):

echo 'export GEMINI_API_KEY=<sua-chave>' >> ~/.zshrc
source ~/.zshrc

Verifique se está definida:

echo $GEMINI_API_KEY

2. Script generate_image.py

Este script deve existir em ./generate_image.py na raiz do projeto. O modelo completo está na seção Modelo de Script abaixo. O Claude verificará se ele existe e se oferecerá para criá-lo, caso esteja faltando.

Dependências Python:

pip install google-generativeai Pillow requests

Ou com uv:

uv pip install google-generativeai Pillow requests

---

Entradas Necessárias

O Claude perguntará por estas informações se não forem fornecidas:

Entrada	Obrigatório	Observações
Texto do artigo ou URL	Sim	Cole o texto completo do artigo ou forneça uma URL para buscar. Usado para extrair temas, ganchos e principais afirmações para a composição.
Cores da marca	Recomendado	Códigos hexadecimais ou nomes descritivos. Ex.: #1A1A2E (azul marinho), #E94560 (coral). Se não for fornecido, o Claude usa padrões neutros e limpos.
Fontes / estilo de tipo	Recomendado	Ex.: "sans-serif negrito", "serif editorial", "Neue Haas Grotesk". Usado no prompt para orientar o tratamento do texto.
Descrição de referência de estilo	Recomendado	Ex.: "ilustração plana, minimalista, como o site de marketing do Stripe" ou "fotorrealista, fundo escuro, alto contraste". Uma URL de imagem de estilo também pode ser fornecida.
Dimensões de saída	Não	Padrão: 1792x1024 (paisagem, miniatura de artigo padrão). Opções: 1024x1024 (quadrado), 1024x1792 (retrato/mobile).
Número de candidatos	Não	Padrão: 4. Mínimo 1, máximo 8 (limites da API e custo).
Título do artigo (se diferente do H1)	Não	Usado como o elemento de texto principal nos prompts de imagem.
Seleção de candidatos	Não	Após propor composições, o Claude pergunta quais gerar. O usuário pode dizer "todos" ou escolher por número.

---

Estrutura de Saída

Fase 1 — Propostas de Composição (texto, antes de qualquer chamada de API)

O Claude apresenta de 3 a 4 conceitos de composição para aprovação do usuário. Formato:

Conceitos de Composição para: "[Título do Artigo]"

1. AFIRMAÇÃO IMPACTANTE
   Layout:    Fundo escuro com sangria, título grande branco centralizado,
              ponto de dados de destaque (ex.: "3x mais rápido") na cor da marca abaixo
   Tom:       Alta autoridade, estilo newsletter
   Melhor para: LinkedIn, cabeçalhos do Substack
   Justificativa: A afirmação central do artigo ("X supera Y em 3x") é específica
              o suficiente para ancorar o visual — os leitores param em dados.

2. OBJETO CONCEITUAL
   Layout:    Ilustração de objeto central (ex.: um relógio quebrado para um artigo sobre perda de tempo),
              título no terço superior, fundo de textura mínima
   Tom:       Editorial, estilo Medium
   Melhor para: Cabeçalho de blog, capa do Medium, preheader de email
   Justificativa: Oferece flexibilidade de metáfora visual para diretores de arte; funciona em vários tamanhos.

3. DIVISÃO DE CONTRASTE
   Layout:    Metade esquerda na cor da marca, metade direita branca ou imagem,
              título no lado da cor, subtítulo de apoio no lado branco
   Tom:       Limpo, profissional, sensação de startup
   Melhor para: Newsletter, primeiro slide do carrossel do LinkedIn
   Justificativa: Layout dividido tem desempenho consistente em testes A/B de newsletters;
              o texto é legível em tamanhos pequenos.

4. APENAS TIPOGRÁFICO
   Layout:    Sem ilustração, tratamento de título ampliado,
              nome do autor em versalete na parte inferior, separador de linha fina
   Tom:       Premium, confiante, editorial
   Melhor para: Substack, Ghost, listas de email de alta densidade
   Justificativa: Funciona quando a marca tem uma identidade tipográfica forte. Mais rápido de produzir.

Quais composições você deseja que sejam geradas? (Responda com números, ex.: "1, 3" ou "todos")

Fase 2 — Arquivos de Imagem Gerados

Após a geração, o Claude salva os arquivos em ./thumbnails/[slug-do-artigo]/:

thumbnails/
└── slug-do-artigo-do-titulo/
    ├── candidate_01_afirmacao_impactante.png
    ├── candidate_02_objeto_conceitual.png
    ├── candidate_03_divisao_contraste.png
    ├── candidate_04_tipografico.png
    └── evaluation_report.md

Fase 3 — Tabela Resumo de Avaliação

O Claude avalia cada imagem retornada via visão computacional e produz:

Avaliação de Miniatura — "[Título do Artigo]"
Gerada: 2026-05-27  |  Modelo: Gemini Imagen  |  Dimensões: 1792x1024

| # | Candidato | Composição | Adequação à Marca /10 | Legibilidade do Texto /10 | Recomendação |
|---|---|---|---|---|---|
| 1 | candidate_01_afirmacao_impactante.png | Afirmação Impactante | 9 | 8 | ★ Melhor escolha — âncora de dados forte, cores da marca corretas, título legível a 200px de largura |
| 2 | candidate_02_objeto_conceitual.png | Objeto Conceitual | 7 | 9 | Boa alternativa — legível, limpo, mas o estilo de ilustração desviou ligeiramente da marca |
| 3 | candidate_03_divisao_contraste.png | Divisão de Contraste | 8 | 7 | Funciona bem em tamanho real; testar em tamanho de miniatura antes de publicar — o texto do lado direito aperta |
| 4 | candidate_04_tipografico.png | Apenas Tipográfico | 9 | 10 | Mais forte para email — risco zero de desvio da marca, totalmente baseado em texto |

Recomendado para web:          candidate_01_afirmacao_impactante.png
Recomendado para email/mobile: candidate_04_tipografico.png
Recomendado para redes sociais: candidate_03_divisao_contraste.png

Arquivos salvos em: ./thumbnails/slug-do-artigo-do-titulo/

---

Como o Claude Deve Executar Esta Habilidade

Passo 1 — Ingerir e analisar o artigo

Aceite o texto do artigo como texto colado ou uma URL.

Se uma URL for fornecida, busque a página e extraia:

• O título H1
• Os primeiros 3 a 5 parágrafos (o gancho, a afirmação central e os pontos-chave)
• Quaisquer estatísticas notáveis ou estruturas nomeadas mencionadas
• O nome do autor (para composições tipográficas)

Se o texto for colado, leia-o diretamente. Concentre-se em:

• O gancho: Qual é a afirmação ou tensão inicial?
• A tese central: Qual é a única coisa que o artigo argumenta ou ensina?
• Detalhes específicos: Quaisquer números, estruturas nomeadas ou exemplos concretos que possam ancorar um visual
• Tom: É formal/autoritário, conversacional/acessível, provocativo/desafiador?

Resuma essas descobertas internamente antes de propor composições — as propostas devem parecer adaptadas a este artigo específico, não genéricas.

Passo 2 — Coletar especificações da marca

Pergunte ao usuário pelas especificações da marca, se não fornecidas:

Para gerar miniaturas alinhadas à marca, preciso de alguns detalhes:

1. Cores da marca (códigos hexadecimais ou descrições) — ex.: #1A1A2E, #E94560
2. Preferência de estilo de fonte — ex.: "sans-serif negrito", "serif editorial", "geométrico"
3. Estilo visual — ex.: "plano minimalista", "fotorrealista", "ilustrado", "apenas tipográfico"
4. Referências de estilo — descreva uma marca ou publicação cuja estética você deseja igualar,
   ou compartilhe uma URL de imagem

Se você ainda não tem especificações de marca, diga "use padrões limpos" e usarei um estilo
editorial profissional escuro sobre branco.

Se o usuário disser "use padrões limpos", aplique:

• Fundo: #FFFFFF ou #0F0F0F (padrão modo escuro)
• Destaque: #2563EB (azul)
• Estilo de fonte: sans-serif geométrico negrito
• Estilo: plano minimalista, sem texturas, alto contraste

Passo 3 — Propor conceitos de composição

Escreva de 3 a 4 conceitos de composição adaptados ao tom e conteúdo do artigo. Cada conceito deve:

• Ter um nome (rótulo curto e memorável)
• Descrever o layout com precisão (onde o título vai, qual elemento visual o ancora, tratamento do fundo)
• Observar o tom e o caso de uso para o qual é mais adequado
• Incluir uma frase de justificativa explicando por que esta composição se encaixa neste artigo específico

Após apresentar os conceitos, pergunte quais gerar. Aguarde a confirmação do usuário antes de fazer qualquer chamada de API.

Passo 4 — Escrever prompts de geração de imagem do Gemini

Para cada composição selecionada, escreva um prompt de geração de imagem detalhado. Prompts de geração de imagem seguem uma gramática diferente de prompts de texto — eles são descritivos, não instrutivos.

Estrutura do prompt:

[Assunto/composição] + [Estilo] + [Paleta de cores] + [Tom/iluminação] +
[Tratamento de texto, se houver] + [O que evitar]

Exemplo de prompt para composição de Afirmação Impactante:

Imagem de miniatura de artigo. Título grande em negrito branco sans-serif "3x Mais Rápido Que
Métodos Tradicionais" centralizado em um fundo azul marinho escuro (#1A1A2E). Pequeno texto de destaque
coral (#E94560) abaixo lendo o subtítulo. Design plano minimalista, sem gradientes, sem elementos de banco
 de imagens, sem pessoas. Estilo editorial profissional limpo, alto contraste, formato de cabeçalho de
newsletter, orientação paisagem 16:9. A composição é tipográfica — o texto é o herói,
sem ilustração necessária. Evitar: clip art, sombras projetadas, baixo contraste, layout poluído.

Regras do prompt:

• Inclua códigos hexadecimais exatos quando as cores da marca forem fornecidas
• Especifique o texto exato do título a aparecer na imagem
• Nomeie o estilo explicitamente ("design plano", "editorial", "fotorrealista") — o Gemini responde bem a nomes de categorias de estilo
• Adicione um prompt negativo ("Evitar: ...") no final para reduzir desvios do estilo da marca
• Mantenha os prompts com menos de 300 palavras — prompts mais longos não produzem resultados melhores de forma confiável

Passo 5 — Verificar pré-requisitos e executar o script de geração

Antes de chamar a API, verifique:

# Verificar se a chave da API está definida
echo $GEMINI_API_KEY

# Verificar se o script existe
ls -la ./generate_image.py

# Verificar dependências
python3 -c "import google.generativeai, PIL, requests; print('Dependências OK')"

Se o script estiver faltando, ofereça-se para criá-lo usando o modelo na seção Modelo de Script abaixo.

Execute o script de geração para cada prompt:

python3 generate_image.py \
  --prompt "seu prompt completo aqui" \
  --output "./thumbnails/slug-do-artigo/candidate_01_afirmacao_impactante.png" \
  --width 1792 \
  --height 1024

Ou passe todos os prompts em um arquivo de configuração em lote:

python3 generate_image.py --config ./thumbnails/slug-do-artigo/prompts.json

Passo 6 — Avaliar imagens geradas

Após cada imagem ser salva, examine-a usando visão computacional. Avalie em duas dimensões:

Adequação à Marca (pontuação /10):

• As cores da marca estão corretas? (1-2 pontos cada)
• O estilo corresponde à estética solicitada? (2 pontos)
• O layout é consistente com o resumo da composição? (2 pontos)
• Existem artefatos de IA, texto distorcido ou elementos não intencionais? (-1 por problema)

**Legibilidade do Texto (pontuação /10):

• O título é legível na resolução máxima? (3 pontos)
• O título é legível quando a imagem é redimensionada para 300px de largura (tamanho de miniatura)? (3 pontos)
• Há contraste suficiente entre o texto e o fundo? (2 pontos)
• O texto está posicionado dentro de zonas seguras (sem cortes nas bordas)? (2 pontos)

Nota: O Gemini Imagen às vezes renderiza texto com erros ortográficos ou formas de letras distorcidas. Se isso acontecer, observe na avaliação e sugira que o usuário adicione a sobreposição de texto manualmente no Canva ou Figma.

Passo 7 — Produzir o relatório de avaliação

Escreva a tabela resumo de avaliação (formato mostrado na seção Estrutura de Saída) e salve-a como evaluation_report.md na pasta de saída.

Inclua:

• Justificativa de uma linha para cada pontuação
• Uma recomendação de melhor escolha por caso de uso (web, email/mobile, redes sociais)
• Quaisquer observações de produção (ex.: "a renderização de texto está imperfeita no candidate_02 — sobreponha o texto manualmente")
• Os prompts completos usados, para que o usuário possa iterar diretamente no AI Studio, se necessário

Passo 8 — Oferecer iteração

Após entregar os candidatos, ofereça uma rodada de iteração:

Quer iterar em algum destes?

Opções:
- Ajustar cores ou estilo de um candidato específico
- Tentar um conceito de composição diferente
- Alterar o texto do título
- Reexecutar com parâmetros diferentes do Gemini (temperatura/seed diferentes)
- Gerar variantes adicionais da melhor escolha

Apenas me diga o que mudar.

---

Modelo de Script

O Claude deve se oferecer para escrever este arquivo se generate_image.py não estiver presente. Este é o modelo canônico a ser usado.

#!/usr/bin/env python3
"""
generate_image.py — Wrapper do Gemini Imagen para a habilidade Thumbnail Creator.

Uso:
    python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
    python3 generate_image.py --config ./prompts.json

Formato do JSON de configuração:
    [
      {
        "prompt": "...",
        "output": "./thumbnails/slug/candidate_01.png",
        "width": 1792,
        "height": 1024
      }
    ]

Requisitos:
    pip install google-generativeai Pillow
"""

import os
import sys
import json
import argparse
import base64
from pathlib import Path

try:
    import google.generativeai as genai
    from google.generativeai import types as genai_types
except ImportError:
    print("ERRO: google-generativeai não instalado. Execute: pip install google-generativeai")
    sys.exit(1)

try:
    from PIL import Image
    import io
except ImportError:
    print("ERRO: Pillow não instalado. Execute: pip install Pillow")
    sys.exit(1)


def get_api_key() -> str:
    key = os.environ.get("GEMINI_API_KEY", "")
    if not key:
        print("ERRO: A variável de ambiente GEMINI_API_KEY não está definida.")
        print("Obtenha uma chave em: https://aistudio.google.com/app/apikey")
        print("Em seguida, execute: export GEMINI_API_KEY=<sua-chave>")
        sys.exit(1)
    return key


def generate_image(
    prompt: str,
    output_path: str,
    width: int = 1792,
    height: int = 1024,
) -> bool:
    """
    Chama o Gemini Imagen para gerar uma única imagem e salva em output_path.
    Retorna True se bem-sucedido, False caso contrário.
    """
    path = Path(output_path)
    path.parent.mkdir(parents=True, exist_ok=True)

    api_key = get_api_key()
    genai.configure(api_key=api_key)

    model = genai.GenerativeModel(
        model_name="models/imagen-3.0-generate-001",
        generation_config=genai_types.GenerationConfig(
            temperature=1.0,
        ),
    )

    try:
        response = model.generate_content(
            prompt,
            generation_config=genai_types.GenerationConfig(
                candidate_count=1,
            ),
        )
        
        if not response.candidates:
            print(f"ERRO: Nenhum candidato retornado para o prompt.")
            return False

        # Gemini retorna dados de imagem no primeiro candidate
        candidate = response.candidates[0]
        if not candidate.content or not candidate.content.parts:
            print(f"ERRO: Candidato vazio para o prompt.")
            return False

        # A primeira parte deve conter dados de imagem
        part = candidate.content.parts[0]
        if not part.inline_data or not part.inline_data.data:
            print(f"ERRO: Nenhum dado de imagem na resposta.")
            return False

        # Decodificar base64 e salvar
        image_data = base64.b64decode(part.inline_data.data)
        image = Image.open(io.BytesIO(image_data))
        image.save(path)
        print(f"Imagem gerada e salva em: {path}")
        return True

    except Exception as e:
        print(f"ERRO ao gerar imagem: {e}")
        return False


def batch_generate(config_path: str) -> None:
    """
    Gera imagens a partir de um arquivo de configuração JSON.
    """
    with open(config_path, "r") as f:
        prompts = json.load(f)

    success_count = 0
    total = len(prompts)

    for i, item in enumerate(prompts, 1):
        print(f"\n--- Gerando imagem {i}/{total} ---")
        success = generate_image(
            prompt=item["prompt"],
            output_path=item["output"],
            width=item.get("width", 1792),
            height=item.get("height", 1024),
        )
        if success:
            success_count += 1

    print(f"\nConcluído. {success_count}/{total} imagens geradas com sucesso.")


def main():
    parser = argparse.ArgumentParser(description="Gerar imagem via Gemini Imagen")
    parser.add_argument("--prompt", type=str, help="Prompt de texto para geração da imagem")
    parser.add_argument("--output", type=str, help="Caminho para salvar a imagem de saída")
    parser.add_argument("--width", type=int, default=1792, help="Largura da imagem (padrão: 1792)")
    parser.add_argument("--height", type=int, default=1024, help="Altura da imagem (padrão: 1024)")
    parser.add_argument("--config", type=str, help="Caminho para arquivo de configuração JSON com múltiplos prompts")

    args = parser.parse_args()

    if args.config:
        batch_generate(args.config)
    elif args.prompt and args.output:
        generate_image(
            prompt=args.prompt,
            output_path=args.output,
            width=args.width,
            height=args.height,
        )
    else:
        parser.print_help()
        sys.exit(1)


if __name__ == "__main__":
    main()

---

Notas Finais

• Limites de velocidade: A API Gemini Imagen tem limites de taxa. Se você estiver gerando várias imagens de uma vez, o script as processará em série para evitar erros de limitação de taxa.
• Precisão do texto: O Gemini Imagen, como outros modelos de IA, às vezes pode renderizar texto com erros ortográficos ou distorções. Sempre verifique os resultados e, se a precisão do texto for crítica, considere sobrepor o texto manualmente.
• Custo: A API Gemini Imagen oferece um nível gratuito generoso. Para uso em produção, consulte os preços mais recentes na documentação do Google AI Studio.
• Direitos de uso: As imagens geradas são de sua propriedade, sujeitas aos termos de serviço do Google.