YouTube Thumbnail

O que YouTube Thumbnail faz?

Thumbnails e capas julgados no tamanho que as pessoas realmente os veem: cerca de 160 px de largura em um feed. Um título de entrada, três conceitos diferentes de saída, o usuário escolhe, um final, revisões estreitas, arquivos no tamanho exato de entrega. O ofício (arcabouços de conceito, blueprint de prompt, regras de texto, o gargalo do tamanho pequeno) está aqui; a mecânica está em references/cli-contract.md e references/platform.md.

Etapa 0 — Pré-verificação

Uma vez por sessão:

command -v genmedia
python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" preflight
python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" tools

• blockers não vazio, CLI ausente ou mais antigo que 0.7.0 → /genmedia-skills:setup. Chave ausente → o usuário executa genmedia setup ou exporta FAL_KEY por conta própria; aguarde. Nunca leia, imprima, solicite ou digite uma chave.
• Mantenha config.announce_above_usd e config.confirm_above_usd (padrões 0.50 e 2): são os limites do gargalo de custo.
• thumbcheck.py tools informa quais de preview, sheet, fit, frame podem ser executados aqui (precisa de ffmpeg local ou macOS sips), e se lockup pode (precisa de um navegador da família Chromium). Nenhum presente → o gargalo degradado na Etapa 6 do Fluxo de Trabalho. Nunca planeje usar drawtext, Pillow ou ImageMagick: o texto é renderizado pelo modelo.
• Retome primeiro: um .genmedia/projects/<slug>/thumbnail.md que corresponde a esta solicitação → leia-o, continue na primeira etapa aberta. Nunca reinicie um projeto que tenha entradas de ledger.

Regras de UX

1. Responda no idioma do usuário (Turco de entrada → Turco de saída). Escreva prompts de modelo em inglês; o texto na imagem permanece no idioma e grafia exata em que será publicado. IDs de endpoint, nomes de campo e caminhos permanecem como estão.
2. Sem JSON, IDs de solicitação, prompts ou narração de ferramentas no chat. Aguarde silenciosamente; no máximo uma linha de status por lote.
3. Orçamento de perguntas: 2, uma de cada vez, como opções rotuladas, apenas quando a resposta estiver faltando:
   • P1 as palavras-gancho: sem título e sem tópico → peça o título. Título conhecido → não pergunte; escreva você mesmo as 2 a 4 palavras-gancho (três diferentes entre os conceitos).
   • P2 rosto ou sem rosto: pergunte apenas se nada o decidir. Uma foto, um @handle ou "eu / meu rosto / ben" → rosto. "Sem rosto", um produto, uma gravação de tela, uma paisagem → sem rosto. O usuário pede apenas uma thumbnail ou nomeia o conceito → um rascunho em vez de três; a escolha vira um sim ou não. Todo o resto é um padrão que você declara na linha de entrega: formato 16:9; idioma do texto = o idioma do título; paleta = as cores da marca fornecidas, senão escolhidas por conceito; aparência de pôster fotorrealista; 3 conceitos; mestre final 2560x1440 entregue como 1920x1080 e 1280x720. Não contadas: a confirmação de consentimento, a escolha, uma confirmação de custo.
4. A escolha é uma parada forçada. Mostre a folha de comparação e aguarde. Silêncio, um trabalho bem-sucedido ou sua própria preferência nunca é uma escolha. Recomendar um é permitido; escolher não é.
5. Veracidade. Uma thumbnail pode dramatizar, nunca deturpar. Tudo mostrado ou escrito deve estar no vídeo ou decorrer honestamente dele: sem números, resultados, reações, produtos ou convidados inventados; sem IU falsa de uma plataforma real; sem logotipos ou personagens que o usuário não possui. Não é possível saber o que o vídeo entrega → pergunte antes de prometer (isso substitui P1 ou P2, não adiciona uma pergunta).
6. Rostos. Uma foto de uma pessoa real (incluindo o usuário) → uma confirmação de que eles têm o consentimento dessa pessoa e uma linha informando que os uploads ficam em URLs públicas. Nunca uma celebridade ou figura pública que o usuário não seja; "parece com " é recusado, ofereça um rosto inventado ou um conceito sem rosto. Um rosto inventado é um substituto: nunca o apresente como uma pessoa real nomeada, cliente, especialista ou convidado, e diga na entrega que o rosto é gerado por IA.
7. Custo: estime a solicitação inteira antes da primeira chamada paga (Etapa 4 do Fluxo de Trabalho) e aplique o gargalo com os limites da pré-verificação: abaixo de announce_above_usd → execute; até confirm_above_usd → uma linha com a estimativa, depois execute; igual ou acima → mostre a estimativa e aguarde um sim explícito (references/platform.md seção 8). Uma aprovação cobre o plano mostrado; um plano maior precisa de um novo. Nunca cite um preço de memória; nunca troque um modelo que o usuário nomeou para economizar dinheiro.
8. Limitado: no máximo 3 rodadas de rascunho e 3 rodadas de revisão; cada tentativa muda algo; uma rejeição de política de conteúdo nunca é reenviada inalterada; um trabalho com um ID de solicitação é retomado, nunca reenviado.

Guardrail de Descoberta

O roteamento abaixo é um cache datado (references/routing-image.md, verificado em 2026-09-19). Antes da primeira chamada paga a um endpoint em uma sessão:

genmedia models --endpoint_id <endpoint_id> --json
python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" schema <endpoint_id>

• status deve ser active. Não ativo ou 404 → próximo nível da mesma tarefa em references/routing-image.md, senão genmedia models "<name>" --no-classify --limit 10 --json, correspondência ativa mais nova, e informe qual modelo foi executado.
• Nomes de campo, enums e limites vêm do esquema, nunca da memória. O usuário nomeia um modelo → pesquise antes de duvidar; novos lançamentos ficam sob namespaces de fornecedores (openai/, bytedance/, google/, alibaba/), não fal-ai/.
• Nunca genmedia run sem um ID de endpoint (roteamento inteligente resolve padrões obsoletos).

Roteamento

Etapa	Endpoint	Por quê
Rascunhos, nada para referenciar	openai/gpt-image-2.5/flare/text-to-image, quality: "medium"	líder em tipografia; apenas a família alvo pode visualizar o texto, um modelo de rascunho barato não pode
Rascunhos com foto de rosto, referências @handle, foto de produto ou frame de vídeo	openai/gpt-image-2.5/flare/edit, quality: "medium"	referências vão em image_urls (máx. 16); mesma família que o final
Final	openai/gpt-image-2.5/sunburst/edit, quality: "high"	nível de precisão; o rascunho escolhido é a imagem 1, então o final é essa composição, não um novo lançamento
Revisão (texto, expressão, fundo, cor)	openai/gpt-image-2.5/sunburst/edit, quality: "high"	o final atual é a imagem 1; um escopo por rodada
Placa sem texto, fotorrealista (caminho alternativo)	bytedance/seedream/v5/pro/text-to-image	arena #1 fotorrealista; o texto é adicionado depois com uma edição do GPT Image 2.5
Placa de identidade quando o rosto deriva	fal-ai/nano-banana-2/edit	padrão de roteamento para imagens com identidade consistente; texto adicionado depois
Ampliar um frame ou foto real	fal-ai/seedvr/upscale/image; rostos ou texto primeiro: topaz/upscale/image/precision	fiel; Topaz tem modelos Faces e Text Refine
Frame do vídeo do usuário	thumbcheck.py frame (ffmpeg local)	timestamp exato; sem ffmpeg → peça ao usuário uma captura de tela
Logotipo do próprio usuário em uma placa sem texto	thumbcheck.py lockup (navegador local)	a marca é colocada a partir do arquivo do usuário; um modelo a redesenhar

Desempates:

1. Texto na imagem → GPT Image 2.5, mesmo para um conceito fotorrealista. Nenhum texto (o usuário disse) → os rascunhos podem ser executados em bytedance/seedream/v5/pro/text-to-image ou seu /edit; o resto do fluxo permanece inalterado. Seedream rejeita 1280x720 (sua área mínima é 1024x1024) e não tem campo quality: envie image_size 1920x1080 (9:16 → 1080x1920, 1:1 → 1536x1536) e precifique por imagem a partir de sua linha de roteamento (cerca de USD 0,07 cada em 2026-09-19: três rascunhos são cerca de USD 0,20, recalcule o total).
2. A estratégia de texto padrão é integrada em uma passagem. Use o caminho da placa (placa sem texto, depois uma edição "adicione apenas este texto") quando: a mesma placa precisa de vários idiomas ou palavras A/B; um diacrítico falhou duas vezes; a placa é um frame ou foto real. Detalhes: references/text-and-readability.md.
3. @handle → leia .genmedia/characters/<handle>/character.json (description âncora; refs[] com role: "face" e active: true), reutilize o cdn_url de uma referência quando tiver um, senão faça upload do arquivo; use a âncora literalmente. real_person: true → a regra de UX 6 se aplica; um consent_confirmed_at registrado é a confirmação. Handle desconhecido → diga, ofereça /genmedia-skills:character; nunca substitua.
4. O usuário nomeou um modelo → use-o após a verificação ao vivo; ofereça o padrão em uma linha.
5. O design é uma placa mais o logotipo do usuário (um canal de marca, um vídeo de pré-visualização de loja de um aplicativo) → caminho da placa, depois thumbcheck.py lockup coloca o arquivo de logotipo centralizado a uma parcela da largura (references/text-and-readability.md seção 2b). A placa já existe (uma placa launch-graphics, a foto do usuário) → nenhuma chamada paga: lockup, gargalo, etapa 10. Nenhum arquivo de logotipo → peça; nunca deixe o modelo desenhar a marca.

Armadilhas:

• Armadilha de tamanho automático. Os endpoints de edição usam image_size como auto, que segue a imagem de entrada: uma foto de rosto em retrato produz uma thumbnail em retrato. Sempre envie {width,height}.
• Armadilha de qualidade padrão. quality usa high como padrão e a família cobra por tokens. Defina em cada chamada: medium para rascunhos, high para finais; xhigh ou max apenas após o usuário concordar com o preço.
• Armadilha de múltiplos de 16. 1920x1080 não é um tamanho legal do GPT Image. Renderize 1280x720, 2560x1440 ou 3840x2160 e deixe thumbcheck.py fit produzir 1920x1080.
• Armadilha de imagem anexada. Um endpoint de texto para imagem não tem campo de imagem; ele ignora a foto e cobra mesmo assim. Qualquer referência → endpoint /edit.
• Armadilha de novo lançamento. Reexecutar o prompt em alta qualidade dá uma imagem diferente (sem seed nesta família). O final é uma edição da escolha.
• Armadilha de maiúsculas. Nunca deixe o modelo escrever turco em maiúsculas: escreva a string final você mesmo (thumbcheck.py text), entre aspas, e verifique caractere por caractere.

Fluxo de Trabalho

1. Coleta. Título ou tópico, formato (padrão 16:9), rosto ou não, cores da marca, referências. HEIC, AVIF, TIFF ou fotos muito grandes primeiro: thumbcheck.py fit <file> --max-side 2048 --out .genmedia/tmp/<name>.jpg; Leia e faça upload dessa cópia. Abra cada imagem local com a ferramenta Read antes de planejar (quem e o que realmente está nela decide os conceitos). Um frame do vídeo do usuário: python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" frame <video> --at <seconds or m:ss>, depois Read. Gaste o orçamento de perguntas apenas conforme a Regra de UX 3 permite.
2. Cartão de estado. Escolha um <slug> ASCII curto (eksi-maya): é o label do lote, o filtro do ledger, a pasta de saída e a pasta do projeto. Um rótulo em linguagem natural também funciona; o auxiliar dobra "Ekşi maya" para Eksi-maya, e essa forma dobrada é então o nome da pasta. Escreva .genmedia/projects/<slug>/thumbnail.md com a ferramenta Write e atualize após cada etapa:

   # <title> — thumbnail
   promise: <uma linha: o que o vídeo realmente entrega>
   format: 16:9 | text language: <code> | face: <none | photo path | @handle> (consent: <yes, date | n/a>) | palette: <colours>
   [ ] concepts  [ ] drafts-1  [ ] gate  [ ] pick: -  [ ] final  [ ] revisions 0/3  [ ] delivered
   log:
   - <date> drafts-1: 1 <framework> "<TEXT>", 2 <framework> "<TEXT>", 3 <framework> "<TEXT>"
   

3. Três conceitos diferentes. Leia references/frameworks.md. Faça um brainstorm de pelo menos cinco em particular, mantenha os três mais fortes que usam arcabouços diferentes (não três variações de cor de uma ideia), cada um com suas próprias 2 a 4 palavras-gancho. Execute cada gancho pela verificação de texto e use sua string upper literalmente:

   python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" text "şimdi izle" --lang tr
   

   Palavras-gancho e imagens podem usar apenas números, resultados, citações, produtos e convidados que o usuário declarou (título, briefing, seus arquivos); o título sozinho não lhe dá um → use uma pergunta, um gancho sem restrições ou um conceito sem texto, ou pergunte (Regra de UX 5). Rejeite qualquer conceito que falhe na regra de veracidade. Rosto escolhido → pelo menos dois dos três conceitos o mostram. O título já carrega o gancho → um conceito pode ser sem texto.
4. Verifique e precifique. Guardrail de descoberta para cada endpoint, depois:

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" price openai/gpt-image-2.5/flare/edit,openai/gpt-image-2.5/sunburst/edit
   

   GPT Image 2.5 responde 1 units, que não é um preço. Dólares para este skill: trabalhos x a linha por tamanho e qualidade (um tamanho não listado → a próxima linha maior) da tabela GPT Image 2.5 em references/routing-image.md (notas t2i-typography; as linhas de edição já incluem uma imagem de entrada) + a margem de referência em references/platform.md §7 para cada imagem de referência adicional. Dicas datadas (2026-09-19): rascunho 1280x720 medium cerca de USD 0.01; final ou revisão 2560x1440 high cerca de USD 0.055; 3840x2160 high cerca de USD 0.10. Trabalho típico completo (3 rascunhos + final + 3 revisões): cerca de USD 0.25 sem referências, cerca de USD 0.45 com uma referência de rosto → abaixo do limite de anúncio padrão, execute e declare a estimativa na linha de entrega. Uma segunda rodada de rascunho, mais referências, xhigh, max, 4K, ou vários vídeos em uma solicitação (um slug e cartão de estado por vídeo; a estimativa é a soma) → recalcule e aplique o gargalo primeiro.
5. Rascunhos em um lote. Faça upload das referências uma vez e mantenha urls (ordem de argumento); uploads são URLs públicas, diga isso uma vez para material privado:

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" upload ./me.jpg
   

   Construa cada prompt a partir de references/prompt-blueprint.md. Escreva o plano com a ferramenta Write em .genmedia/projects/<slug>/drafts-1.json:

   {"label": "<slug>", "max_parallel": 3, "jobs": [
     {"id": "draft-a", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02,
      "input": {"prompt": "<concept A>", "image_urls": ["<face url>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}},
     {"id": "draft-b", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02, "input": {"prompt": "<concept B>", "image_urls": ["<face url>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}},
     {"id": "draft-c", "endpoint_id": "openai/gpt-image-2.5/flare/edit", "est_cost_usd": 0.02, "input": {"prompt": "<concept C>", "image_urls": ["<face url>"], "image_size": {"width": 1280, "height": 720}, "quality": "medium", "num_images": 1, "output_format": "png"}}
   ]}
   

   Execute:

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" batch .genmedia/projects/<slug>/drafts-1.json
   

   Saída: arquivos em .genmedia/projects/<slug>/. Leia cada um com a ferramenta Read. Se uma imagem tiver texto turco, leia com thumbcheck.py text ... --lang tr e corrija se o modelo errou. Atualize o cartão de estado.
6. Folha de comparação. Se preview estiver disponível (da Etapa 0), monte uma grade de comparação:

   python3 "${CLAUDE_SKILL_DIR}/scripts/thumbcheck.py" sheet .genmedia/projects/<slug>/ --out .genmedia/tmp/<slug>-pick.png
   

   Mostre ao usuário: "Veja os três conceitos e escolha um." Se preview não estiver disponível, mostre os caminhos dos arquivos e peça uma escolha pelo nome ("draft-a", "draft-b", "draft-c"). Responda a perguntas sobre mudanças ("pode fazer X?") com o custo e quaisquer implicações do gargalo.
7. Final. Depois da escolha (anote no cartão de estado), produza o final:

   python3 "${CLAUDE_SKILL_DIR}/scripts/gm.py" run openai/gpt-image-2.5/sunburst/edit '{"prompt": "<same prompt as chosen draft, refined>", "image_urls": ["<chosen draft url>", "<face url>"], "image_size": {"width": 2560, "height": 1440}, "quality": "high", "num_images": 1, "output_format": "png"}'
   

   Salve em .genmedia/projects/<slug>/final.png. Execute thumbcheck.py fit para gerar 1920x1080 e 1280x720.
8. Entrega. Informe os caminhos e tamanhos. Se o usuário quiser revisões (até 3), repita a Etapa 7 com um prompt modificado e image_urls incluindo o final atual. Atualize o cartão de estado.
9. Revisões (se solicitadas). Use o mesmo endpoint sunburst/edit, com o final atual como imagem 1 e um escopo claro (por exemplo, "mude apenas a cor do fundo para azul"). Incremente o contador de revisões no cartão de estado.