tokenrouter-image-generator

Image Generation

Generate or edit images through Palebluedot Ai(PBD)-TokenRouter's multimodal image generation endpoint (`/v1/chat/completions`) using TokenRouter-compatible image models. Use for text-to-image or image-to-image requests when the user wants TokenRouter, `PBD_TOKENROUTER_API_KEY`, model overrides, or provider-specific `image_config` options.

Install

openclaw skills install @yb98k999/tokenrouter-images

TokenRouter Image Generation & Editing

Generate new images or edit existing ones using TokenRouter image-capable models via the Chat Completions API.

Usage

Run the script using absolute path (do NOT cd to the skill directory first):

Generate new image:

# Ensure outbound directory exists first
mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/pbd-tokenrouter-image-generator/scripts/generate_image.py \
  --prompt "your image description" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --model google/gemini-2.5-flash-image \
  [--aspect-ratio 16:9] \
  [--image-size 2K]

Edit existing image (image-to-image):

mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/pbd-tokenrouter-image-generator/scripts/generate_image.py \
  --prompt "editing instructions" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --input-image "path/to/input.png" \
  --model google/gemini-2.5-flash-image

Important: Default OpenClaw delivery path is ~/.openclaw/media/outbound/. Save generated images there so other OpenClaw flows can pick them up easily.

API Key

The script requires a TokenRouter API key. Check for it in this order:

--api-key argument
PBD_TOKENROUTER_API_KEY environment variable
Auto-detect from the current agent's tokenrouter provider config in ~/.openclaw/openclaw.json

If no API key is found

Before running the script, check whether the key is available:

test -n "$PBD_TOKENROUTER_API_KEY" && echo "Key found" || echo "No key"

If none of the above sources provides a key, do NOT run the script. Instead, guide the user through obtaining a key:

Tell the user they need a TokenRouter API key.
Direct them to open: https://www.tokenrouter.com
Walk them through the steps:
- Register or sign in on the website
- After login, navigate to the API Keys section
- Find the API Keys menu in the sidebar/navigation
- Click API Keys to enter the key management page
- Create a new API key and copy it
Once the user has the key, offer two options:
- Option A — Provide the key directly to the agent: The user can paste the key in the chat, and the agent passes it to the script via --api-key. This is the quickest way to get started — no environment setup needed.
- Option B — Configure as environment variable (persistent):
  - For this session only: export PBD_TOKENROUTER_API_KEY="sk-xxx..." (paste in terminal)
  - Persistent (zsh): Add the export line to ~/.zshrc then source ~/.zshrc
  - Persistent (bash): Add the export line to ~/.bashrc then source ~/.bashrc
After the key is available, proceed with the image generation command.

Important: Never skip this check. Running without a valid key will fail with Error: No API key provided or HTTP 401/403.

Optional attribution headers(optional)

--site-url or PBD_TOKENROUTER_SITE_URL
--app-name or PBD_TOKENROUTER_APP_NAME

Model + Image Config

--model <tokenrouter-model-id> is required (no script default)
Default / recommended: google/gemini-2.5-flash-image
Other supported image models (user can request a switch):
- openai/gpt-5-image
- openai/gpt-5-image-mini
- google/gemini-3-pro-image-preview
- google/gemini-3.1-flash-image-preview
Use --aspect-ratio for image_config.aspect_ratio (for example 1:1, 16:9)
Use --image-size for image_config.image_size (1K, 2K, 4K)

Note: TokenRouter docs show aspect_ratio and image_size as the common image config fields for image generation. Additional keys may exist for specific providers/models (for example Sourceful features). If a request fails, remove unsupported options or switch models.

Note: The script always sends modalities: ["image", "text"]. Image-only models (some FLUX variants) may reject this — if you get an unexpected error with a non-Gemini model, this may be the cause. No workaround is currently exposed via CLI args.

Default Workflow (draft -> iterate -> final)

Goal: iterate quickly before spending time on higher-quality settings.

Draft: smaller size / faster model
- --image-size 1K
Iterate: adjust prompt in small diffs and keep a new filename each run
Final: larger size or higher quality if the selected model supports it
- Example: --image-size 4K --aspect-ratio 16:9

Preflight + Common Failures

Preflight:
- command -v uv
- API key check (CRITICAL): The script will try --api-key, then PBD_TOKENROUTER_API_KEY, then auto-read from ~/.openclaw/openclaw.json (tokenrouter provider). If all fail, STOP and guide the user to https://www.tokenrouter.com to register and get a TokenRouter API key (see "If no API key is found" section above)
- test -d ~/.openclaw/media/outbound || mkdir -p ~/.openclaw/media/outbound
- If editing: test -f "path/to/input.png"
Common failures:
- Error: No API key provided. -> The script could not find a key from --api-key, PBD_TOKENROUTER_API_KEY, or ~/.openclaw/openclaw.json. Guide the user to https://www.tokenrouter.com to register and obtain a free TokenRouter API key, then set PBD_TOKENROUTER_API_KEY or pass --api-key
- Error loading input image: -> bad path or unreadable file
- HTTP 400 with model/image config error -> unsupported model or invalid image_config.aspect_ratio / image_config.image_size
- HTTP 401/403 -> invalid key, no model access, or quota/credits issue
- No image found in response -> model may not support image output or request format rejected

Filename Generation

Generate filenames with the pattern: ~/.openclaw/media/outbound/yyyy-mm-dd-hh-mm-ss-name.png

Examples:

~/.openclaw/media/outbound/2026-03-21-10-00-00-example.png

Prompt Handling

For generation: pass the user's description as-is unless it is too vague to be actionable.
For editing: make the requested change explicit and preserve everything else.

Prompt template for precise edits:

Change ONLY: <change>. Keep identical: subject, composition/crop, pose, lighting, color palette, background, text, and overall style. Do not add new objects.

Output

Save the first returned image to ~/.openclaw/media/outbound/output-name.png by default (pass that full path in --filename)
Supports TokenRouter's base64 data URL image responses (message.images[0].image_url.url)
Prints the saved file path
Do not read the image back unless the user asks

Examples