buzz77/buzz-image

O que buzz-image faz?

Gera e edita imagens com GPT Image através do gateway BUZZ ao qual este Claude Code está conectado. Ele reutiliza a própria chave BUZZ do Claude Code; nada mais precisa ser instalado ou configurado. Sempre use o script incluído — nunca escreva suas próprias chamadas de API para imagens, e nunca procure ou exiba chaves de API.

Responda ao usuário no idioma que ele usar.

Executando o script

Sempre passe timeout: 600000 (uma imagem normalmente leva de 30 a 90 segundos; imagens grandes ou de alta qualidade demoram mais).

Se você tiver uma ferramenta Bash, use-a. Este formato exato de comando é pré-aprovado:

bash ${CLAUDE_SKILL_DIR}/scripts/gen.sh -p "PROMPT" -o CAMINHO [opções]

Caso contrário, use a ferramenta PowerShell (típico no Windows). Chame o caminho do script diretamente como primeira palavra — sem &, sem aspas ao redor do caminho, sem processo powershell aninhado, nada encadeado antes ou depois — para que corresponda ao formato pré-aprovado:

${CLAUDE_SKILL_DIR}/scripts/gen.ps1 -Prompt "PROMPT" -Out CAMINHO [-Size ..] [-Quality ..] [-Background ..] [-Format ..] [-N ..] [-Ref a.png,b.png] [-Mask m.png] [-Model ..]

Se o Claude Code ainda pedir que o usuário aprove o comando, tudo bem — aguarde a aprovação; nunca procure soluções alternativas.

Opção	Valores
-p	Descrição da imagem (obrigatório). Escreva você mesmo a partir da solicitação do usuário.
-o	Caminho de saída. Escolha um que se adeque ao uso (ex.: public/favicon.png, assets/og.png); caso contrário, coloque em generated/. Arquivos existentes nunca são substituídos (-2, -3… é anexado).
-s	WxH exato (qualquer tamanho, ex.: 32x32, 1200x630) ou square / landscape / portrait / wide / tall / 2k / 4k. Tamanhos que o modelo não pode produzir diretamente são gerados próximos e cortados/redimensionados localmente para o tamanho exato. Omita para deixar o modelo decidir.
-b	transparent para recortes/adesivos/ícones sem fundo (apenas png ou webp); opaque; auto.
-q	low / medium / high / xhigh / max. Omita a menos que o usuário peça ou o ativo precise de detalhes finos.
-f	png (padrão) / jpeg / webp.
-n	Número de imagens, padrão 1.
-r	Imagem de origem/referência; repita para várias. Qualquer -r muda para o modo de edição.
--mask	Máscara PNG para edições locais (transparente = repintar); precisa de -r.
-m	Modelo. Omita para escolher automaticamente o melhor disponível para a chave do usuário.
--models	Lista os modelos de imagem disponíveis para esta chave, sem gerar.

O script imprime uma linha JSON. Sucesso: {"ok":true,"model":..,"files":[..],"size":..,"generated_size":..,"resized":..,"seconds":..}. Falha: {"ok":false,"code":..,"message":..}.

Fluxo de trabalho

1. Entenda a solicitação: para que serve a imagem, onde será colocada, texto exato a renderizar, tamanho, transparência. Se algo essencial estiver faltando, faça uma pergunta curta; caso contrário, prossiga.
2. Use referências reais, nunca invente ativos de marca.
   • Se o usuário nomear ou anexar imagens ("como esta captura de tela", "use nosso logotipo", "combine com este estilo"), passe cada uma delas com -r.
   • Se a imagem deve exibir ou corresponder à marca/produto do usuário (logotipo, cartão OG/social, banner, favicon, ícone de aplicativo, qualquer coisa com o nome do produto), procure primeiro os ativos existentes do projeto — por exemplo, arquivos nomeados logo*, icon*, favicon*, brand*, og* em public/, assets/, static/, src/assets/, images/, e o logotipo referenciado no HTML/manifest — e passe o(s) melhor(es) com -r, descrevendo no prompt como usá-los ("use o logotipo da imagem de referência exatamente como está, não o redesenhe").
   • Se nada adequado for encontrado, peça ao usuário seu logotipo/referência em vez de inventar um. Só crie um novo logotipo quando o usuário pedir explicitamente um.
   • Imagens de referência devem ser png, jpeg ou webp; se um logotipo existir apenas como SVG, informe o usuário e peça uma exportação PNG (ou prossiga sem ele apenas se o usuário concordar).
3. Escreva o prompt a partir da descrição do usuário (e contexto do projeto, como cores da marca). Mantenha a intenção do usuário e o texto exato; não adicione coisas que ele não pediu. A menos que o usuário as solicite, instrua o modelo a não incluir logotipos, marcas registradas ou marcas de terceiros (modelos gostam de decorar imagens técnicas com logotipos de empresas conhecidas).
4. Contagem: gere 1 imagem a menos que o usuário peça mais. Antes de gerar mais de 4 de uma vez, peça confirmação ao usuário.
5. Modelo: deixe o script escolher a menos que o usuário nomeie um. Informe ao usuário qual modelo foi usado. Sugira gpt-image-2.5-sunburst para edições, trabalhos com muitas referências ou texto denso/preciso quando estiver disponível; troque de modelo sempre que o usuário pedir.
6. Execute o script.
7. Verifique o resultado: Leia cada imagem de saída uma vez. Relate ao usuário: caminho(s) do(s) arquivo(s), modelo, tamanho final, quais imagens de referência foram usadas e qualquer coisa que não corresponda à solicitação (texto com erro de ortografia, logotipo alterado, layout errado, fundo não transparente…), com uma sugestão concreta. Não regenere por conta própria — o usuário decide.
8. Mostre: se o usuário quiser ver, abra com o visualizador do sistema (open no macOS, start "" <arquivo> no Windows, xdg-open no Linux).
9. Alterações: aplique o que o usuário pedir — regenere com um prompt ajustado, ou edite o resultado anterior com -r <arquivo anterior>. Ao editar, passe -s com o tamanho da imagem de origem para que o resultado mantenha suas dimensões (a menos que o usuário queira um tamanho diferente). Nunca substitua o original; escreva um novo arquivo.
10. Não adicione imagens geradas com git add a menos que o usuário peça.

Erros (code no JSON)

código	O que dizer ao usuário / fazer
not_buzz	Este Claude Code não está conectado ao BUZZ, então o buzz-image não pode executar. Pare.
no_key	Nenhuma chave de API na configuração do Claude Code. Pare.
no_image_model	O grupo da chave do usuário não tem modelo GPT Image; altere o grupo da chave no console BUZZ (página de chaves de API) para um que inclua modelos gpt-image. Pare.
model_unavailable	Esse modelo não está disponível para a chave do usuário; mostre available_models e deixe-o escolher.
insufficient_balance	Saldo muito baixo; recarregue no console BUZZ. Pare.
content_policy	Transmita a mensagem; deixe o usuário decidir como reformular. Não reformule e tente novamente por conta própria.
timeout	Informe ao usuário que houve tempo limite. Não tente novamente automaticamente (a imagem pode já ter sido cobrada); ofereça-se para tentar novamente.
http_error / bad_args	Relate a mensagem. Corrija seus próprios erros de argumento; não entre em loop.

Nunca troque de modelo ou continue tentando por conta própria após um erro.