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

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

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