Asset Goes Here Docs
Sign in
Making images with OpenAI
agh openai is a ready-made fulfiller for image requests. It claims a request, sends its brief to OpenAI's image API, and delivers the result with provenance ai and made by OpenAI <model>. It runs only while you run it, and each image is billed to your OpenAI API key.
What you need
- The agh CLI, signed in (
agh login) or set up with a tool's sign-in. Seeagh guide getting-started. - A place on the project that can claim requests:
fulfiller,artist,developeroradmin. - An OpenAI API key from platform.openai.com/api-keys. Image models may need a verified organization. Set a monthly budget under Billing before you start, since a large batch adds up.
Keep the key in an environment variable or a secret store, never in a command you type or a file you commit:
export OPENAI_API_KEY=... # paste it from your password managerTry it
See what a run would take, and the exact prompts, without claiming anything or spending:
agh openai --dry-run --count 5Then make one image and look at it under Review on the web page before you make more:
agh openai --count 1When you're happy with the results, fill a batch:
agh openai --count 20 --tag role=card_artOptions
| Option | What it does |
|---|---|
--count N | Fill up to N requests, one at a time. The default is 1. |
--tag key=value, --prefix id. | Only take matching requests, the same as agh next. |
--quality | low, medium, high or auto (the default). Lower is cheaper and faster, which suits drafts. |
--model | The image model. The default is gpt-image-2, or OPENAI_IMAGE_MODEL if set. |
--size | One size for every image, such as 1024x1024. |
--dry-run | Show the requests and prompts; claim and spend nothing. |
How requests become images
- Prompt: the brief, the request's specs, any note from a rejected attempt, and the request's notes. This is the same prompt the web page offers for ChatGPT.
- Size: a request's
sizespec picks the closest shape OpenAI supports: square1024x1024, landscape1536x1024or portrait1024x1536. The image keeps that size, so a768x1024request gets a1024x1536image; resize it in the game's import if it matters. - File type: follows the request's path,
.png,.jpgor.webp. Other image paths get a PNG. - Transparency: a spec of
background=transparentasks for a transparent background (PNG and WebP only).
When something goes wrong
The run stops at the first failure and says which request it had claimed. That claim expires on its own after two hours, and the request goes back to the queue. A refused key, an empty account or a rate limit all stop the run this way, so a mistake costs at most one image.
A rejected image goes back to the queue with its review note, and the next run puts that note in the prompt.
In Codex or a script
agh openai works anywhere the CLI does. In a Codex cloud environment, add OPENAI_API_KEY as a secret alongside the agh sign-in (see agh guide codex), allow api.openai.com in the network settings, and ask Codex to run agh openai --count 10.
For agents: this page as Markdown is at /docs/openai.md, and the CLI prints it with agh guide openai.