generate-image

Generate images

Use executors/generate-image/generate-image.mjs for text-to-image and reference-image editing. It is a repository-owned, zero-dependency Node.js client. Do not call Codex system Skills, private scripts, or files under ~/.codex.

Define the asset

Specify:

• placement and purpose;
• subject and visible action;
• composition and aspect ratio;
• visual style and brand palette;
• exact text when text is essential;
• details that must appear;
• artifacts, logos, watermarks, and unrelated text to exclude.

Prefer real product screenshots when the image explains product behavior. Use generated visuals for concepts, scenes, covers, illustrations, diagrams, and supporting examples.

Generate

Use a prompt file for long or multilingual prompts:

node executors/generate-image/generate-image.mjs \
  --out <output.png> --prompt-file <prompt.txt>

Choose OpenAI explicitly when appropriate:

node executors/generate-image/generate-image.mjs \
  --model gpt-image-2 --out <output.png> \
  --prompt-file <prompt.txt>

--model accepts any gpt-image-* ID (sent to the OpenAI Images API at OPENAI_BASE_URL) or any gemini-*image* / nano-banana* ID (sent to the Gemini API at GOOGLE_GEMINI_BASE_URL). Compatible gateways may expose suffixed or tiered model IDs; list them with the gateway's /v1/models before choosing.

Add one --ref <image> argument for each reference image used in an edit.

For JSONL batch generation, put one job per line with prompt or prompt_file, out, and optional model, refs, size, or quality:

node executors/generate-image/generate-image.mjs \
  --batch <jobs.jsonl> --out-dir <directory> --concurrency 3

Read GEMINI_API_KEY or OPENAI_API_KEY from the process environment, root .env.local, or root .env, in that precedence order. Use GOOGLE_GEMINI_BASE_URL or OPENAI_BASE_URL only for a compatible HTTPS endpoint. Keep credentials out of prompts, files, logs, and commits. Do not read credentials from another application's private authentication files.

Before the first provider call, run python models/onboard-growth-lab/scripts/check_configuration.py. If image generation is optional-missing, tell the user that collection, copywriting, review, and deterministic rendering can continue without an image API. When generated assets are requested, point to CONFIGURATION.md, name the OpenAI and Gemini field options, and wait for the user to configure or skip. Never ask them to paste a key into the conversation. A paid verification call requires separate approval.

Control text and structure

List every required label verbatim in the prompt. State that all rendered text must match those strings exactly and that the image may contain no other text or watermark.

For a structured diagram, enumerate nodes, arrows, order, grouping, and direction explicitly. For edits, state what must remain unchanged.

Inspect every result

Use the Runtime's image viewer at full size. Check:

• relevance to the adjacent page content;
• every rendered character;
• subject and factual details;
• arrow direction, order, and grouping;
• visual artifacts and unintended objects;
• crop, aspect ratio, and mobile readability;
• consistency with the product's visual language.

Regenerate with one targeted correction when the result fails. Use a deterministic code-native graphic when repeated attempts cannot render exact dense text or structure.

Store the selected asset in the product's normal public directory with a stable descriptive filename, suitable compression, explicit dimensions, and descriptive alt text.