mcpField
C
codex-gpt-image

codex-gpt-image

github.com/ningzimuCreative & media70262 installsUpdated 7w ago
Repository

About codex-gpt-image

codex-gpt-image is a skill for generating and editing images through Codex OAuth. It is intended for agents that support SKILL.md but lack a native image tool, and uses local Codex authentication rather than the OpenAI API-key path.

Key features

  1. 01Generate images through Codex OAuth
  2. 02Edit images using reference inputs
  3. 03Check authentication and log in
  4. 04Save generated images to local files

Use cases

  1. 01Generate images through a Codex subscription
  2. 02Edit images without using OPENAI_API_KEY
  3. 03Reuse a local image workflow across agents

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ningzimu/codex-gpt-image --skill codex-gpt-image

After installing, type/codex-gpt-imagein Claude Code to confirm it loaded.

Bundled filesreferences/openai-images-api-parameters.mdscripts/codex_gpt_image.py

Details

From the project README

Codex GPT Image

Use this skill to generate or edit images through Codex OAuth instead of the OpenAI API-key path. The bundled CLI reads the local Codex auth file and calls the Codex Images backend endpoints.

When To Use

  • The user asks to use gpt-image-2.5-flare or GPT Image through Codex auth/subscription.
  • The current agent supports SKILL.md but does not have a native image tool.
  • The user explicitly does not want to use OPENAI_API_KEY.
  • The user wants the same local image workflow across Codex, Claude Code, OpenClaw, Hermes Agent, or similar agents.

Do not use this skill when the user wants the official OpenAI Images API, an OpenAI-compatible gateway, or API-key billing. This skill is deliberately Codex-OAuth-only.

Core Workflow

All CLI commands below assume the working directory is this skill folder. Otherwise, resolve the absolute path to scripts/codex_gpt_image.py from this SKILL.md.

  1. Check local Codex auth:

    python3 scripts/codex_gpt_image.py auth-status

  2. If Codex auth is missing, run the device-code login flow:

    python3 scripts/codex_gpt_image.py login --open-browser

    The CLI prints a browser URL and a short user code. The user must complete this step; never ask them to paste tokens.

  3. Generate an image with the user's actual prompt. Choose only the CLI flags required by the request, and do not reuse prompt wording from this skill.

  4. Edit or use reference images by passing one or more --image inputs. For edits, build the prompt from the user's requested changes and the invariants that must stay unchanged.

  5. Report the saved path(s), requested model, actual output size when inspected, and whether Codex OAuth was used. Do not claim the requested model was used unless the backend identifies it.

Defaults

  • Auth file: ~/.codex/auth.json
  • Override auth file: CODEX_AUTH_FILE=/path/to/auth.json
  • Login fallback: login uses OpenAI Codex device-code auth and writes the same auth file
  • Login client id: --client-id, CODEX_APP_SERVER_LOGIN_CLIENT_ID, then the public Codex default
  • Images base URL: https://chatgpt.com/backend-api/codex
  • Image model: gpt-image-2.5-flare
  • Size: auto
  • Quality: auto
  • Background: auto
  • Moderation: auto
  • Output format: png
  • Output compression: 100 for jpeg and webp

For detailed parameter values, defaults, model-specific constraints, and CLI mapping, read references/openai-images-api-parameters.md.

Parameter Selection

Prefer the official API defaults unless the user request requires a specific option. Read the reference before choosing explicit model, size, quality, background, moderation, or output_format values.

Prompting

Keep prompts explicit and production-oriented:

  • State the intended asset type.
  • Quote any exact visible text.
  • Specify composition, background, style, and constraints.
  • For edits, repeat invariants: what must stay unchanged.
  • Avoid adding logos, watermarks, or extra text unless requested.

Failure Handling

  • Missing auth file: run codex_gpt_image.py login --open-browser, or ask the user to run codex login, then retry.
  • 401/403: the Codex OAuth token may be expired, the account may not have access, or the endpoint may reject the session. Ask the user to refresh Codex auth.
  • Network failures: retry once if the request is idempotent and the user accepts possible duplicate image generation.
  • Never print or paste tokens from ~/.codex/auth.json.

Implementation Notes

The CLI sends Codex Images requests with:

  • generation endpoint: POST https://chatgpt.com/backend-api/codex/images/generations
  • edit endpoint: POST https://chatgpt.com/backend-api/codex/images/edits
  • auth: Authorization: Bearer <access token from ~/.codex/auth.json>
  • model: gpt-image-2.5-flare

It parses the JSON Images response and writes returned base64 image payloads to local files.

GPT Image 2.5 Compatibility

Use the default Flare model for everyday generation, or select --model gpt-image-2.5-sunburst for precise editing. Both models and their dated snapshots support xhigh and max quality and transparent backgrounds with PNG/WebP. Older models cannot use the new quality levels; this CLI keeps transparency disabled for older models. Codex OAuth access depends on the account and backend rollout.

Codex OAuth probes on 2026-09-11 also accepted an invalid model name, omitted the actual model ID, and returned dimensions different from the requested size. Successful generation does not verify model or quality selection. Treat these flags as requested settings; do not present public API capabilities as guaranteed OAuth backend behavior.

Comments

Markdown supported