colab-flux

O que colab-flux faz?

FLUX 3 Image Klein em uma GPU Colab alugada, controlada por fluxx. Um fluxx gen inicia uma A100 -> instala diffusers -> baixa e carrega o FLUX 3 e um modelo juiz -> renderiza cada cena (melhor de várias, julgadas) -> baixa as imagens -> mantém a GPU aquecida por alguns minutos para acompanhamentos, depois a interrompe. Agrupe todas as cenas que puder em uma única chamada.

O que torna as imagens consistentes é o perfil de marca, não a sorte:

• referências do produto: fotos reais do produto, passadas para o FLUX 3 como imagens de referência em cada cena para que o produto mantenha sua forma, rótulo e cores (até 10 referências)
• estilo: um parágrafo de linguagem fotográfica concreta anexado a cada cena
• evitar: o que nunca deve aparecer
• seed: fixo por marca, para que a mesma cena seja renderizada da mesma forma novamente
• feedback: cada cena é registrada; fluxx rate registra o que a pessoa gostou e por quê, e você incorpora o padrão de volta ao estilo

Tudo fica em ~/colab-flux/brands/<nome>/: brand.json, refs/, history.jsonl, shots/<time>/.

1. Primeiro uso: verificar configuração

Execute fluxx doctor (se fluxx não for encontrado, execute primeiro sh <pasta deste skill>/install.sh). Ele imprime linhas ok / TODO. Guie a pessoa por cada TODO, em palavras simples, um de cada vez:

TODO	O que a pessoa faz	Observações
Colab CLI não instalado	nada: você executa sh install.sh da pasta deste skill	instala uv e a CLI oficial do Colab
não conectado ao Google	executa fluxx login no terminal dela	um navegador abre para login no Google. Você não pode fazer isso por ela
unidades de computação	compra Colab Pro ou unidades de computação em https://colab.research.google.com/signup	a A100 não está no nível gratuito
Hugging Face (opcional)	nada por padrão: sem um token, o fluxx baixa de um espelho público após verificar o sha256 de cada arquivo de peso em relação ao repositório oficial. Para o repositório oficial: fluxx login abre a página do FLUX 3, eles clicam em concordar, criam um token de leitura e o colam no prompt oculto	gratuito. Nunca peça para colarem o token no chat
nenhuma marca	nada: você faz a entrevista de marca abaixo

fluxx login pede o token com um prompt oculto, então precisa de um terminal real: no Claude Code diga a eles para abrir uma aba do terminal e executá-lo lá (Codex, igual). Quando eles disserem que está feito, execute fluxx doctor novamente.

2. Entrevista de marca (uma vez por negócio)

Faça estas perguntas em uma mensagem, curtas, com exemplos para que leve um minuto para responder:

1. Qual é o negócio e qual(is) produto(s) deve(m) aparecer? (ex.: "velas de soja artesanais em potes de vidro âmbar")
2. Quem compra e onde as imagens serão usadas? (Shopify, Amazon, Etsy, Instagram, anúncios, impressos)
3. O visual, em poucas palavras ou uma marca que admiram. (ex.: "calmo, quente, escandinavo, como Aesop")
4. Algo que nunca deve aparecer? (pessoas, texto, itens de concorrentes, bagunça, certas cores)
5. Fotos do produto: caminhos dos arquivos ou arraste-os. Uma foto simples e bem iluminada por produto funciona melhor.

Em seguida, transforme as respostas no perfil. Traduza adjetivos em palavras que um fotógrafo usaria, porque é isso que o FLUX segue. "Calmo e quente" se torna "luz suave difusa de janela vinda da esquerda, paleta neutra quente de aveia, areia e terracota, linho fosco e superfícies de carvalho claro, profundidade de campo rasa, espaço negativo generoso, fotografia editorial de produto".

fluxx brand new acme-velas --business "Acme, velas de soja artesanais em potes de vidro âmbar" \
  --style "luz suave difusa de janela vindo da esquerda, paleta neutra quente ..." \
  --avoid "pessoas, mãos, texto escrito além do rótulo do pote, bagunça" --aspect 4:5
fluxx brand ref acme-velas /caminho/pote-frente.jpg            # role: product (padrão)
fluxx brand ref acme-velas /caminho/moodboard.jpg --role style

Proporção por destino: grade de produtos Amazon/Shopify 1:1, feed do Instagram 4:5, stories/reels 9:16, web hero 16:9, Etsy 4:3 ou 1:1. A proporção da marca é o padrão; --aspect substitui por execução. Mostre à pessoa o perfil que você escreveu (fluxx brand show NOME) e pergunte se parece com eles.

3. Criando imagens

1. fluxx brand show NOME: leia o perfil e o feedback recente antes de escrever qualquer coisa.
2. Escreva as cenas. Uma linha curta e concreta cada uma, apenas sobre a cena. O estilo da marca, a lista de evitar e as funções das referências são adicionadas automaticamente, e o próprio upsampler de prompt do FLUX 3 (um modelo de 9B na GPU) expande cada linha em uma legenda completa, então não gaste tokens escrevendo prompts longos. Bom: o pote em um parapeito de janela de carvalho ensolarado, manhã, um ramo de eucalipto seco ao lado.
3. Reúna todas as cenas que a pessoa possa querer em uma única chamada (a inicialização é a parte cara):

   fluxx gen -b acme-velas -n 2 "cena um" "cena dois" "cena três"
   fluxx gen -b acme-velas --from cenas.txt          # uma cena por linha, comentários # são ok
   

   Uma cena pode definir sua própria forma com um prefixo, para que uma execução possa misturar formatos: 16:9 | o pote em um parapeito ensolarado, espaço à esquerda para um título. Uma inicialização a frio leva ~4 minutos, depois ~45 s por renderização de 4 MP. No Claude Code execute-a com run_in_background; no Codex deixe-a executar. Ela imprime um caminho de imagem por linha no stdout; progresso, a pontuação do juiz e defeitos de cada cena, e o custo em unidades de computação vão para o stderr. Quando uma pessoa está em uma cena usando o produto, diga como: "segurando o fone do telefone no ouvido, seu fio saindo do quadro; a base do telefone não visível". O FLUX desenha o produto da maneira que a referência mostra, então uma parte levantada tende a aparecer duas vezes (em testes, um fone segurado mais um ainda no telefone, mesmo quando o prompt dizia que o berço estava vazio). Enquadrar o resto do produto fora da imagem corrigiu isso.
4. Melhor de N, julgado na GPU. Cada cena renderiza até --candidates imagens (padrão 3). Um juiz de linguagem visual (Qwen3.5-9B, na mesma GPU) verifica cada uma contra o briefing, as referências do produto e a lista de evitar (anatomia, objetos duplicados, fidelidade do produto, texto estranho, apelo), mantém a melhor e para cedo quando uma obtém pontuação 9+ sem defeitos. As outras voltam pequenas em alts/, para que a pessoa ainda possa escolher uma.
5. Olhe você mesmo para os arquivos _md.jpg (eles são pequenos), especialmente qualquer cena cuja linha de stderr liste defeitos ou pontuações abaixo de 7. Diga o que está errado em vez de apresentá-la como pronta. Em seguida, dê à pessoa a pasta e os caminhos.
6. A GPU permanece aquecida depois (--keep, padrão 5 minutos) com os modelos carregados, para que um fluxx gen de acompanhamento com a mesma configuração comece a renderizar imediatamente em vez de depois de ~4 minutos. Imediatamente após apresentar, pergunte: "A GPU ainda está aquecida por N minutos (cerca de X unidades de computação se ficar ociosa). Quer mais ou alterações? Caso contrário, vou desligá-la." Se eles terminarem, execute fluxx stop. Se não disserem nada, ela para sozinha. Se pedirem para mantê-la por mais tempo, passe --keep 15 na próxima execução, ou salve um novo padrão com fluxx config keep_minutes 15. --keep 0 interrompe a GPU ao final da execução.

Flags: -n N variações por cena (seeds seed..seed+N-1) · --candidates K renderiza por cena, melhor mantida (1-8) · --keep MIN minutos aquecidos depois · --draft apenas médio de 1 MP, um candidato, mais rápido, para explorar uma nova direção · --aspect W:H · --ref PATH foto extra de produto única · --no-refs · --seed S · --no-upsample quando as cenas já são legendas completas (pula um download de 19 GB) · --out DIR.

Saídas por cena: <id>_hd.png (cerca de 4 MP, ex.: 2048x2048, para impressão, zoom e imagens hero) e <id>_md.jpg (1024 px no lado maior, para listagens, web e redes sociais).

4. Listagens de marketplace (Amazon, Etsy, eBay, Shopify)

Quando as imagens são para vender um produto online, use fluxx listing em vez de gen. Uma execução cria o conjunto padrão de seis fotos quadradas de 4 MP, exporta uma pasta por marketplace com a ordem, nomes e tamanhos desse site, e redige o texto da listagem na GPU (o modelo juiz o escreve, então sem tokens Claude):

fluxx listing -b acme-velas --product "vela de soja artesanal em um pote de vidro âmbar com tampa de madeira" \
  --notes "227 g, 50 horas de queima, pavio de algodão, fragrância: cedro e fumaça, feito em Oregon" --for amazon,etsy

Cena (função)	O que	Visual da marca
main	produto sozinho em fundo branco puro, centralizado	nenhum: fluxx então torna o fundo exatamente RGB 255 e redimensiona o produto para preencher 85% do quadro (regra de imagem principal da Amazon)
angle	vista de três quartos sobre fundo branco	nenhum
detail	close-up de materiais e acabamento	nenhum
lifestyle	em uso, em um cenário que se adequa aos compradores	sim
scale	ao lado de objetos do dia a dia, para que o tamanho seja óbvio	sim
gift	em mãos ou como presente, sem rosto	sim

Saída na pasta da execução em markets/<site>/:

Site	Imagens	Texto (listing.md + copy.json), limites aplicados pelo fluxx
amazon	MAIN.jpg, PT01.jpg... 2048 px	título 75 caracteres (limite desde julho de 2026), destaques do item 125, 5 bullets de 200, descrição 2000, termos de busca 250 bytes
etsy	01.jpg... 2048 px, uma foto estilizada primeiro (é a miniatura de busca)	título 140, 13 tags de 20 caracteres, descrição
ebay	01.jpg... 1600 px	título 80, especificações do item, descrição
shopify	01.jpg... 2048 px	título 70, título SEO 60, descrição SEO 160, descrição, tags

Regras para o agente:

• Fatos vêm do vendedor. Pergunte sobre tamanho, materiais, o que está incluído e cuidados antes da execução, e passe-os em --notes. O modelo de texto recebe instrução para nunca inventar fatos, mas leia listing.md e remova qualquer afirmação que não esteja nas notas ou visível na imagem antes de a pessoa publicar.
• As imagens mostram o que o FLUX desenhou, não o item real. Para main, angle e detail, o produto deve corresponder ao produto real da pessoa: verifique-o contra as fotos deles e diga a eles que os marketplaces exigem imagens que mostrem o item real. Cenas de estilo de vida são onde as cenas geradas mais ajudam.
• A imagem main branca finalizada se torna a referência do produto para as cenas posteriores, para que adereços na foto da própria pessoa (uma toalha de mesa, decorações) não vazem para as cenas de estilo de vida. Ainda assim, peça uma foto simples e bem iluminada do produto: é a partir dela que main é desenhada.
• --only main,lifestyle cria um subconjunto; --no-refs --ref outra.jpg lista um produto diferente da mesma marca; --for etsy limita os sites.

5. Aprendendo o que eles gostam

O perfil melhora apenas se você fechar o ciclo. Toda vez que a pessoa reagir a uma imagem:

fluxx rate 02-pote-no-parapeito-ensolarado-v1 good "adora a luz baixa da manhã"
fluxx rate 03-pote-no-banheiro-v2 bad "muito ocupado, a toalha rouba o foco"

Quando duas ou mais avaliações apontarem na mesma direção, edite brand.json (é JSON simples; edite-o com suas ferramentas de arquivo): aprimore style, estenda avoid, adicione uma linha datada a notes dizendo o que mudou e por quê. Quando o mesmo defeito voltar (uma parte duplicada, uma cor errada, um rótulo ausente), adicione uma regra de uma linha a checks, ex.: "Exatamente um fone de telefone em toda a imagem". O juiz então conta e verifica essa regra em cada candidato a partir de agora; uma pontuação geral sozinha perdeu exatamente esse tipo de defeito em testes. Diga à pessoa em uma linha ("Adicionei 'luz baixa da manhã' ao seu estilo e removi adereços perto do pote"). Uma cena que eles amam pode se tornar uma referência de estilo: fluxx brand ref NOME <caminho>_hd.png --role style (as referências são limitadas a 10 no total; o FLUX 3 trata referências de estilo apenas como visual, não como conteúdo).

Alterando o estilo a pedido ("deixe mais escuro e mais dramático", "estamos mudando a marca para pastel"): reescreva style em brand.json, mantenha o antigo em notes com a data para que possam voltar atrás, remova referências de estilo que não se encaixam mais e ofereça uma execução rápida --draft de 3-4 cenas conhecidas para que vejam o novo visual antes de um lote completo. Para um segundo visual separado (ex.: uma campanha de feriado), crie outra marca com as mesmas referências de produto em vez de sobrescrever.

Regras

• Uma chamada, muitas cenas. Nunca faça loop de fluxx gen por imagem. Uma inicialização a frio (GPU, ~60 GB de modelos, carregamento) custa ~4 minutos. Acompanhamentos dentro da janela aquecida a pulam.
• A GPU sempre para. Em caso de falha, fluxx a interrompe imediatamente. Em caso de sucesso, ela permanece aquecida por --keep minutos e um watchdog destacado a interrompe depois, mesmo que fluxx ou o agente tenha desaparecido. Durante uma execução, o watchdog a limita a --max-minutes (padrão 60). Se uma execução terminar com NOT CONFIRMED STOPPED, execute fluxx stop e depois fluxx status imediatamente.
• Sem segredos no chat. O token do Hugging Face é digitado apenas no prompt oculto de fluxx login. Ele viaja para a própria VM Colab da pessoa, que o exclui do disco assim que lido e é limpa na parada.
• **As imagens deles permanecem...