Image Generation API

Generate images with the Stable Image API — the Codex ImageGen skill and the OpenAI-compatible API reference.

When using the GetToken relay service, Codex cannot generate images directly through the built-in client ImageGen.

Built-in ImageGen needs a key that can connect directly to the OpenAI Images API. GetToken provides a relay service API key, and that key does not take over the direct ImageGen path inside Codex.

Image generation with the GetToken relay service must use the gettoken-imagegen Skill.

Install It

Open the Stable Image API console, choose macOS or Windows, copy the one-line install command, run it, and restart Codex.

Already installed? Run the same command again to update to the latest version. Your config and task history are preserved. You can also let Codex run <skill>/bin/<platform>/gettoken-imagegen update.

Requirement

When generating images in Codex, image generation tasks must be handled by gettoken-imagegen.

Do not use:

  • Built-in Codex ImageGen
  • Image generation paths that depend on an official OpenAI direct key

Use:

  • gettoken-imagegen Skill
  • GetToken API Key
  • OpenAI-compatible Images API endpoint

Configure the Endpoint

The installer writes the image API key and stable image endpoint into the skill configuration. Do not expose the API key in source code, screenshots, or public commands after installation.

Install Location

The Skill is installed under ~/.agents/skills/gettoken-imagegen. Run the install command on the same machine where Codex runs.

Troubleshooting

Why not use built-in ImageGen directly

Built-in Codex ImageGen requires a key that can connect directly to the OpenAI Images API. When using the GetToken relay service, that direct path does not work, so gettoken-imagegen must handle image generation.

Codex Cannot Find the Skill

Confirm the Skill is installed under ~/.agents/skills/gettoken-imagegen, then restart Codex.

Windows Installation Does Not Work

Confirm that you use the PowerShell install command on native Windows.

Generation Fails

Check:

  1. The image API key is configured.
  2. You can reach the stable image endpoint.
  3. The output directory exists and is writable.

API Reference

The GetToken Image Generation API follows the OpenAI Images specification and supports text-to-image generation and image edits. Configured models are listed below; availability depends on the request result.

Loading models…

The GPT Image 2.6 family additionally supports complexity control, markup-guided edits, and SVG and animated GIF output; the related parameters are documented below.

  • Base URL: https://api.gettoken.dev/image/v1 (China-optimized: https://api.clawto.link/image/v1)
  • Endpoints:
    • POST /images/generations (text-to-image)
    • POST /images/edits (image edits, multipart/form-data)
  • Auth: Authorization: Bearer <image API key> (image keys are managed separately)
  • Response: images may be returned as data[].b64_json or data[].url, depending on the response

Text-to-image /images/generations

ParameterTypeDescription
promptstringRequired. Text description of the image to generate.
modelstringSee the current model list above.
nintegerNumber of images to generate. Default 1.
sizestringauto / 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 4096x4096, or a custom WIDTHxHEIGHT
qualitystringauto / low / medium / high / xhigh / max. xhigh and max are 2.5- and 2.6-only.
complexitystringlow / medium / high. 2.6 only; defaults to high when omitted and carries no extra fee.
backgroundstringauto / opaque / transparent. transparent requires PNG or WebP output.
output_formatstringpng / jpeg / webp / gif / svg
output_compressioninteger0-100, applies to jpeg / webp only. Lower means stronger compression.
frame_countintegerGIF frame count, 2-16, defaults to 9. Only valid with output_format=gif.
frame_duration_msintegerDelay per GIF frame in milliseconds, defaults to 200. Only valid with output_format=gif.
moderationstringauto (default) / low. Controls moderation strictness.
safety_identifierstringOptional stable pseudonymous id, 128 characters max. Replaces the deprecated user parameter.
streambooleanStream the result via server-sent events.
partial_imagesinteger0-3. Number of partial previews in streaming mode.

Image edits /images/edits

ParameterTypeDescription
imagefileRequired. Image(s) to edit, uploaded via multipart/form-data.
promptstringRequired. Text description of the edit.
maskfileOptional. Mask whose transparent areas indicate where to edit.
markupfileOptional transparent PNG annotation layer that circles the area to change. Must match the first input image's dimensions, contain transparent pixels, and cannot be combined with mask.
modelstringSee the current model list above.
n / size / quality / complexity / background / output_format / output_compression-Same meaning as text-to-image.
input_fidelitystringlow (default) / high. high preserves details of the input image (faces, logos, etc.).
stream / partial_images-Same meaning as text-to-image.

Examples

Text-to-image:

curl https://api.clawto.link/image/v1/images/generations \
  -H "Authorization: Bearer $IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A clean product photo on a white desk",
    "n": 1,
    "size": "2048x2048",
    "quality": "high",
    "complexity": "medium",
    "background": "auto",
    "output_format": "png"
  }'

Image edit:

curl https://api.clawto.link/image/v1/images/edits \
  -H "Authorization: Bearer $IMAGE_API_KEY" \
  -F "model=gpt-image-2.6-flare" \
  -F "prompt=Replace the background with a clean studio backdrop" \
  -F "image=@input.png" \
  -F "input_fidelity=high" \
  -F "size=2048x2048" \
  -F "quality=high"

Sizes, formats, and the 2.6 additions

Sizes. Besides the presets 1024x1024, 1536x1024, 1024x1536, 2048x2048, and 4096x4096, you can pass a custom WIDTHxHEIGHT. Both edges must be multiples of 16, the aspect ratio must stay between 1:3 and 3:1, and neither edge may exceed 4096. Anything above 2560x1440 sits in the upstream experimental range and is not guaranteed.

Complexity (complexity, 2.6 only). This controls how much the model plans before rendering. It is independent of quality and carries no extra fee. Use low for focused edits such as a background or a sign, and high for dense text, complex layouts, and object relationships; higher complexity adds latency and can introduce unwanted changes. Omitted values are treated as high.

SVG output. Set output_format to svg for editable vector graphics such as icons and illustrations. It requires n=1 and does not support streaming, partial_images, or output_compression. /images/edits does not support SVG, and an SVG is not a valid edit input. The response is a base64-encoded UTF-8 XML document; save it with a .svg extension.

Animated GIF output. Set output_format to gif and control the animation with frame_count (2–16, default 9) and frame_duration_ms (default 200). GIF output does not support transparent backgrounds, output_compression, streaming, or partial images, and size describes each frame. The response is base64-encoded GIF bytes; save it with a .gif extension.

Markup-guided edits (markup). /images/edits accepts an extra transparent PNG annotation layer that circles the region to change, described in prompt. The overlay must match the first input image's dimensions and contain transparent pixels, and it cannot be combined with mask. Use it for "change only the circled area and keep the rest untouched".

Pricing (per image)

Size tierBilling boundary (longest edge)Standard (USD)Stable (USD)
1K<= 1024px0.1341.5
2K1025-2048px0.2013
4K> 2048px0.2684

Stable Image tiers are classified by the longest edge of the actual output size returned upstream; only when no recognizable size is returned does the requested size apply. auto, empty, or unrecognized sizes fall back to 2K. The direct API passes custom WxH through, but generation still depends on upstream support for that size.

On this page