How to Call the image_gen Tool Syntax, Availability, and Where the Files Go

Key Takeaways

• There is no public argument schema for the built-in tool. You do not hand image_gen a JSON payload. The model calls it; you shape the result through the prompt.
• Built-in mode needs no API key. OPENAI_API_KEY is required only for the fallback CLI. If something is asking you for a key to generate an image in Codex, you are on the wrong path.
• Output lands in $CODEX_HOME/generated_images/. Not the OS temp directory, and there is no destination-path argument on the built-in tool. Generate first, then move the file.
• quality, input_fidelity, and masks are fallback-only. They are Images API parameters exposed through scripts/image_gen.py, not built-in tool arguments. This is the single most common source of confusion.
• Built-in editing works on images in the conversation, not arbitrary file paths. To edit a local file, load it with view_image first so it is in context.

What Is the image_gen Tool?

image_gen is a built-in tool in OpenAI Codex that generates and edits raster images — photos, illustrations, textures, sprites, mockups, and transparent-background cutouts. It is built in, meaning it ships with the environment rather than being something you install, configure, or authenticate against.

OpenAI publishes a skill that governs how an agent should use it. That skill — imagegen, from the openai/skills repository — defines exactly two top-level modes, and the distinction between them explains almost every confusing thing about the tool:

• Built-in tool mode (the default). Uses the image_gen tool directly. No OPENAI_API_KEY. No explicit parameters.
• Fallback CLI mode (explicit request only). Uses a bundled scripts/image_gen.py. Requires OPENAI_API_KEY and network access, and exposes real flags.

The skill is emphatic that an agent should never switch to the CLI on its own. If the built-in tool fails, the correct behaviour is to tell you the fallback exists and wait for you to ask for it.

How Do You Call image_gen?

You do not call it directly. You ask for an image, and the model invokes the tool. There is no command to type and no function signature to fill in. In practice that means the quality of your request is the quality of your interface.

This is the answer to the most common version of the question — “how do I call the image_gen tool in this environment?” — and it disappoints people because it sounds like a non-answer. It is not. It has a concrete consequence: everything you would otherwise pass as a parameter has to be expressed in the prompt instead, and there is a documented structure for doing that. See the prompt spec below.

For multiple assets or variants, the skill is specific: issue one image_gen call per asset. There is no batch parameter in built-in mode. Batching exists only as the CLI’s generate-batch subcommand.

Why There Is No image_gen Argument Schema

Searches for image_gen tool schema and internal-looking identifiers such as image_gen.text2im or gen_id are common, and they mostly come back empty. That is expected: those are internal identifiers that surface in some hosted environments, not a supported public interface. Building against them is building against something nobody promised to keep stable.

OpenAI’s skill goes further and warns against inferring arguments that look like they should exist. Two specific prohibitions are worth quoting in spirit:

So there are two genuinely documented surfaces. The built-in tool, steered by prompt. And the Images API — POST /v1/images/generations and POST /v1/images/edits — which has a real, published parameter list. What does not exist is a public schema for calling the built-in tool as if it were the API.

Is image_gen Available in My Environment?

The practical test is to ask for an image and see what happens. There is no capability endpoint to query, which is why “image_gen tool availability” is such a frequent and frustrating search.

What you can reason about is the failure mode. If the tool is unavailable, the documented behaviour is that the agent tells you the CLI fallback exists and that it needs OPENAI_API_KEY — and then stops, rather than silently switching. If your agent is asking for an API key before generating anything, that is the signal that built-in mode is not in play.

The Actual Syntax: A Structured Prompt Spec

Since the prompt is the interface, the skill defines a labelled spec to structure it. This is the closest thing to “image_gen syntax” that actually exists, and it applies to both modes:

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <your main prompt>
Input images: <Image 1: role; Image 2: role>   (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

Use only the lines that help — it is scaffolding, not a required schema. Two of those lines are traps worth calling out. Asset type and Input images are prompt text, not CLI flags. And Scene/backdrop is the visual setting, which is not the same as the CLI’s background parameter — that one controls output transparency.

Use-case slugs

The skill classifies every request into one of sixteen buckets, and keeping the slug consistent across prompts measurably helps.

A worked example

Use case: product-mockup
Asset type: landing page hero
Primary request: a minimal hero image of a ceramic coffee mug
Style/medium: clean product photography
Composition/framing: wide composition with usable negative space for copy
Lighting/mood: soft studio lighting
Constraints: no logos, no text, no watermark

Where Generated Images Are Saved

In built-in mode, Codex saves generated images under $CODEX_HOME/generated_images/. CODEX_HOME defaults to ~/.codex.

Two things follow that catch people out. It is not the OS temp directory, so do not go looking in /tmp. And because there is no destination argument, the workflow for getting an image where you actually want it is: generate first, then move or copy the selected output.

The skill treats this as a correctness rule rather than a style preference: an asset the project references must never be left sitting at the default generated-images path. If your build points at ~/.codex/generated_images/…, it will break on any other machine.

Editing an Image That Already Exists

Built-in edit mode operates on images that are visible in the conversation — attached by you, or generated earlier in the same thread. It does not take a filesystem path.

To edit a local file, load it into context first with the built-in view_imagetool, then describe the edit. If you genuinely need direct file-path control, masks, or explicit fidelity settings, that is the CLI’s job.

One technique matters more than any parameter: state your invariants, and restate them every iteration. Phrase edits as “change only X; keep Y unchanged”. Models drift across turns, and repeating the constraint is what stops the drift.

Use case: precise-object-edit
Asset type: product photo background replacement
Primary request: replace only the background with a warm sunset gradient
Constraints: change only the background; keep the product and its
  edges unchanged; no text; no watermark

The CLI Fallback, and When It Is the Right Call

scripts/image_gen.py is the escape hatch. Reach for it when you need something the built-in tool genuinely cannot express: an explicit mask, high input fidelity, a deterministic output path, a specific output format, or a batch run from a JSONL file.

It has three subcommands — generate, edit, and generate-batch — and it needs OPENAI_API_KEY plus network access for real calls.

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

# Dry run — no API call, no network, no openai package needed
python "$IMAGE_GEN" generate \
  --prompt "Test" \
  --out output/imagegen/test.png \
  --dry-run

# Real generation
python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --out output/imagegen/alpine-cabin.png

# Edit
python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --out output/imagegen/sunset-edit.png

CLI defaults: model gpt-image-1.5, size 1024x1024, quality auto, format png. Intermediates belong in tmp/imagegen/ and finals in output/imagegen/. Dependencies install with uv pip install openai, plus pillow only if you need downscaling.

Image API Parameter Reference (Fallback Only)

These are the parameters behind the CLI, from the Images API for GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini). To say it once more, because it is the thing everyone gets wrong: these are not built-in image_gen arguments.

Model-specific behaviour worth knowing: gpt-image-1 and gpt-image-1-mini preserve every input image but give the first one richer texture and detail, while gpt-image-1.5 preserves the first five at higher fidelity. Inputs and masks must be under 50MB.

Common Failures and What They Mean

Frequently Asked Questions

How We Verified This

Everything above comes from OpenAI’s own imagegen skill in the openai/skills repository — the SKILL.md at skills/.system/imagegen/ plus its references/cli.md and references/image-api.md, read on 2 September 2026.

We have deliberately not documented internal identifiers such as image_gen.text2im or gen_id. They are not part of any published interface, and writing them up as though they were would be inventing an API contract nobody offered.

You can read the skill yourself on its directory page, which renders the upstream SKILL.md at the commit we captured it from, or install it with npx skills add openai/skills@imagegen.