codex-image-gen 0.1.1

Generate images from Python through Codex's Responses API bridge.

codex-image-gen

Generate images from Python through Codex responses

English · 한국어

---

codex-image-gen is a tiny, dependency-clean Python library for generating high-quality images through the Codex CLI's responses command and the Responses API image_generation tool.

It uses your existing Codex login, sends a raw Responses payload to codex responses, and returns Python dataclasses with decoded image bytes and metadata.

Demo

Generated with codex-image-gen + gpt-image-2.

Quick Start

uv add codex-image-gen

# or
pip install codex-image-gen

from pathlib import Path

from codex_image_gen import generate_image

result = generate_image(
    "A serene mountain landscape with a lake and pine trees, sunset light",
    size="1024x1024",
    quality="low",
    output_format="png",
)

image = result.images[0]
Path("mountain.png").write_bytes(image.data)
print("saved:", image.mime_type, len(image.data), "bytes")

That's it. Your image is saved locally.

Features

High-quality images Powered by gpt-image-2 through Codex responses.	Multiple input types Use local paths, URLs, data URLs, file IDs, and detail mappings.
Robust and reliable Clear exceptions for Codex failures, invalid JSON, missing image results, and bad base64.	Live-tested parameter surface Forward the gpt-image-2 options that work through the current Codex bridge.
Typed results Frozen dataclasses with image bytes, MIME type, response ID, call ID, revised prompt, and partial images.	Zero heavy deps Runtime uses only the Python standard library and the Codex CLI.

API Highlights

generate_image(
    prompt: str,
    *,
    images=None,
    model="gpt-5.5",
    size="auto",
    quality="auto",
    output_format="png",
    output_compression=None,
    background="auto",
    action="auto",
    input_image_mask=None,
    moderation=None,
    partial_images=None,
    reasoning_effort=None,
    reasoning_summary=None,
    text_verbosity=None,
    max_output_tokens=None,
    instructions=None,
    timeout=300,
    codex_bin="codex",
)

• Simple, composable function API.
• Rich result objects with images, metadata, raw response data, and optional partial images.
• Reference images can be local files, remote URLs, data: URLs, or file IDs.
• Masked edits use input_image_mask; pass a mask as a local path, URL, data: URL, or file ID. The mask must match the edited image's dimensions and format, stay under 50 MB, and include an alpha channel.
• Reasoning effort, reasoning summaries, text verbosity, max output tokens, timeouts, moderation, output format, compression, and custom instructions are first-class options.

Examples

Edit With References

result = generate_image(
    "Edit the reference image into a watercolor postcard",
    images=[
        "reference.png",
        {"file_id": "file_123", "detail": "high"},
    ],
    action="edit",
    output_format="webp",
    output_compression=75,
)

Path("postcard.webp").write_bytes(result.images[0].data)

Masked Edits

The diagram is a workflow illustration. For an actual masked edit, use an alpha-channel mask with the same dimensions and format as the image you edit.

result = generate_image(
    "Replace only the masked logo area with a white star",
    images=["product.png"],
    input_image_mask="mask_alpha.png",
    action="edit",
    background="opaque",
)

Path("edited.png").write_bytes(result.images[0].data)

Partial Images

result = generate_image(
    "Create a polished app icon of a glass bottle",
    partial_images=2,
)

for partial in result.partial_images:
    Path(f"partial-{partial.index}.png").write_bytes(partial.data)

Partial images are collected after codex responses exits. This function does not expose live streaming callbacks.

Reasoning Settings

result = generate_image(
    "Create a detailed concept sheet for a modular desk lamp",
    reasoning_effort="high",
    reasoning_summary="auto",
    text_verbosity="low",
    max_output_tokens=4096,
)

reasoning_effort supports none, minimal, low, medium, high, and xhigh. text_verbosity supports low, medium, and high.

Compatibility

This library intentionally exposes only the parameters that worked through the current codex responses bridge in live tests.

• The default mainline Responses model is gpt-5.5.
• The image generation tool always sends model="gpt-image-2".
• input_image_mask is exposed because it is documented for the Responses image_generation tool and was live-tested through the Codex bridge. The library forwards your mask; it does not synthesize the required alpha channel.
• background="transparent" is rejected before calling Codex.
• input_fidelity is not exposed because gpt-image-2 rejects it.
• previous_response_id and previous image_generation_call item references are not exposed because Codex requires store=false; prior items are not persisted. Use image bytes, local files, URLs, or file IDs for follow-up edits.

Development

git clone https://github.com/smturtle2/codex-image-gen.git
cd codex-image-gen
uv sync --dev
uv run ruff check .
uv run pytest
uv build

Project Links

Link	Description
Documentation	Full docs and guide
Examples	Real-world usage snippets
Contributing	Local development workflow
Issues	Report bugs and request features
Discussions	Ask questions
PyPI	Published Python package
Release v0.1.1	Wheel and sdist artifacts

Release

v0.1.1 is available on PyPI and as a GitHub Release with wheel and sdist artifacts.

Install from PyPI:

uv add codex-image-gen

# or
pip install codex-image-gen

License

MIT