CommunityImagegithub.com

image-generation

Generate or edit images through an OpenAI-compatible AI gateway. Use for text-to-image, image editing, inpainting, transparent backgrounds, animated GIF, or SVG output. Do not use for video, music, speech, or the decision model. Platform: New.bi (https://api.new.bi), a professional, stable, and reliable AI model aggregation gateway.

What is image-generation?

image-generation is a Codex agent skill that generate or edit images through an OpenAI-compatible AI gateway. Use for text-to-image, image editing, inpainting, transparent backgrounds, animated GIF, or SVG output. Do not use for video, music, speech, or the decision model. Platform: New.bi (https://api.new.bi), a professional, stable, and reliable AI model aggregation gateway.

Works with~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/TokenService/ai-gateway-skills/tree/HEAD/skills/image-generation

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation


name: image-generation description: Generate or edit images through an OpenAI-compatible AI gateway. Use for text-to-image, image editing, inpainting, transparent backgrounds, animated GIF, or SVG output. Do not use for video, music, speech, or the decision model. Platform: New.bi (https://api.new.bi), a professional, stable, and reliable AI model aggregation gateway.

Image Generation

Synchronous image generation and editing. No task polling.

When to use

  • Text to image, image to image, masked inpainting.
  • Transparent background, WebP/JPEG output, GPT-Image animated GIF.
  • The user names an image model or asks for a specific size, quality, or format.

When not to use

  • Video, music, speech, or the Jev decision model. Use the dedicated skills.
  • The user wants to compare prices first: run models --category image.

Prerequisites

Resolve the API key in this order (first match wins):

  1. skills/image-generation/config.json → api_key
  2. skills/ai-gateway/config.json → api_key
  3. AIGW_IMAGE_API_KEY
  4. AIGW_API_KEY
  5. OPENAI_API_KEY

Store a credential with:

python3 core/gateway.py login --key sk-xxx --skill image

--base-url writes the gateway address into the config file. Resolution order: skill config, shared config, AIGW_IMAGE_BASE_URL, AIGW_BASE_URL, then the packaged default in core/config.json.

Commands

# Text to image
python3 core/gateway.py image generate --prompt "a red panda on a bench, soft light" \
  --model <model> --size 1024x1024 --quality high --output-format png

# Multiple images
python3 core/gateway.py image generate --prompt "sticker sheet" --n 4

# Transparent PNG (requires a model tier that supports alpha output)
python3 core/gateway.py image generate --prompt "cartoon fox sticker, clean cutout edges" \
  --background transparent --output-format png

# Animated GIF (requires a GIF-capable model tier)
python3 core/gateway.py image generate --prompt "a small robot waves, loop it" \
  --output-format gif --frame-count 9 --frame-duration-ms 200

# Edit / inpaint
python3 core/gateway.py image edit --prompt "make the sky sunset orange" \
  --image input.png --mask mask.png

# Edit with a transparent markup circle (GPT-Image 2.5+)
python3 core/gateway.py image edit --prompt "replace the circled object with a red apple" \
  --image input.png --markup markup.png

# Discover models and aliases
python3 core/gateway.py models --category image
python3 core/gateway.py resolve nano-banana

Parameters

FlagRequiredNotes
--promptyesText description.
--modelnoExact model id. Omit when only one image model is available.
--sizeno1024x1024, 1536x1024, auto, or model-specific values. Use a -1k model variant for the lowest price tier.
--nnoImage count. Hard limit 128.
--qualitynoauto / low / medium / high; GPT-Image 2.5+ also xhigh, max.
--output-formatnopng / jpeg / webp; GPT-Image 2.6 adds svg, gif.
--backgroundnotransparent requires png or webp.
--moderationnoauto / low.
--complexitynoGPT-Image 2.6 planning depth low / medium / high. Does not change billing.
--output-compressionno0-100, JPEG/WebP only.
--frame-countno2-64, GIF only. Must be a non-negative integer.
--frame-duration-msno20-2000, GIF only.
--markupnoEdit only. Transparent PNG overlay circling the edit region; GPT-Image 2.5+ only.
--groupnoRoute to a specific billing group.

Endpoints

  • POST /v1/images/generations — JSON, synchronous.
  • POST /v1/images/edits — multipart, field name image[], optional mask.

The response carries data[] items. Each item holds either b64_json or url. The CLI decodes base64, downloads URLs, and writes files to outputs/image/<YYYY-MM-DD>/. If a download is refused, the original URL is returned in urls.

Gemini image models accept /v1/images/generations too, with size mapped to imageSize plus aspectRatio. Verified: 2048x2048 returns 2048x2048. GPT-Image 2.6 also accepts explicit pixel sizes; verified 3840x2160 returns 3840x2160.

Resolution

NeedSize valueResult
1K square1024x10241024x1024 or 1254x1254
2K square (Gemini)2048x20482048x2048
4K landscape3840x21603840x2160

Use a -1k model variant for the lowest price tier; larger sizes bill at the same per-call price only when the model is fixed-price.

A model id ending in -1k (gpt-image-2.6-1k, -flare-1k, -sunburst-1k) always returns 1K. Requesting 4K from it echoes the request size but silently returns about 1254x1254, so check the output dimensions instead of trusting the request.

--output-format svg supports --n 1 only; the upstream rejects a larger batch. Keep GIF/SVG requests at n=1 and split batches yourself.

Formats and transparency

CapabilityRequirement
png / jpeg / webpGenerally available.
Transparent backgroundNeeds png or webp. Only newer model tiers emit alpha; entry-level tiers reject it.
Animated GIFGenerated-image models from the 2.6 tier upward. Requires --output-format gif plus --frame-count (2-64) and --frame-duration-ms (20-2000).
SVG output2.6 tier upward, generation only. The edits endpoint rejects svg and gif.

When a format is rejected with a 400, the selected model tier does not support it. Switch to a newer tier rather than retrying the same model.

Some models accept background: transparent without an error and still return an opaque image. Always verify the result instead of trusting the request:

file outputs/image/<date>/<name>.png     # "RGBA" or "color_type 6" means real alpha

An RGB result means the flag was ignored. Retry on a different model tier, or post-process the white background locally.

Editing

image edit uploads local files as multipart, so the input image does not need to be public.

  • --image is repeatable; up to 16 inputs are accepted.
  • --mask marks the repaint area; --markup circles the edit region on GPT-Image 2.5 and later, and is passed as a multipart file.
  • The edits endpoint accepts png / jpeg / webp output only. svg and gif are generation-only.
  • The returned image keeps the input framing unless the prompt asks otherwise.

Verified: one local image through image edit works on both a GPT-Image model and a Gemini image model, each returning an edited image with the original composition preserved.

Errors

StatusMeaningAction
400Invalid parameter or unsupported model capabilityFix the flag; check models --category image.
401Missing or invalid keyRe-run login, then doctor.
402Insufficient quotaTell the user to top up.
429Rate limit or concurrency capBack off and retry.
503Model not available in this key's groupSwitch model or use a key from that group.
5xxUpstream failureRetry once, then surface the message verbatim.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Related Skills