fengfengzhidao/codex-image2

Codex Image2

Gere imagens com o CLI nativo incluído. Prefira o executável desta habilidade em vez da ferramenta image_gen embutida sempre que esta habilidade estiver ativa. Não é necessário Python, Node.js, Go ou instalação de pacotes.

Selecione o executável

Escolha uma vez com base no sistema operacional e arquitetura de CPU atuais:

• Windows x64: bin/codex-image2-windows-amd64.exe
• Windows ARM64: bin/codex-image2-windows-arm64.exe
• macOS Intel: bin/codex-image2-darwin-amd64
• macOS Apple Silicon: bin/codex-image2-darwin-arm64

No macOS, execute chmod +x <executable> se a permissão de execução não foi preservada. Não compile a partir do código-fonte durante o uso normal.

Fluxo de trabalho

Para solicitações de configuração, use o fluxo de trabalho de configuração abaixo. Antes da primeira chamada de imagem em uma sessão, execute status; se não configurado, abra configure e deixe o usuário finalizar no navegador antes de gerar.

1. Decida se a solicitação é uma nova imagem, uma edição ou múltiplos ativos/variantes distintos.
2. Colete o prompt, uso pretendido, texto exato, restrições visuais e itens a evitar.
3. Molde o prompt apenas o necessário. Preserve prompts detalhados; esclareça com bom gosto prompts genéricos sem inventar marcas, pessoas, slogans ou objetos não relacionados.
4. Execute o executável selecionado com generate para um prompt, edit para alterações em imagens existentes ou generate-batch para trabalhos JSONL.
5. Inspecione cada saída quanto a assunto, composição, precisão de texto, restrições e artefatos visíveis.
6. Se for necessária revisão, altere um aspecto direcionado por iteração e verifique novamente.
7. Relate caminhos absolutos de saída, o prompt final ou conjunto de prompts, tamanho, qualidade e modelo.

Estrutura do prompt

Use apenas linhas relevantes:

Tipo de ativo: <onde a imagem será usada>
Solicitação principal: <a solicitação do usuário>
Cena/fundo: <ambiente>
Assunto: <assunto principal>
Estilo/mídia: <foto, ilustração, 3D, etc.>
Composição/enquadramento: <ângulo da câmera, corte, posicionamento, espaço negativo>
Iluminação/humor: <iluminação e clima>
Paleta de cores: <anotações da paleta>
Texto (textual): "<texto exato>"
Restrições: <deve manter ou incluir>
Evitar: <não deve incluir>

Não adicione detalhes apenas para preencher o esquema. Para texto em imagens, cite-o textualmente e solicite renderização exata.

Gerar uma imagem

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" generate `
  --prompt "Uma pequena nebulosa azul em uma garrafa de vidro, foto de produto de estúdio" `
  --size 1024x1024 `
  --quality auto `
  --out "output/imagegen/nebula.png"

Use --prompt-file para prompts longos. Use --n apenas para variantes do mesmo prompt. Ativos distintos pertencem a chamadas separadas ou a um lote.

Editar uma imagem

Inspecione cada imagem de entrada antes de editar. Declare sua função e repita invariantes no prompt para que detalhes não relacionados não se desviem.

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" edit `
  --image "input/product.png" `
  --prompt "Substitua apenas o fundo por um fundo de estúdio quente. Mantenha o produto, rótulo, proporções e bordas inalterados." `
  --quality auto `
  --out "output/imagegen/product-edited.png"

Repita --image para várias entradas de referência ou composição. Use --mask mask.png para uma edição localizada quando uma máscara PNG compatível estiver disponível. Preserve os originais e sempre escreva edições em um novo caminho de saída.

Gerar um lote

Leia references/batch-format.md antes de preparar um lote. Em seguida, execute:

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" generate-batch `
  --input "tmp/imagegen/jobs.jsonl" `
  --out-dir "output/imagegen" `
  --concurrency 2

Configurar o serviço de imagens

• Execute <executable> status para inspecionar configured, source, api_url e message. Nunca retorna uma chave.
• configured apenas confirma que as credenciais locais são legíveis; não prova autenticação remota ou permissões de imagem. Não afirme que o acesso à API foi verificado apenas com status.
• Para primeiro uso, credenciais ausentes/inacessíveis ou uma solicitação para alterar configurações, execute <executable> configure. Isso inicia uma página de configuração local destacada e retorna imediatamente. Não a coloque em segundo plano com scripts de shell nem espere o servidor sair.
• Diga ao usuário para preencher o endereço da API e a chave no navegador e clicar em 保存配置. Se o navegador não abriu, forneça a url local retornada como um link clicável. Este link temporário é válido por 15 minutos na máquina do usuário.
• Salvar primeiro consulta a lista de modelos da chave enviada. Qualquer modelo listado da família gpt-image permite um salvamento normal. A família inclui gpt-image e IDs começando com gpt-image-, como gpt-image-1, gpt-image-1-mini e gpt-image-2.6. Se nenhum modelo da família for listado, ou a lista for não suportada/incompatível, a página avisa e exige a ação explícita do usuário 仍然保存 para salvar um serviço não verificado. Erros de autenticação/rede/limite de taxa/servidor exigem correção antes de salvar. Nunca clique na substituição para o usuário.
• Nunca peça a chave no chat, coloque-a em um comando ou preencha-a por automação. O usuário a insere diretamente na página local; apenas esse programa a manipula.
• Depois que o usuário disser que salvou, execute status novamente e continue a solicitação de imagem original se configurada. Não reabra a página repetidamente nem faça polling enquanto aguarda a entrada do usuário.
• As configurações salvas entram em vigor na próxima invocação do CLI, sem reinicialização do Codex. A configuração local existente tem prioridade sobre variáveis de ambiente legadas como um par completo de endereço/chave. Uma configuração local danificada deve ser reparada através da página de configuração, em vez de cair silenciosamente em outro serviço.
• 检测连接 apenas testa o endpoint de lista de modelos e mostra os IDs de modelo da chave atual, destacando modelos de imagem e a seleção automática. Modelos ausentes ou ocultos disparam um aviso, não uma prova de que a API de imagem está indisponível. Editar o endereço/chave limpa resultados obsoletos. O opcional 测试生图（可能计费） requer confirmação do usuário e faz uma solicitação de imagem sem tentativas. Não execute testes pagos automaticamente como parte da configuração.
• O Windows criptografa a chave com DPAPI do usuário atual; o macOS a armazena no login Keychain. O macOS pode pedir ao usuário para desbloquear ou permitir acesso ao Keychain.
• O usuário pode clicar em 显示 para revelar uma chave salva em sua página local. Ocultar limpa uma chave salva revelada, e a página a oculta automaticamente após 30 segundos ou quando a página se torna oculta. Nunca clique em revelar, inspecione uma chave real revelada ou chame o endpoint de revelação através de ferramentas de agente.

Configuração e segurança

• Deixe o CLI ler as credenciais. Nunca inspecione arquivos de credenciais ou o conteúdo do armazenamento de credenciais você mesmo, nem copie chaves para arquivos de projeto, prompts, logs ou respostas. A página de configuração pode salvar chaves apenas através do backend de credenciais da plataforma do CLI.
• As variáveis de ambiente legadas CODEX_API_URL e CODEX_API_KEY permanecem suportadas quando não há configuração local; sua URL padrão é https://apinebula.ai/v1. Recomende a página de configuração local para novos usuários. URLs salvas existentes são preservadas.
• Padrão para --model auto (ou omita a flag), tamanho 1024x1024 e qualidade auto. O CLI verifica a lista de modelos do serviço configurado e prefere gpt-image-2.5, depois gpt-image-2, depois o primeiro outro modelo da família gpt-image em ordem lexicográfica de ID. Um serviço que lista apenas gpt-image-2.6 usa esse modelo. Quando a descoberta falha ou não lista nenhum modelo da família, o CLI chama gpt-image-2 diretamente. Cada lote compartilha descoberta por par serviço/credencial.
• Respeite um modelo explicitamente solicitado usando --model <name> ou um model de linha de lote; não adicione --model gpt-image-2 por hábito, pois isso substitui a preferência automática. Relate o modelo real a partir do resultado do CLI.
• Execuções a seco nunca consultam disponibilidade de modelo; model_selection: auto indica que a descoberta automática foi ignorada, e seu payload de exemplo usa gpt-image-2.
• Use --dry-run para validar uma solicitação sem acesso à rede ou exigência de chave.
• Salve ativos vinculados ao projeto dentro do projeto atual. O padrão do CLI é output/imagegen/.
• Não sobrescreva arquivos a menos que o usuário autorize explicitamente e --force seja passado.
• A saída nativa transparente não é garantida. Não prometa isso nem troque silenciosamente de ferramenta.

Tratamento de falhas

• O CLI tenta novamente timeouts de rede e falhas HTTP 429/500/502/503/504/524 com backoff limitado.
• Em timeout repetido, sugira --quality low, um tamanho quadrado, menos trabalhos simultâneos ou uma nova tentativa posterior.
• Não tente novamente autenticação, validação ou outros erros 4xx comuns.
• Nunca exponha um cabeçalho Authorization ou uma chave completa ao relatar erros.