fengfengzhidao/codex-image2

Codex Image2

Generate images with the bundled native CLI. Prefer this skill's executable over the built-in image_gen tool whenever this skill is active. No Python, Node.js, Go, or package installation is required.

Select the executable

Choose once from the current operating system and CPU architecture:

• 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

On macOS, run chmod +x <executable> if execute permission was not preserved. Do not compile from source during normal use.

Workflow

For setup requests, use the configuration workflow below. Before the first image call in a session, run status; if unconfigured, open configure and let the user finish in their browser before generating.

1. Decide whether the request is a new image, an edit, or multiple distinct assets/variants.
2. Collect the prompt, intended use, exact text, visual constraints, and avoid items.
3. Shape the prompt only as much as needed. Preserve detailed prompts; tastefully clarify generic prompts without inventing brands, people, slogans, or unrelated objects.
4. Run the selected executable with generate for one prompt, edit for changes to existing images, or generate-batch for JSONL jobs.
5. Inspect each output for subject, composition, text accuracy, constraints, and visible artifacts.
6. If revision is needed, change one targeted aspect per iteration and re-check.
7. Report absolute output paths, the final prompt or prompt set, size, quality, and model.

Prompt structure

Use only relevant lines:

Asset type: <where the image will be used>
Primary request: <the user's request>
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo, illustration, 3D, etc.>
Composition/framing: <camera angle, crop, placement, negative space>
Lighting/mood: <lighting and mood>
Color palette: <palette notes>
Text (verbatim): "<exact text>"
Constraints: <must keep or include>
Avoid: <must not include>

Do not add detail merely to fill the schema. For text in images, quote it verbatim and request exact rendering.

Generate one image

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" generate `
  --prompt "A small blue nebula in a glass bottle, studio product photo" `
  --size 1024x1024 `
  --quality auto `
  --out "output/imagegen/nebula.png"

Use --prompt-file for long prompts. Use --n only for variants of the same prompt. Distinct assets belong in separate calls or a batch.

Edit an image

Inspect each input image before editing. State its role and repeat invariants in the prompt so unrelated details do not drift.

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" edit `
  --image "input/product.png" `
  --prompt "Replace only the background with a warm studio backdrop. Keep the product, label, proportions, and edges unchanged." `
  --quality auto `
  --out "output/imagegen/product-edited.png"

Repeat --image for multiple reference or compositing inputs. Use --mask mask.png for a localized edit when a compatible PNG mask is available. Preserve originals and always write edits to a new output path.

Generate a batch

Read references/batch-format.md before preparing a batch. Then run:

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

Configure the image service

• Run <executable> status to inspect configured, source, api_url, and message. It never returns a key.
• configured only confirms that local credentials are readable; it does not prove remote authentication or image permissions. Do not claim API access was verified from status alone.
• For first use, missing/inaccessible credentials, or a request to change settings, run <executable> configure. This launches a detached local configuration page and returns immediately. Do not background it with shell scripts or wait for its server to exit.
• Tell the user to fill in the API address and key in the browser and click 保存配置. If the browser did not open, provide the returned local url as a clickable link. This temporary link is valid for 15 minutes on the user's machine.
• Saving first queries the submitted key's model list. Any listed gpt-image family model allows a normal save. The family includes gpt-image and IDs starting with gpt-image-, such as gpt-image-1, gpt-image-1-mini, and gpt-image-2.6. If no family model is listed, or the list is unsupported/incompatible, the page warns and requires the user's explicit 仍然保存 action to save an unverified service. Authentication/network/rate-limit/server errors require correction before saving. Never click the override for the user.
• Never ask for the key in chat, put it into a command, or fill it through automation. The user enters it directly in the local page; only that program handles it.
• After the user says they saved, run status again and continue the original image request if configured. Do not repeatedly reopen the page or poll while waiting for user input.
• Saved settings take effect on the next CLI invocation, with no Codex restart. Existing local config takes priority over legacy environment variables as a complete address/key pair. A damaged local config must be repaired through the setup page rather than silently falling back to another service.
• 检测连接 only probes the model-list endpoint and shows the current key's model IDs, highlighting image models and the automatic selection. Missing or hidden models trigger a warning rather than proof that the image API is unavailable. Editing the address/key clears stale results. The optional 测试生图（可能计费） requires user confirmation and makes one image request without retries. Do not run paid tests automatically as part of setup.
• Windows encrypts the key with current-user DPAPI; macOS stores it in the login Keychain. macOS may ask the user to unlock or allow access to the Keychain.
• The user can click 显示 to reveal a saved key in their local page. Hiding clears a revealed saved key, and the page automatically hides it after 30 seconds or when the page becomes hidden. Never click reveal, inspect a real revealed key, or call the reveal endpoint through agent tools.

Configuration and safety

• Let the CLI read credentials. Never inspect credential files or credential-store contents yourself, or copy keys into project files, prompts, logs, or responses. The configuration page may save keys only through the CLI's platform credential backend.
• Legacy CODEX_API_URL and CODEX_API_KEY remain supported when no local configuration exists; their URL defaults to https://apinebula.ai/v1. Recommend the local setup page to new users. Existing saved URLs are preserved.
• Default to --model auto (or omit the flag), size 1024x1024, and quality auto. The CLI checks the configured service's model list and prefers gpt-image-2.5, then gpt-image-2, then the first other gpt-image family model in lexicographic ID order. A service listing only gpt-image-2.6 uses that model. When discovery fails or lists no family model, the CLI calls gpt-image-2 directly. Each batch shares discovery per service/credential pair.
• Respect an explicitly requested model using --model <name> or a batch row's model; do not add --model gpt-image-2 by habit, as that overrides automatic preference. Report the actual model from the CLI result.
• Dry runs never query model availability; model_selection: auto indicates automatic discovery was skipped, and their example payload uses gpt-image-2.
• Use --dry-run to validate a request without network access or requiring a key.
• Save project-bound assets inside the current project. The CLI default is output/imagegen/.
• Do not overwrite files unless the user explicitly authorizes it and --force is passed.
• Native transparent output is not guaranteed. Do not promise it or silently switch tools.

Failure handling

• The CLI retries network timeouts and HTTP 429/500/502/503/504/524 failures with bounded backoff.
• On repeated timeout, suggest --quality low, a square size, fewer concurrent jobs, or a later retry.
• Do not retry authentication, validation, or other ordinary 4xx errors.
• Never expose an Authorization header or full key when reporting errors.