codex-images

Generate or edit images in Pi using your saved ChatGPT/Codex login.

Warning: This package calls the ChatGPT Codex Responses endpoint. It is a private, undocumented endpoint and may break or change without notice. Use it only if you accept that compatibility risk.

Requirements

• Node.js 20 or newer
• Pi with an openai-codex login

Run /login in Pi and select the ChatGPT/Codex provider before using the tool.

Local installation

pi install /absolute/path/to/codex-images

Restart Pi or run /reload, then ask Pi to create or edit an image.

Install the published package from npm with:

pi install npm:codex-images

Usage

The extension registers the codex_image tool. Ask Pi plainly; Pi supplies the tool options.

Generate a new image

Create a PNG illustration of a red fox reading under a lantern at dusk.

Edit from a local reference

Use assets/logo.png as a reference. Make the logo look hand-painted in watercolor, keeping its main shape.

Edit from recent conversation images

Use the most recent image in this conversation as a reference and make it a winter scene. Set recent_images to 1.

Choose an exact output filename

Create a square product image of a ceramic mug. Save it as art/mug.webp by setting destination to art/mug.webp.

Tool options

| Option | Values | Default | Notes | | --- | --- | --- | --- | | prompt | Non-blank text | Required | Describe the new image or what to change. | | reference_paths | Up to five non-blank local paths | [] | PNG, JPEG, or WebP. Relative paths use Pi's current project directory; listed order is preserved. | | recent_images | Integer 0–5 | 0 | Selects the newest visible conversation images. They are appended after local references. | | size | auto, 1024x1024, 1536x1024, 1024x1536 | auto | Requested output size. | | quality | auto, low, medium, high | auto | Requested image quality. | | format | png, jpeg, webp | png, unless the destination filename has a supported extension | An explicit format must agree with a supported filename extension. | | destination | A path | ~/Downloads/ | Relative paths use Pi's current project directory. | | routing_model | luna, terra, sol | luna | Selects the Codex model used to interpret and route the image request. |

There is no separate “edit” switch: no references creates a new image; one or more references tells Codex to preserve, change, combine, or use them as inspiration.

Paths and safe saving

~ and ~/... expand from your home directory. Relative paths resolve from Pi's current project directory.

A destination is treated as a directory when it already exists as a directory, ends in / or \, or is a path that does not exist and is not a supported image filename. A non-directory destination ending in .png, .jpg, .jpeg, or .webp is a complete filename. An existing non-image file is rejected.

Directory destinations receive a UTC name such as codex-image-20260805-142301.png; missing directories are created. A filename extension chooses its format when format is omitted (.jpg and .jpeg mean JPEG). An explicit conflicting format is rejected.

Existing images are never overwritten. The package publishes a fully written temporary image atomically. If the requested filename already exists, it tries -2, then -3, and so on (for example, mug-2.webp). Atomic publication is the commit point: cancellation before publication means cancellation with no final file, while publication wins a concurrent cancellation.

Limits, retries, and timeout

• Prompt: the core limit is exactly 32,000 UTF-16 code units. Pi's TypeBox maxLength is an early Unicode-length filter; the core validation is authoritative.
• References: at most five local and recent references combined; PNG, JPEG, and WebP only; 20 MiB per reference and 50 MiB combined. References are validated from their bytes and are not silently resized, converted, or deduplicated.
• Stream: 100 MiB total Server-Sent Events stream cap; 75 MiB per SSE line and 75 MiB per SSE event safety caps. Error response bodies are read only up to 64 KiB for classification.
• Output: 50 MiB maximum decoded output image. The output must have valid image bytes and match the requested format.
• Retries: temporary network failures, HTTP 408, HTTP 429, and HTTP 5xx may retry. There are at most five HTTP attempts total across retries and model fallback. Exponential jitter starts with a 500 ms ceiling; each delay and any Retry-After value is capped at 30 seconds.
• Timeout: one five-minute overall deadline covers login lookup, fallback, retries, streaming, validation, and saving. Cancellation stops active requests and retry waits.

A complete valid image is not retried. Invalid input, authentication, policy, and deterministic response-validation failures are not retried.

Routing models and fallback

The image-generation tool renders the image. The routing model helps interpret and route the request:

• Luna (luna → gpt-5.6-luna) is the default for clear, straightforward requests.
• Terra (terra → gpt-5.6-terra) is useful for more complex or ambiguous instructions.
• Sol (sol → gpt-5.6-sol) is for the most difficult or ambiguous instructions.

Fallback happens only when Codex says the chosen model is unavailable or unsupported:

• Luna → Terra → Sol
• Terra → Sol → Luna
• Sol → Terra → Luna

Authentication, invalid requests, policy failures, timeouts, rate limits, and general server failures do not change the routing model. The result reports the routing model that succeeded.

Troubleshooting

| Error | What it means | What to do | | --- | --- | --- | | AUTH_REQUIRED | Pi has no usable saved Codex login. | Run /login, select ChatGPT/Codex, then retry. API-key and command-line fallback are not available. | | INVALID_INPUT | A prompt, option, reference, path, or destination is invalid. | Check the option values, reference count and formats, size limits, and destination rules. | | CODEX_UNAVAILABLE | The private endpoint, network, timeout, rate limit, server, or model is unavailable. | Retry later. If it persists, the undocumented endpoint may have changed. | | GENERATION_FAILED | Codex did not return one valid image in the requested format. | Simplify the request and retry; check that the requested format is supported. | | SAVE_FAILED | The package could not create, write, or atomically publish the output. | Check the destination path, available disk space, and filesystem support for hard links. | | CANCELLED | Pi cancelled the operation. | Retry if you still want the image. Before publication no final file is created. |

Privacy and security

Prompts and reference images go to OpenAI for generation. This package has no telemetry. It logs no credentials, account identifiers, complete prompts, image data, base64 output, or raw backend response bodies. It uses Pi's saved openai-codex login only; it does not provide an API-key, command-line, or credential-file fallback.

Testing

Normal automated tests never contact OpenAI. A live Codex smoke test consumes image allowance and is not run automatically; run one only with explicit approval.

Version 1 scope

Version 1 does not include transparent-background controls, remote image URLs, API-key or command-line authentication fallback, service-tier controls, a background daemon, global configuration files, user-selectable image-generation models, telemetry, or package publication.

Possible later upgrades include transparency when supported, output compression, remote references, API-key or CLI fallback authentication, service-tier controls, and image-model selection. Any publication is a separate decision.

License

This project is released under the MIT License.