ChatGPT Subscription → Image Generation API Visual Overview: Understand chatgpt-imagegen at a Glance

visual guide · understand it on one page

Use Your ChatGPT Subscription as Your Image Generation API

Already paying the monthly fee for ChatGPT Plus / Pro / Team, but need to generate images from the command line or inside an AI agent? No need to top up OPENAI_API_KEY separately—a 300-line Python CLI directly reuses your subscription quota.

$ chatgpt-imagegen "a watercolor cat sitting on a windowsill" -o cat.png -> saved: cat.png (812,344 bytes) size=1024x1024 quality=medium # One command, no API key, no proxy, no daemon

There Are Actually Two Paths for OpenAI Image Generation

Most developers have only seen the path on the left. The path on the right is basically invisible to non-Codex CLI users—but it is actually already included in the subscription fee you pay every month.

Path A

Official API

Charged per image · Requires OPENAI_API_KEY

POST /v1/images/generations

Path B · Hidden Channel
ChatGPT SubscriptionFixed monthly fee · Auth via ~/.codex/auth.json
POST chatgpt.com/backend-api/codex/responses

Path B is the endpoint used by the built-in image_gen tool in OpenAI Codex CLI. What chatgpt-imagegen does is extract this route and wrap it in a CLI shell, making it scriptable and directly callable by AI agents.

Set It Up in 30 Seconds

# Prerequisite: install Codex CLI and log in once with your ChatGPT subscription account $ npm i -g @openai/codex $ codex login # Option A: install as an AI agent skill (Claude Code / Cursor / Codex Agent) $ npx skills add leeguooooo/chatgpt-imagegen -g # Option B: standalone CLI $ git clone https://github.com/leeguooooo/chatgpt-imagegen $ sudo install chatgpt-imagegen/chatgpt-imagegen /usr/local/bin/

Internal Protocol: What Happens During One Call

Read Codex login state ~/.codex/auth.json · ~/.codex/version.json

Construct the Responses API request tools: [{type: "image_generation"}]

POST to the internal endpoint chatgpt.com/backend-api/codex/responses

Consume the SSE stream image_generation_call.in_progress → generating → output_item.done

Decode and write to disk item.result (base64 PNG) → cat.png

Automatically refresh expired tokens auth.openai.com/oauth/token (refresh_token) → write back to auth.json

Capability Matrix: What Works and What Does Not

Capability	Subscription Channel	Notes
`--size`	✅ Works	Stable in testing: `1024x1024`, `1024x1536`, `1536x1024`. Larger sizes are passed through; success depends on your subscription tier
`--format`	✅ Works	png / jpeg / webp all work
Image quality `quality`	⚠️ Server decides	The subscription channel does not expose a controllable quality field. Requests for `high` are silently downgraded—so the CLI simply does not include this flag
Transparent background `background: transparent`	❌ Not supported	You must use the official API + `gpt-image-1.5`
Image edits `/v1/images/edits`	❌ Not implemented	If you need this, open an issue in the repository
Speed	15–40 s / image	End-to-end SSE streaming

Concurrency Test

4×

Concurrent requests all returned 200

~27s

Total time ≈ slowest single image

429 / serialization

≤10/min

Recommended sustained rate limit

In testing, a Plus account ran 4 chatgpt-imagegen calls at the same time, and the server neither rate-limited nor serialized them. But the subscription quota is shared with the ChatGPT web app and Codex CLI—do not run at >10 images/minute for long, or you will hit the daily rate limit.

When You Should Not Use This Tool

If any of the following applies, use the official API directly:

You need strict quality=high or transparent backgrounds—the subscription channel cannot provide them
You are building a production service for end users—this both violates the OpenAI Terms of Use and will burn through your own ChatGPT quota
You need precise per-call cost allocation—the subscription is a monthly fee and cannot be allocated to each call
You need stable throughput of >10 images/minute—subscription rate limits are tighter

Choose One: Local CLI or HTTP Gateway?

This repository

chatgpt-imagegen

Occasional image generation on a laptop, as a skill for an AI agent, or called from shell scripts. One Python file, no network service.

Sister project

agent-cli-to-api

Wraps the same subscription channel into an OpenAI-compatible /v1/chat/completions HTTP service for teams / multiple clients / remote calls.

Use Cases for AI agents

This is the core use case for this project. In the past, wanting Claude Code / Cursor / Codex Agent to "quickly draw one" usually meant stuffing in another OPENAI_API_KEY or hearing it say "I can't generate images." After installing this skill:

$ npx skills add leeguooooo/chatgpt-imagegen -g

The agent directly reuses the subscription quota you've already paid for—no new key, new account, or new environment variable needed. The repository's SKILL.md already spells out when the agent should call it, how to choose sizes, and how to handle errors.