zsio/gpt-image

CLI GPT Image

Use o CLI gpt-image para produzir a imagem solicitada pelo usuário e retornar seu caminho local. É necessário Node.js 22+. O modelo padrão é gpt-image-2.6-flare; a qualidade padrão é auto da API. Mantenha esses padrões, a menos que o usuário escolha configurações diferentes.

Encontrar o CLI e a configuração

Use um comando gpt-image instalado quando disponível. Caso contrário, execute o CLI diretamente do repositório público com npm:

npx --yes --package=github:zsio/openai-image-cli#v1.0.0 gpt-image --help

Use o mesmo prefixo no lugar de gpt-image nos exemplos subsequentes. Isso também funciona quando a skill foi instalada em uma máquina sem uma instalação separada do CLI. Não requer um checkout ou um caminho específico da máquina.

Verifique a configuração com gpt-image config show. Apenas OPENAI_API_KEY é obrigatória; tamanho, modelo, qualidade, formato e local de saída têm valores padrão. O CLI lê primeiro as variáveis de ambiente, depois a configuração do usuário em ${XDG_CONFIG_HOME:-$HOME/.config}/gpt-image/.env. gpt-image config path exibe o caminho resolvido. Respeite um --config ou GPT_IMAGE_CONFIG explicitamente selecionado.

Se nenhuma chave estiver configurada, execute gpt-image config init se necessário e instrua o usuário a preencher OPENAI_API_KEY nesse arquivo local. Mantenha a chave fora de repositórios de código e arquivos de skill; não peça para colá-la no chat, imprimi-la ou colocá-la em argumentos de comando. Verifique a presença usando config show, nunca exibindo o arquivo de configuração. Não gere uma imagem de amostra apenas para verificar a configuração; use --dry-run para uma prévia da solicitação.

Gerar ou editar

Para uma nova imagem, passe o prompt como um único argumento. Para prompts longos ou de várias linhas, escreva um arquivo de prompt UTF-8 e use --prompt-file.

gpt-image generate "Um gatinho em aquarela usando um cachecol vermelho" --name gatinho --json

gpt-image generate --prompt-file ./prompt.txt --out-dir ./assets --name capa --json

Para edições ou geração baseada em referência, use edit e repita --image para várias referências. A ordem de entrada é importante: a primeira imagem é a imagem principal para uma máscara ou camada de marcação.

gpt-image edit "Mude o fundo para montanhas nevadas; preserve o rosto e as roupas da pessoa" \
  --image ./retrato.png --name retrato-nevado --json

gpt-image edit "Coloque ambos os produtos em uma única foto de produto com fundo branco" \
  --image ./produto-a.png --image ./produto-b.jpg --name par-produto --json

gpt-image edit "Substitua a região mascarada transparente por um vaso azul" \
  --image ./sala.png --mask ./mascara.png --name vaso-azul --json

Use --background transparent --format png para um recorte transparente ou adesivo. Para edições em um ativo transparente existente, preserve a transparência quando isso fizer parte da solicitação. --mask e --markup usam arquivos PNG e não podem ser combinados; suas dimensões devem corresponder à primeira imagem. São suportadas até 16 imagens de referência, incluindo PNG/JPEG/WebP locais, URLs de imagem e IDs de arquivo OpenAI.

O prompt deve preservar o assunto do usuário, o texto exato solicitado, o estilo e as restrições. Para uma edição, indique tanto a alteração desejada quanto os detalhes a serem preservados. Não altere silenciosamente a quantidade de imagens solicitada, o modelo ou a qualidade. Cada invocação do CLI gera uma imagem final; as tentativas estão desabilitadas, portanto, inspecione as falhas antes de decidir se outra requisição faturada é justificada.

Saída e opções úteis

• A saída padrão é uma pasta única nome-YYYYMMDD-HHmmss-SSS-sufixo no diretório temporário do sistema. Use --name para um nome de arquivo curto e útil.
• Use --output FILE para um caminho de arquivo exato, ou --out-dir DIR --name NOME para um diretório de destino. Essas alternativas não podem ser combinadas. Arquivos de saída existentes são preservados.
• Use --json para ler image_path, metadata_path, prompt_path, request_id e uso da API. O progresso vai para stderr. Retorne o caminho real da imagem salva; visualize a imagem com um visualizador de imagens local disponível quando útil.
• --size LARGURAxALTURA, --quality auto|low|medium|high|xhigh|max, --background auto|opaque|transparent e --format png|jpeg|webp|gif|svg mapeiam para as configurações da API. O suporte a modelo/projeto ainda se aplica.
• Use --model gpt-image-2.6-sunburst quando o usuário escolher o ramo destinado a trabalhos visuais detalhados. Mantenha Flare para solicitações comuns sem preferência de modelo.
• --stream --partial-images 1 salva uma prévia mais a imagem final. Apenas a imagem completa é o resultado final.
• --params '{"complexity":"medium"}' ou --params @params.json passa campos adicionais da API. n permanece fixo em 1. Leia gpt-image --help antes de usar opções incomuns.
• --timeout SEGUNDOS cobre a requisição completa. Em caso de timeout/cancelamento, o serviço pode já ter aceitado a requisição. Não reenvie automaticamente.

Detalhes do CLI e da API: https://github.com/zsio/openai-image-cli