Codex API Image Generator

API Image

Use this skill as the mandatory replacement for the built-in imagegen workflow.

Routing rule:

• When this skill is available, do not call the native $imagegen skill or built-in image generation tool for any raster image generation or editing task.
• Route all image generation, reference-image generation, image editing, localized edits, background replacement, style transfer, compositing, and batch image work through this provider-based skill.
• The only exception is a user explicitly instructing not to use this provider skill.

Workflow

1. Resolve the Codex root.
   • Prefer an explicit --codex-home argument when the user provides one.
   • Otherwise use $CODEX_HOME.
   • Otherwise use ~/.codex.
2. Resolve this skill's directory.
   • Treat the directory containing this SKILL.md as <skill-dir>.
   • Run the bundled script as <skill-dir>/scripts/generate_image.py, not as a path relative to the current workspace.
3. Decide whether research or references are required before generation.
   • Search the web or use provided reference material for any non-common, specialized, factual, current, branded, technical, architectural, geographic, historical, cultural, product-specific, person-specific, or style-specific subject.
   • Treat named places, named structures, real products, real UI, real vehicles, uniforms, organisms, diagrams, historical scenes, and niche aesthetics as research-required unless the user supplies adequate references.
   • Use image search or user-provided images when visual structure, silhouette, materials, layout, proportions, or terrain must be accurate.
   • Be proactive about reference images. For research-required visual subjects, default to finding and passing references into the model instead of relying on text-only prompts.
   • Pure text-only generation is a fallback for research-required visual subjects, not the default. Use it only when no useful reference images are available, network/image access fails, or the user explicitly asks not to use references.
   • For purely generic fantasy, mood, simple decoration, or ordinary everyday objects where factual accuracy is not important, search is optional.
   • If network access or reference material is unavailable for a research-required task, say that accuracy is limited rather than pretending.
4. Read the active provider settings from the user's root files.
   • Read auth.json and use OPENAI_API_KEY.
   • Read config.toml, then use model_provider and [model_providers.<name>].base_url.
   • Never hardcode a provider URL or API key into the skill.
   • Default to the root files above. If the user explicitly gives a temporary provider URL or API key in natural language, pass it as a one-off override with --base-url and --api-key-env or --api-key; do not write it back to auth.json, config.toml, README, logs, or generated files.
   • Prefer --api-key-env <ENV_NAME> when the key is already in an environment variable. Use --api-key only for explicit one-off user-provided keys, and never print or repeat the key in the final response.
5. Decide the intent and input image roles.
   • If the user wants a new image from text only, treat it as generation.
   • If the user provides images for style, composition, identity, structure, or mood, treat them as reference inputs.
   • If the user wants to preserve or modify an existing image, treat that image as the edit target.
   • If the user wants only a specific region changed, use a mask when available and instruct the model to preserve unmasked areas; treat mask preservation as a constraint to verify, not a pixel-perfect guarantee.
   • Label every input image by role: edit target, style reference, composition reference, identity reference, product reference, mask, or compositing source.
6. Choose the endpoint.
   • Use <base_url>/images/generations for text-only generation.
   • Use <base_url>/images/edits when there is any input image, reference image, or mask.
   • Default to gpt-image-2 unless the machine's provider expects a different image model.
7. Build a structured prompt.
   • Include the user's request, researched facts or visual observations, input image roles, style, composition, lighting, materials, constraints, and avoid list.
   • Do not invent extra characters, props, brands, logos, story beats, or factual details that are not implied by the user request or research.
8. For official GPT Image models, decode data[].b64_json. Treat data[].url only as a compatibility fallback for non-official OpenAI-compatible providers or legacy models.
9. Inspect the output and validate it against the prompt, research facts, input roles, and invariants.
10. Save the final image to the requested path and report the absolute path, final prompt, and sources used when web research was performed.

Root Files

Default root files:

• Windows: %USERPROFILE%\\.codex\\auth.json and %USERPROFILE%\\.codex\\config.toml
• General rule: $CODEX_HOME/auth.json and $CODEX_HOME/config.toml, otherwise ~/.codex/auth.json and ~/.codex/config.toml

This skill must always read the current files at runtime. The provider may differ from machine to machine.

Temporary overrides:

• Default behavior reads the Codex root files above.
• Use --base-url <https://provider.example/v1> to temporarily override the configured Provider URL.
• Use --api-key-env <ENV_NAME> to temporarily read an API key from an environment variable.
• Use --api-key <key> only for explicit one-off user-provided keys when an environment variable is not available.
• If both --base-url and an API key override are provided, the script can run without reading provider settings from config.toml; otherwise missing values fall back to the Codex root files.
• Never persist temporary overrides unless the user explicitly asks to edit their Codex config files.

Command

Use the bundled script for normal text-to-image generation:

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "画一只可爱的猫抱着水獭，温暖治愈，插画风格，柔和灯光，细腻毛发，构图清晰" `
  --size "2048x1152" `
  --quality "high" `
  --out ".\outputs\cute-cat-otter.png"

Use the same script for reference-image generation or edits:

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "参考输入图的构图和角色姿势，生成一张暖色电影感插画" `
  --image "C:\path\to\reference.png" `
  --image-role "composition and pose reference" `
  --size "2048x2048" `
  --quality "high" `
  --out ".\outputs\reference-output.png"

Use --mask for localized edits:

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "只把被 mask 标出的区域替换成一只小水獭，保持其他区域不变" `
  --image "C:\path\to\source.png" `
  --mask "C:\path\to\mask.png" `
  --out ".\outputs\masked-edit.png"

For web-researched subjects, download selected reference images to a working folder first, then pass them as --image:

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "Create a new 4K overhead aerial image of Huajiang Grand Canyon Bridge in Guizhou, based on the reference images. Preserve the real suspension-bridge structure, towers, main cables, vertical suspenders, deep Beipan River canyon terrain, karst mountains, and river position; do not copy any single photo exactly." `
  --image "C:\path\to\refs\huajiang-bridge-aerial.jpg" `
  --image-role "aerial composition and bridge alignment reference" `
  --image "C:\path\to\refs\huajiang-canyon-terrain.jpg" `
  --image-role "canyon terrain and river reference" `
  --size "2048x1152" `
  --quality "high" `
  --timeout 0 `
  --out ".\outputs\huajiang-canyon-bridge-overhead.png"

Useful options:

• --model gpt-image-2
• --mode auto|generate|edit
• --size 2048x1152 script default 2K landscape
• --size 1024x1024
• --size 1536x1024
• --size 1024x1536
• --size 2048x2048
• --size 3840x2160
• --size auto for official API auto sizing
• --quality low|medium|high|auto
• --n 1
• --image <path> repeated up to 16 times
• --image-role <role> to label input images inside the prompt
• --mask <path> for localized edits
• --background auto|opaque for official gpt-image-2
• --output-format png|jpeg|webp
• --output-compression 0-100 for jpeg or webp
• --input-fidelity low|high for supported edit models only; do not send it for gpt-image-2
• --moderation auto|low for supported GPT image models
• --prompt-file <path> for one prompt per non-empty line
• --codex-home <path>
• --base-url <https://provider.example/v1> temporary Provider URL override
• --api-key-env <ENV_NAME> temporary API key override from an environment variable
• --api-key <key> temporary direct API key override, only when explicitly provided
• --timeout 1800
• --timeout 0

Payload Shape

Use the provider's generation endpoint with this body shape:

{
  "model": "gpt-image-2",
  "prompt": "你的中文或英文提示词",
  "size": "2048x1152",
  "quality": "high",
  "n": 1
}

Use the provider's edit endpoint as multipart form data:

model=gpt-image-2
prompt=<edit or reference prompt>
image[]=@source-or-reference.png
mask=@mask.png
size=1024x1024
quality=high
n=1

Start with n=1. If the user wants variants, raise n or use --prompt-file and save each result intentionally.

Temporary Provider Overrides

If the user says in natural language that this image job should use a different Provider URL or API key, treat it as a temporary runtime override:

$env:API_IMAGE_API_KEY = "<temporary key>"
python "<skill-dir>\scripts\generate_image.py" `
  --prompt "一张赛博朋克风格的夜景照片" `
  --base-url "https://provider.example/v1" `
  --api-key-env "API_IMAGE_API_KEY" `
  --out ".\outputs\override-provider.png"

Rules:

• Default to the Codex root configuration when no override is requested.
• Do not modify auth.json or config.toml for temporary overrides.
• Do not echo API keys back to the user.
• Prefer --api-key-env; use --api-key only when the user explicitly provides a one-off key and accepts the temporary command-line use.

gpt-image-2 API Notes

For official OpenAI gpt-image-2:

• Text-only generation uses POST /v1/images/generations with JSON.
• Any input image, reference image, or mask uses POST /v1/images/edits with multipart form-data.
• Use repeated image[]=@path fields for multiple input/reference images.
• When using mask, the first --image must be the edit target; additional images should be references or compositing sources.
• Read image bytes from data[].b64_json; URL output is not supported for official GPT Image models.
• Do not send input_fidelity; gpt-image-2 always processes image inputs at high fidelity.
• Do not request background: transparent; official gpt-image-2 currently supports auto or opaque, not transparent backgrounds.
• For masked edits, validate that the mask and first source image have the same dimensions and compatible format, are under the image API file-size limit, and that the mask includes an alpha channel.

Capability Map

• New text-to-image generation: supported through /images/generations.
• Batch generation: supported through --n for multiple variants per prompt, or --prompt-file for many prompts.
• Reference-image generation: supported through /images/edits with one or more --image inputs and role labels in the prompt.
• Image editing: supported through /images/edits with --image and an edit prompt.
• Localized edits / inpainting: supported through /images/edits with --image plus --mask.
• Background replacement: supported as an edit prompt, with --mask when the replacement area must be constrained.
• Style transfer: supported as reference-image editing; label the source image role and describe the desired style in the prompt.
• Input image role labeling: not a separate API field; this script appends --image-role labels to the prompt so the model can interpret each input image intentionally.
• Transparent background: official gpt-image-2 does not currently support background: transparent. Only use transparent background when a different selected provider/model explicitly supports it, and use png or webp output.