codex-image-gen

Codex Image Gen

Goal: package the "local logged-in Codex OAuth image generation capability" into azero private dependenciescross-Agent Skill.

It does not depend on any private modules; any Agent that can execute python3 , as long as the host machine already has Codex CLI installed and has run codex auth login, can directly call scripts/codex_image.py to generate images or perform image editing.

Prerequisites

All of the following must be satisfied:

1. Codex CLI is installed on the local machine
2. Has been run before codex auth login
3. ~/.codex/auth.json exists and is readable
4. The machine can access:
   • https://chatgpt.com/backend-api/codex/responses
   • https://auth.openai.com/oauth/token

If ~/.codex/auth.json does not exist, do not guess or bypass it. Directly prompt the user to first run:

codex auth login

What this skill can do

• Text-to-image
• Accompanying image / illustration / cover image generation
• image-to-image / editing
• Encode a local reference image into data:image/...;base64,... and then send it to the Codex Responses API
• Automatically check whether the access token is expired
• When the access token is expired, automatically refresh it with the refresh token and write it back to ~/.codex/auth.json
• Extract the image base64 from the SSE stream and save it as a local PNG

Core script

Relative path:scripts/codex_image.py

Typical invocation:

python3 scripts/codex_image.py --prompt "极简科技感课程封面，无文字" --aspect landscape

If the Agent is not executing in the skill root directory, explicitly pass the skill-relative path or absolute path, for example:

python3 .claude/skills/codex-image-gen/scripts/codex_image.py \
  --prompt "商业文章封面插图，克制，干净，无文字" \
  --aspect landscape \
  --quality high \
  --out-dir ./outputs

CLI parameters

Required

Choose one of the two:

• --prompt "..."
• --prompt-file /path/to/prompt.txt

Optional

• --quality low|medium|high: default medium
• --aspect landscape|square|portrait: default square
• --out-dir /path/to/output-dir: defaults to the current directory
• --image /path/to/image.png: main edit image / input image
• --reference-image /path/to/ref.png: reference image, can be passed repeatedly
• --model gpt-image-2: default gpt-image-2

Recommended workflow

1) Shortest path: text-to-image

python3 scripts/codex_image.py \
  --prompt "蓝白配色的 AI 课程封面插图，几何感，极简，无文字" \
  --aspect landscape \
  --quality high \
  --out-dir ./outputs

2) Use a prompt file

python3 scripts/codex_image.py \
  --prompt-file ./prompt.txt \
  --aspect portrait \
  --out-dir ./outputs

3) image-to-image / editing

python3 scripts/codex_image.py \
  --prompt "把这张草图做成干净的白板商业插图风格" \
  --image ./draft.png \
  --reference-image ./style-ref.png \
  --aspect landscape \
  --out-dir ./outputs

Agent execution rules

1. First confirm that ~/.codex/auth.json exists; if it does not exist, stop and prompt codex auth login
2. Prefer directly running python3 scripts/codex_image.py --help self-check CLI
3. When actually executing, give a clear prompt, do not pass only keywords
4. If the user wants a cover/accompanying image, by default prefer:
   • --aspect landscape
   • --quality high
5. If the user wants an avatar, icon, or square image, by default prefer:
   • --aspect square
6. If 401 is returned, directly prompt to log in to Codex again
7. If 403 is returned, first suspect Cloudflare / incomplete request headers / abnormal login state, and do not misjudge it as a prompt issue

Success output convention

On success, the script outputs JSON:

{"success": true, "image": "/absolute/path/to/file.png"}

The Agent should return:

• Final image path
• The prompt used (can be briefly described if necessary)
• Whether an input image / reference image was used

Failure handling

auth.json does not exist

Clearly prompt:

codex auth login

401 Unauthorized

Indicates that the local login state is invalid; recommend logging in again:

codex auth login

403 Forbidden

Indicates that it is most likely a Cloudflare / key request header / account state issue. First check:

• User-Agent: codex_cli_rs/0.0.0
• originator: codex_cli_rs
• ChatGPT-Account-ID

No image data was obtained

This indicates that the upstream SSE response format has changed, or only intermediate events were returned but there is no usable image field. In this case, check references/api-notes.md and update the script according to the new response structure.

Reference documentation

• API details:references/api-notes.md
• Core script:scripts/codex_image.py