codex-image-gen 0.2.1

Generate images from Python through Codex OAuth Responses.

codex-image-gen

Generate images from Python through Codex OAuth Responses

English · 한국어

---

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

It uses your existing Codex login from ~/.codex/auth.json, sends a raw Responses payload to the Codex OAuth bridge, and returns Python dataclasses with decoded image bytes and metadata. It does not use OPENAI_API_KEY.

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",
    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 OAuth Responses.	Multiple input types Use local paths, URLs, data URLs, file IDs, and detail mappings.
Robust and reliable Clear exceptions for OAuth bridge failures, invalid JSON, missing image results, and bad base64.	Focused parameter surface Forward the gpt-image-2 options used by the 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.

API Highlights

generate_image(
    prompt: str,
    *,
    images=None,
    model="gpt-5.5",
    size="auto",
    output_format="png",
    output_compression=None,
    background="auto",
    input_image_mask=None,
    moderation=None,
    partial_images=None,
    reasoning_effort=None,
    reasoning_summary=None,
    text_verbosity=None,
    instructions=None,
    timeout=300,
    oauth_base_url="https://chatgpt.com/backend-api/codex",
    auth_file=None,
)

• 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.
• Size, output format, output compression, background, moderation, partial images, reasoning settings, text verbosity, timeouts, 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"},
    ],
    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",
    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 the streaming Responses request completes. 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",
)

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 used by the Codex Responses bridge.

• 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. 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. 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.2.1	Wheel and sdist artifacts

Release

v0.2.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