Peteroooooooo/imagegen

O que imagegen faz?

Um comando que chama /images/generations ou /images/edits e salva o resultado no projeto atual.

Configuração (uma vez, pelo usuário)

• Precisa de uma chave de API para a API de Imagens OpenAI ou qualquer API de imagens compatível com OpenAI.
• Variáveis de ambiente (no Windows, valores definidos com setx são lidos do registro, então não é necessário reiniciar o agente):
  • IMAGEGEN_API_KEY: a chave da API. Utiliza OPENAI_API_KEY como fallback.
  • IMAGEGEN_BASE_URL: opcional, padrão https://api.openai.com/v1.
  • IMAGEGEN_MODEL: opcional, padrão gpt-image-2.
• Python 3.8+, apenas biblioteca padrão. Instale esta pasta como ~/.claude/skills/imagegen/ (Claude Code) e/ou ~/.codex/skills/imagegen/ (Codex).
• Opcional: coloque um wrapper imagegen no PATH (exemplos na pasta wrappers/ do repositório). Sem ele, substitua imagegen abaixo por python <caminho da pasta do skill>/scripts/imagegen.py.

Gerar

imagegen "<prompt>" [--size 1536x1024] [--quality high] [--n 2] [--out caminho.png]

Opções de saída (enviadas apenas quando fornecidas; nem toda API ou modelo as aceita): --background transparent|opaque|auto, --format png|jpeg|webp, --compression 0-100 (apenas jpeg/webp).

Editar (passar uma ou mais imagens de entrada)

imagegen "<o que mudar>" --image entrada.png [--image ref.png] [--mask mascara.png]

Saída

Uma linha JSON na saída padrão:

{"ok": true, "mode": "generate", "paths": ["/caminho/para/o/projeto/output/imagegen/20260101-120000-gato-laranja.png"], "seconds": 42.9, "model": "gpt-image-2", "revised_prompt": null, "sidecars": ["/caminho/para/o/projeto/output/imagegen/20260101-120000-gato-laranja.json"]}

Cada imagem recebe um sidecar <mesmo nome>.json com o prompt, prompt revisado, modelo, tamanho, qualidade, outras opções, caminhos das imagens de entrada e da máscara, segundos e horário de criação (--no-sidecar desliga isso). A última imagem é o último caminho na sua saída anterior; se você não o tiver (nova sessão), pegue a imagem mais nova em output/imagegen/ e leia seu .json para o prompt com o qual foi gerada.

Em caso de falha: {"ok": false, "error": "..."} e código de saída 1. Leia paths e reporte-os ao usuário. Se o erro disser que não há chave de API, instrua o usuário a definir IMAGEGEN_API_KEY; não procure chaves por conta própria.

Como trabalhar

• Padrão: gere uma vez a partir da solicitação do usuário e reporte os caminhos. Não abra ou julgue a imagem, e não regenere, a menos que o usuário peça.
• Use apenas o que o usuário disse. Não invente estilo ou detalhes. Se algo sem o qual a imagem fique inutilizável estiver faltando (texto exato na imagem, paisagem ou retrato), pergunte uma vez antes de gerar.
• Quando o usuário pedir para alterar um resultado ("deixe o da esquerda azul"), edite a última imagem com --image <último caminho> em vez de gerar do zero.
• Várias imagens independentes podem ser solicitadas em paralelo (comandos separados ao mesmo tempo).
• Apenas quando o usuário pedir para iterar ("itere até ficar bom") e você puder visualizar imagens: escreva uma pequena lista de verificação com requisitos verificáveis, gere, abra a imagem, verifique cada item. Corrija problemas locais com edições --image e regenere somente se a direção geral estiver errada. Pare quando todos os itens passarem ou após 3 rodadas, e reporte o caminho de cada versão e quaisquer itens que ainda falharem.

Notas

• Sem --out, os arquivos vão para output/imagegen/<tempo>-<palavras>.png no diretório atual (a extensão segue --format).
• Tamanhos: 1024x1024 (quadrado), 1536x1024 (paisagem), 1024x1536 (retrato). gpt-image-2 também aceita tamanhos personalizados como 2048x1152 (16:9): ambos os lados múltiplos de 16, lado mais longo no máximo 3840, proporção entre 1:3 e 3:1. Omita --size para automático.
• --quality low é o mais rápido para rascunhos; high para ativos finais. xhigh / max funcionam apenas em modelos que os suportam.
• Uma imagem leva cerca de 30 a 90 segundos. Execute-a em primeiro plano com um timeout de pelo menos 600000 ms; não faça polling.
• Escreva prompts como: tipo de ativo, assunto, estilo, composição, iluminação, texto exato entre aspas, se houver. Prompts em outros idiomas funcionam.
• Texto que deve aparecer na imagem vai entre aspas, palavra por palavra, com a localização: título no topo lendo "Promoção de Verão". Soletre palavras incomuns letra por letra.
• Com várias imagens de entrada, diga para que cada uma serve, por ordem: "Imagem 1: a foto do produto para editar. Imagem 2: apenas referência de estilo."
• Em edições, diga exatamente o que muda e que tudo o resto permanece igual: "Mude apenas o casaco para vermelho; mantenha o rosto, pose, fundo e iluminação inalterados." Repita as partes inalteradas em cada edição de acompanhamento.
• --background transparent precisa de saída png ou webp e um modelo que suporte isso.
• --dry-run imprime a solicitação sem chamar a API.
• Nunca imprima ou escreva a chave da API.