Image Providers

Image Providers Reference

One interface, five pinned models across three providers. The CLI routes to the right API based on --model; you never call a provider SDK directly.

Quick Start

bun src/main.ts output.png "A minimal 3D cube"
bun src/main.ts output.png "A minimal 3D cube" --model seedream
bun src/main.ts --models        # what is pinned, and which keys are present

Models

Do not hardcode model IDs into prompts, docs, or commands. Run --models for the current pins — that command reads the registry directly, so it cannot drift. The aliases below are stable; the IDs behind them change with the plugin.

All five support --edit / --ref.

nano-banana-pro is the default. Only the provider whose model you request needs a key, and several names for the same key are accepted — the CLI reports which ones it looked for. --models shows what is ready right now.

An unknown --model is an error, never a near match. seedream5pro will not silently resolve to seedream; the CLI lists the supported set instead.

Input images on gpt-image use a direct-HTTP workaround

@ai-sdk/openai wraps edit images in a Blob (no filename) and the multipart helper appends it without one, so /images/edits rejects the request. Verified experimentally: identical bytes succeed the moment a filename is attached. The plugin therefore calls /images/edits directly for this one case (src/openai-edit.ts); everything else goes through the AI SDK. Delete that module once the SDK passes a filename.

Output format

Providers return what they return: Gemini and Seedream both emit JPEG even when the output path ends in .png. The CLI writes the file with the extension that matches the actual bytes and prints a note, rather than producing a mislabelled file.

Model pinning and freshness

These models are pinned deliberately and updated with the plugin — see CLAUDE.md → "Image model pinning" for the reasoning. A background check compares the pins against the live image catalog and prints an advisory when something newer ships. It is advisory only: it never switches models, never blocks generation, and stays silent when it cannot reach the catalog. Disable it with --no-check.

Aspect Ratios

CLI Flags

Multiple prompts produce numbered files: out_001.png, out_002.png, …

Error Codes

Retry Behaviour

Retries are handled by the AI SDK with exponential backoff on transient failures (rate limits, 5xx, timeouts). Default 3, tune with --max-retries.

Best Practices

1. Prompts — be specific about style, lighting, composition
2. Styles — use markdown templates for consistency across a batch
3. References — supply visual examples instead of describing a style
4. Batch — generate variations in one call, then pick
5. Model choice — nano-banana-pro when the image is the deliverable, nano-banana for the balanced middle, nano-banana-lite for high-volume batches, gpt-image for text rendering, seedream for photographic realism