junxxxxiao/gpt-image-2-apikey-skill

Chave de API GPT Image 2

Visão Geral

Gere ou edite imagens com um provedor gpt-image-2 configurado separadamente executando scripts/generate_image.py. Use este skill quando a geração de imagem deve ser faturada, autenticada e isolada de uma chave de API de imagem dedicada, em vez das credenciais atuais do Codex/OpenAI.

O skill deliberadamente não lê OPENAI_API_KEY, arquivos de autenticação do Codex ou credenciais de sessão do ChatGPT/Codex. Ele lê apenas o arquivo de configuração privado selecionado por --config, ou o arquivo de configuração padrão documentado abaixo.

O Que Isso Resolve

Este skill aborda um problema comum no fluxo de trabalho do Codex: a sessão atual do Codex pode já estar autenticada com uma chave de API, enquanto a geração de imagem deve usar outra chave, outra conta, outra cota ou um proxy compatível com OpenAI.

Use este skill para:

• Manter as credenciais de geração de imagem separadas das credenciais do Codex.
• Chamar um endpoint de imagem gpt-image-2 ou compatível a partir do Codex sem expor a chave em prompts, comandos ou arquivos do repositório.
• Gerar imagens através de /v1/images/generations.
• Editar imagens existentes através de /v1/images/edits com upload multipart.
• Usar uma ou mais imagens de referência para edições, reformatações, tratamentos de logotipo, mockups de produto e transformações imagem-para-imagem.
• Opcionalmente fornecer uma imagem de máscara para edições limitadas a regiões.
• Salvar saídas geradas em caminhos locais explícitos que o Codex pode exibir, inspecionar ou passar para etapas posteriores.

Casos de Uso

Use este skill para solicitações como:

• "Gere um logotipo com o texto exato JunXxxxi."
• "Use esta imagem de referência e deixe a marca em itálico."
• "Altere o texto deste logotipo para um gradiente metálico de prata a preto."
• "Crie uma imagem de produto usando gpt-image-2, mas use minha chave de API de imagem separada."
• "Edite esta imagem preservando a composição original."
• "Use um provedor de imagem compatível com OpenAI com uma URL base personalizada."

Prefira processamento de imagem local determinístico em vez deste skill quando a alteração solicitada for uma transformação simples em nível de pixel que deve preservar a geometria exata, como corte, redimensionamento, conversão alfa ou um remapeamento de cor totalmente determinístico. Prefira este skill quando o usuário quiser interpretação visual baseada em modelo, reformatação ou geração.

Conteúdo

gpt-image-2-apikey/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_image.py

• SKILL.md: fluxo de trabalho voltado para o Codex e documentação de uso legível.
• agents/openai.yaml: metadados opcionais da interface do Codex.
• scripts/generate_image.py: script Python 3 sem dependências que chama endpoints de geração ou edição.

O script suporta respostas de imagem tanto b64_json quanto URL. Respostas URL são baixadas imediatamente e escritas no caminho de saída solicitado.

Configuração Privada

Caminho de configuração padrão:

~/.config/gpt-image-2-apikey/config.json

A configuração deve conter a chave do provedor de imagem, não a chave de API atual do Codex:

{
  "api_key": "coloque-a-chave-do-provedor-aqui",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-image-2"
}

Defina permissões privadas após criar o arquivo:

chmod 600 ~/.config/gpt-image-2-apikey/config.json

Use --config /caminho/para/config.json apenas quando o usuário solicitar explicitamente outro arquivo de configuração privado.

Campos da Configuração

• api_key: obrigatório. A chave do provedor de imagem. Não use a chave de API atual do Codex, a menos que seja explicitamente intencionado.
• base_url: opcional. Padrão: https://api.openai.com/v1. Para provedores compatíveis com OpenAI, mantenha na raiz da API, como https://exemplo.com/v1.
• model: opcional. Padrão: gpt-image-2.
• extra_body: objeto opcional. Os valores são mesclados ao corpo da solicitação para campos específicos do provedor.

Exemplos bons de base_url:

{
  "base_url": "https://api.openai.com/v1"
}

{
  "base_url": "https://www.packyapi.com/v1"
}

Não inclua /images/generations ou /images/edits em base_url, a menos que você esteja intencionalmente fixando um endpoint exato. O script normalmente anexa o endpoint correto automaticamente.

Uso

Execute a partir do diretório do skill:

python3 scripts/generate_image.py \
  --prompt "Uma foto de produto limpa de um teclado mecânico preto fosco sobre uma mesa de nogueira" \
  --out /caminho/absoluto/para/saida.png \
  --size 1024x1024 \
  --quality high

Se --edit-image for omitido, o script chama:

POST <base_url>/images/generations

Edite uma ou mais imagens de referência adicionando --edit-image:

python3 scripts/generate_image.py \
  --prompt "Transforme este logotipo em texto gradiente itálico prata-para-preto preservando a grafia exata" \
  --edit-image /caminho/absoluto/para/entrada.png \
  --out /caminho/absoluto/para/editado.png \
  --size 1024x1024 \
  --quality high

Se --edit-image estiver presente, o script chama:

POST <base_url>/images/edits

Para edições com máscara, adicione --mask /caminho/absoluto/para/mascara.png:

python3 scripts/generate_image.py \
  --prompt "Apenas mude o fundo para um cinza de estúdio limpo, preservando o assunto" \
  --edit-image /caminho/absoluto/para/fonte.png \
  --mask /caminho/absoluto/para/mascara.png \
  --out /caminho/absoluto/para/editado.png \
  --quality high

Repita --edit-image para edições com múltiplas imagens:

python3 scripts/generate_image.py \
  --prompt "Combine o produto da imagem 1 com o clima de fundo da imagem 2" \
  --edit-image /caminho/absoluto/para/produto.png \
  --edit-image /caminho/absoluto/para/referencia-fundo.png \
  --out /caminho/absoluto/para/combinado.png

Sempre forneça um caminho --out absoluto quando o usuário precisar do arquivo em um local específico. Se omitido, o script escreve um PNG com timestamp no diretório de trabalho atual.

Referência de Comandos

--prompt       Instrução de prompt ou edição de imagem obrigatória.
--out          Caminho da imagem de saída. Saídas extras usam -2, -3, etc. antes da extensão.
--config       Caminho da configuração privada. Padrão: ~/.config/gpt-image-2-apikey/config.json.
--model        Substituto de modelo da configuração.
--size         Tamanho da imagem suportado pelo provedor. Padrão: 1024x1024.
--quality      low, medium, high ou auto. Padrão: auto.
--n            Número de imagens. Padrão: 1.
--format       png, jpeg ou webp. Padrão: png.
--edit-image   Caminho da imagem de entrada para /v1/images/edits. Repetível.
--mask         Caminho opcional de máscara PNG para edições.
--timeout      Tempo limite HTTP em segundos. Padrão: 600.
--dry-run      Imprime endpoint editado, corpo e lista de arquivos sem chamar a API.

Use --dry-run antes de uma chamada real ao verificar configuração, roteamento de endpoint ou se uma edição usará o arquivo de entrada pretendido:

python3 scripts/generate_image.py \
  --prompt "apenas teste seco" \
  --edit-image /caminho/absoluto/para/entrada.png \
  --out /caminho/absoluto/para/saida.png \
  --dry-run

A saída de dry-run oculta a autorização como Bearer ***redacted***.

Orientações de Prompt

Para geração:

• Declare explicitamente o tipo de ativo, assunto, estilo, layout e texto necessário.
• Coloque o texto visível exato entre aspas.
• Inclua "sem texto extra, sem marca d'água" ao trabalhar com logotipos, cartazes ou gráficos de interface.
• Use quality high para logotipos finais, imagens com tipografia, fotos de produto e entregáveis polidos.
• Use quality low para exploração barata e rascunhos rápidos.

Para edições:

• Descreva a alteração, não a imagem inteira, a menos que a imagem inteira deva ser reinterpretada.
• Nomeie explicitamente o que deve ser preservado: grafia do texto, layout, composição, identidade facial, forma do produto, cores ou fundo.
• Para gráficos com muito texto, repita a grafia e capitalização exatas no prompt.
• Use máscaras para edições cirúrgicas quando suportadas pelo provedor.

Exemplo de prompt de edição:

Edite a imagem de logotipo fornecida. Preserve o texto exato "JunXxxxi" e o mesmo layout da marca. Torne as letras itálicas/inclinadas para a direita. Altere o preenchimento das letras para um gradiente metálico de prata brilhante no topo/esquerda a preto intenso na parte inferior/direita. Mantenha um fundo branco limpo. Não adicione palavras extras, ícones, marcas d'água, bordas ou elementos decorativos.

Regras de Isolamento

• Não passe nem copie a chave de API atual do Codex para este skill.
• Não leia OPENAI_API_KEY; o script a ignora intencionalmente.
• Não imprima api_key ou conteúdo da configuração. O script apenas relata um resumo de configuração editado em --dry-run.
• Se a configuração estiver faltando, informe ao usuário para criar o arquivo de configuração privado. Não o crie com um segredo real em nome deles, a menos que explicitamente solicitado.
• Se um provedor usar um endpoint compatível com OpenAI, defina base_url na configuração privada. O script anexa /images/generations para geração e /images/edits para edições.

Notas de Configuração

• Mantenha config.json fora do Git. Nunca confirme chaves de API reais.
• Use modo de arquivo 600 para a configuração privada.
• Mantenha base_url na raiz da API (.../v1) a menos que o provedor documente o contrário.
• Se o provedor exigir campos de solicitação personalizados, coloque-os sob extra_body.
• Se o provedor não suportar gpt-image-2, defina model para o nome do modelo compatível do provedor.
• Se o provedor suportar apenas respostas URL, o script baixará a URL retornada.
• Se o provedor retornar imagens base64 em b64_json, o script as decodificará diretamente.
• Chamadas de rede podem incorrer em cobranças na conta do provedor configurado.

Exemplo com campos específicos do provedor:

{
  "api_key": "coloque-a-chave-do-provedor-aqui",
  "base_url": "https://exemplo.com/v1",
  "model": "gpt-image-2",
  "extra_body": {
    "moderation": "auto"
  }
}

Tratamento de Falhas

• Configuração ou api_key ausente: reporte o caminho da configuração e os campos obrigatórios.
• Erro HTTP: exiba o código de status e o corpo de erro do provedor, mas nunca inclua a chave.
• Resposta de provedor não suportada: reporte as chaves de resposta de nível superior e não salve nenhum arquivo.
• Múltiplas imagens: a primeira imagem usa --out; imagens adicionais recebem -2, -3, etc. antes da extensão.

Limitações

• Este skill é um wrapper de API, não um editor gráfico completo. Use ferramentas locais determinísticas para cortes exatos, redimensionamentos, exportações vetoriais ou alterações de tipografia garantidamente perfeitas em pixel.
• A edição de imagem baseada em modelo pode alterar texto exato, kerning ou geometria. Para logotipos e marcas, inspecione o resultado antes da entrega.
• A compatibilidade de edição multipart pode variar entre provedores compatíveis com OpenAI. Se edições falharem mas a geração funcionar, verifique se o provedor suporta /v1/images/edits com upload multipart de image.
• O script atualmente envia imagens de edição com o nome do campo multipart image[] para compatibilidade com múltiplas imagens. Se um provedor exigir um nome de campo diferente, ajuste scripts/generate_image.py para esse provedor.
• O comportamento de fundo transparente real depende do suporte do provedor/modelo. Se PNGs transparentes forem necessários, verifique o canal alfa após a geração.

Notas de Publicação

Ao publicar este skill no GitHub:

• Inclua SKILL.md, agents/openai.yaml e scripts/generate_image.py.
• Não inclua ~/.config/gpt-image-2-apikey/config.json.
• Não inclua imagens geradas, a menos que sejam exemplos intencionais.
• Adicione entradas .gitignore para configurações locais, saídas e imagens temporárias se este skill residir em um repositório maior.