image

name	image
description	Generate, edit, or upscale images with ppq.ai models — text-to-image from a prompt, image-to-image editing/retouching/restyling of an existing photo, deterministic upscaling, background removal, SVG generation. Use whenever the user wants to create or transform an image (via ppq, or when no other image backend is configured).
argument-hint	[gen|edit|upscale|models] [prompt or file]
allowed-tools	["Bash(bash ${CLAUDE_SKILL_DIR}/scripts/image *)","Bash(bash \"${CLAUDE_SKILL_DIR}/scripts/image\" *)","Bash(uv run ${CLAUDE_SKILL_DIR}/scripts/ppq_image.py *)","Bash(uv run \"${CLAUDE_SKILL_DIR}/scripts/ppq_image.py\" *)","Bash(pipx run ${CLAUDE_SKILL_DIR}/scripts/ppq_image.py *)","Bash(pipx run \"${CLAUDE_SKILL_DIR}/scripts/ppq_image.py\" *)","Skill(ppq:setup)","Skill(ppq:setup *)","Skill(ppq:topup)","Skill(ppq:topup *)"]

ppq.ai image generation

One self-contained script behind a uv-locating launcher (no install needed):

bash ${CLAUDE_SKILL_DIR}/scripts/image gen "a red fox in fresh snow, golden hour" --ar 16:9 -o fox.png
bash ${CLAUDE_SKILL_DIR}/scripts/image edit photo.jpg "restyle as a 1940s film-noir portrait" -o noir.jpg
bash ${CLAUDE_SKILL_DIR}/scripts/image upscale small.jpg -o big.png
bash ${CLAUDE_SKILL_DIR}/scripts/image models [filter]   # live catalog + prices (free, works without a key)

Run these exactly as shown — one command, full script path, no cd, no SCRIPT= variable, nothing chained, and the path copied byte-for-byte (keep Windows backslashes as printed — rewriting separators or re-quoting breaks the match). These exact shapes are pre-approved (allowed-tools) for as long as this turn lasts; any other shape falls back to a normal permission prompt. If a literal unsubstituted ${CLAUDE_SKILL_DIR} appears above (older harness), build the path from the "Base directory for this skill" header instead — still the same launcher, never an improvised alternative. Keep iteration inside this one turn — clarifying the prompt, picking between drafts, retrying: ask with the AskUserQuestion tool (numbered choices), whose answer returns as a tool result without ending the turn, so the grant stays armed. A prose question ends the turn and resets the grant.

Key comes from $PPQ_API_KEY or ~/.config/ppq/api-key. Every paid call prints cost $… — always relay the cost to the user. HTTP 402 = balance empty → invoke the ppq:topup skill; 401 or no key at all → the ppq:setup skill installs one or creates an anonymous account from scratch. Invoke either in this same turn — their Skill(...) calls are pre-approved here.

The launcher finds uv even when it's off the Bash tool's PATH (it checks a login shell, then on Windows the registry-backed Path) and falls back to pipx. Never prefix export PATH=…; or any other setup command — chaining breaks the pre-approved match and triggers a permission prompt. If the launcher reports that neither uv nor pipx exists, relay its install hints; don't fall back to bare python3 — the dependencies live in the script's inline metadata and won't be installed.

Picking a model

Prices surveyed 2026-07-23; re-check with models when it matters.

Task	Model	$/image	Notes
t2i default	nano-banana-2	0.092	best prompt-following; honors --ar up to 21:9
t2i cheap draft	imagen4-fast	0.023	good for iterating on prompts
t2i cheapest	fast-sdxl	0.014	lower quality
t2i alternatives	seedream-4.5 0.046, flux-2-pro 0.063, imagen4-ultra 0.069, grok-imagine 0.033
edit default	nano-banana-2-edit	0.092	proven best at identity-preserving face edits
edit cheap	qwen-image-2-edit	0.040	also seedream-4.5-edit 0.066, kling-v3-image-edit 0.032; flux-kontext-pro 0.029 502'd on data-URI input when tested (2026-07)
upscale	topaz-upscale	0.041	deterministic; aura-sr 0.002 (cheap), crystal-upscaler 0.026
background removal	birefnet-v2	0.002	use edit subcommand with any prompt
SVG / vector	recraft-v4.1-svg	0.092	raster: recraft-v4.1 0.046

Workflow for a "good" final image: iterate the prompt 1–2× on a cheap model, then render the final on the good one. For a batch of edits, run several script invocations in parallel (network-bound).

Practical knowledge (learned the hard way)

• Aspect ratio: many models ignore --ar/size and return a square — crop yourself afterwards. nano-banana-2 genuinely renders wide frames (21:9); imagen4-* honors 16:9.
• Prompts for edits: state what must be preserved explicitly, e.g. "Keep the face, features, hair, expression and identity exactly the same. Photorealistic." Illustrated/cartoon restyles redraw faces and lose likeness.
• --seed is best-effort — hosted models don't guarantee bit-exact repro even with a seed.
• Inputs are uploaded as data-URIs; the script downscales the long edge to 1536 px (--max-px 0 to keep full size). Upscale inputs go lossless PNG, unresized.
• The script already retries 3× (a 200 can carry a provider error page instead of an image) and saves the returned bytes unrecompressed.
• Image-to-video models (*-i2v, veo3-*, kling-*…) also appear in the catalog but use the async POST /v1/videos endpoint — not this script.

Raw API (if the script doesn't cover a parameter)

POST https://api.ppq.ai/v1/images/generations with bearer auth, JSON body: model, prompt, plus optional image_url (data-URI or https), aspect_ratio ("16:9"), resolution ("1K"|"2K"|"4K"), n (1–4), quality, negative_prompt, output_format, seed. Response: {"data":[{"url": …}], "cost": …}.