Magic Prompt de Arte para Estamparia

Magic Prompt de Arte para Estamparia

Magic prompt e guia para geração de imagens consistentes no chat da plataforma.

Status: implementado no fluxo de imagem do chat em 2026-07-16.

Objetivo

O cliente descreve livremente o tema, mesmo sem conhecer estilos de arte, composição ou preparação para impressão. O sistema mantém o pedido original e produz um segundo texto, o Magic Prompt, que é o prompt efetivamente enviado ao gerador de imagem.

O enriquecimento deve resolver três problemas ao mesmo tempo:

1. acrescentar direção artística e criatividade sem apagar a intenção do cliente;
2. integrar texto exato quando a arte contém nome, local, data, evento, frase ou versículo;
3. favorecer formas que sobrevivam a adesivo, DTF e separação de cores para serigrafia.

O Viewer mostra separadamente Pedido e Magic prompt, seguindo a mesma ideia de transparência do Ideogram. Ambos ficam persistidos em ai_generated_images.metadata como original_prompt e magic_prompt.

Pipeline

pedido em linguagem livre
  → Gemini 2.5 Flash como diretor de arte econômico
  → JSON estruturado: conceito, composição, paleta, lettering e produção
  → policy determinística escolhe o especialista Fal
  → comparação paralela: 2× Gemini Image + 1× Fal especialista
  → cliente escolhe uma das artes
  → persistência por variante + pedido + Magic Prompt + profile usado

O modelo textual sugere uma rota, mas não tem autoridade para gastar. A função chooseImageGenerationProfile() aplica condições verificáveis.

/api/ai/chat assina o profile Fal escolhido + pedido + Magic Prompt com HMAC server-side. /api/ai/image só executa a terceira opção paga se a assinatura conferir; alterar o profile pelo DevTools ou chamar o endpoint diretamente não autoriza gasto. A chave e a assinatura nunca dão ao navegador poder para criar outra rota paga.

Em produção, a assinatura usa IMAGE_ROUTE_HMAC_SECRET; FAL_KEY permanece apenas como fallback de compatibilidade para ambientes ainda não migrados.

Comparação 2 + 1

Cada solicitação do cliente consome uma entrada da quota e tenta produzir três alternativas independentes:

1. variante Gemini A — geração econômica;
2. variante Gemini B — nova amostragem do mesmo briefing, para diversidade;
3. variante Fal especialista — modelo escolhido automaticamente pela natureza do trabalho.

As chamadas rodam em paralelo e usam Promise.allSettled: a falha isolada de um modelo não descarta as alternativas bem-sucedidas. A resposta contém variants[], com URL, provider, modelo, profile e rótulo alinhados por índice. A UI mostra somente as imagens, sem fornecedor, modelo, título ou botão. Clicar na própria arte abre o Viewer e grava selected_variant=true apenas na opção escolhida. Todas as variantes mantêm o mesmo comparison_group_id, o que permite reconstruir a comparação na galeria e medir qual rota venceu.

As linhas da galeria são criadas no servidor. O navegador mantém o cache local em IndexedDB e usa /api/ai/image/select para atualizar a escolha; o endpoint mescla apenas selected_variant e preserva a telemetria e a proveniência já gravadas pelo servidor.

A remoção automática de fundo fica suspensa enquanto há várias opções. Isso evita processar e pagar armazenamento para três recortes; depois da escolha, o cliente pode abrir a arte vencedora no Viewer e remover o fundo com undo.

Resposta visual durante a geração

A grade final é reservada assim que o pedido começa: três cartões quadrados aparecem com skeleton, shimmer e pulso, evitando salto de layout. Quando a API retorna, a mesma linha é reaproveitada e cada imagem é revelada individualmente conforme termina de carregar no navegador. No desktop são três colunas; em celular vertical, duas colunas. Usuários com prefers-reduced-motion recebem a mesma estrutura sem animações.

Política econômica

O catálogo de infraestrutura também contém fal-fast (Nano Banana 2) para smokes e experimentos server-side. Ele não pertence ao tipo de domínio ImageGenerationProfile, não pode ser escolhido pelo diretor de arte e não é aceito da API pública; enquanto o Gemini estiver disponível, não há motivo para pagar por uma rota rápida equivalente.

Se FAL_KEY estiver ausente, a autorização for inválida ou o endpoint especialista falhar, as opções Gemini continuam disponíveis. O cliente não precisa conhecer nomes de modelos: a proveniência fica nos metadados para telemetria e administração, enquanto a escolha técnica continua no servidor.

Homologação real

Em 2026-07-16, o profile fal-typography foi executado contra fal-ai/ideogram/v3 com uma arte naval 1024×1024. O resultado preservou exatamente o texto ENGENHARIA NAVAL e produziu emblema com contorno externo grosso, keylines internas e paleta spot limitada. O smoke pago é opt-in:

npx tsx tooling/smoke-fal-generation.mjs --live fal-typography

Sem --live, o script recusa a chamada para evitar gasto acidental.

Técnicas de produção

Contorno externo

Todas as receitas de estampa podem pedir uma silhueta escura firme. Isso ajuda no recorte de adesivo e PNG para DTF, sem obrigar o interior da arte a ser flat.

Keyline e trapping

Uma grade preta funciona como placa-chave e sobrepõe discretamente as bordas das cores. Pequenos deslocamentos de tela ficam escondidos debaixo do preto. A medida real do trap pertence ao preflight, pois depende de malha, tinta, substrato e estabilidade da prensa.

Registro aberto

Cada cor spot é uma ilha. Canais deliberados de espaço negativo separam todas as regiões, de modo que nenhuma tinta toca ou sobrepõe outra. A cor da camiseta ou do substrato aparece nas folgas e absorve variações de registro. No prompt em inglês usamos a formulação concreta deliberate negative-space gutters between every adjacent spot-color region para evitar a ambiguidade de termos como butt fit, que descreve cores que se encontram sem sobreposição nem folga.

Contrato do diretor de arte

O Gemini retorna JSON com:

• subject, creativeDirection, composition e palette;
• lettering.required, exactTexts e layout;
• production.technique e production.notes;
• specialist e specialistReason.

As palavras fornecidas pelo cliente são copiadas literalmente. O diretor pode inventar composição e linguagem visual, mas nunca inventa data, local, nome de evento, citação, versículo ou marca que não esteja no pedido.

Arquivos principais

• src/lib/ai/image-magic.ts: tipos, parser, composição e policy econômica.
• src/lib/ai/image-prompt.ts: chamada ao Gemini e carregamento das receitas.
• src/lib/ai/image-route-auth.ts: autorização HMAC da rota paga.
• src/content/ai/art-styles/: receitas editáveis sem alterar o código.
• src/lib/media/: profiles agnósticos e transporte de mídia fal.ai.
• src/pages/api/ai/image.ts: execução, persistência e telemetria.
• src/components/ai/ChatInterface.astro: grade comparativa e escolha da arte.
• src/lib/ai/storage.ts: persistência do grupo, proveniência e opção escolhida.
• tooling/test-image-magic.mjs: testes determinísticos da policy.
• tooling/smoke-fal-generation.mjs: homologação real, paga e opt-in.