# Image Providers

> Reference for generating images across Google, OpenAI and ByteDance through one CLI. Use when generating or editing images, picking an image model, or resolving image API key and provider errors.

- Skill: `madappgang/image-providers` (Agent Skill)
- Install (CLI): `npx skillmds@latest add madappgang/image-providers`
- Raw SKILL.md: https://api.skillmd.com/api/skills/madappgang/image-providers/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MadAppGang (https://skillmd.com/u/madappgang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/madappgang/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

```bash
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.

| Alias | Model | Tier | API key (any of) |
|-------|-------|------|------------------|
| `nano-banana-pro` | Nano Banana Pro | studio quality (default) | `GEMINI_API_KEY`, `GOOGLE_GEMINI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` |
| `nano-banana` | Nano Banana 2 | pro-level at Flash speed | same as above |
| `nano-banana-lite` | Nano Banana 2 Lite | fastest / cheapest | same as above |
| `gpt-image` | GPT Image 2 | OpenAI | `OPENAI_API_KEY` |
| `seedream` | Seedream 4.5 | ByteDance via OpenRouter | `OPENROUTER_API_KEY` |

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

| Ratio | Use Case |
|-------|----------|
| 1:1 | Social media, icons |
| 3:4 | Portrait photos |
| 4:3 | Traditional photos |
| 4:5 | Instagram portrait |
| 5:4 | Landscape photos |
| 9:16 | Mobile, stories |
| 16:9 | YouTube, desktop |
| 21:9 | Cinematic, ultrawide |
| 1:4, 4:1, 1:8, 8:1 | Banners and strips (Nano Banana 2) |

## CLI Flags

| Flag | Description | Example |
|------|-------------|---------|
| `--style` | Apply style template | `--style styles/glass.md` |
| `--edit` | Edit an existing image | `--edit photo.jpg` |
| `--ref` | Reference image (repeatable) | `--ref style.png` |
| `--aspect` | Aspect ratio | `--aspect 16:9` |
| `--model` | Model alias | `--model seedream` |
| `--max-retries` | Retry attempts | `--max-retries 5` |
| `--no-check` | Skip the freshness advisory | |
| `--models` | List pinned models and key status | |

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

## Error Codes

| Code | Meaning | Recovery |
|------|---------|----------|
| `SUCCESS` | Operation completed | — |
| `API_KEY_MISSING` | That provider's key is unset | Export the key named in the error |
| `FILE_NOT_FOUND` | Style/edit/ref file missing | Check the path |
| `INVALID_INPUT` | Empty or over-long prompt | Fix the prompt |
| `API_ERROR` | Provider rejected the request | Read the message; check content policy |
| `PARTIAL_FAILURE` | Some batch items failed | Inspect individual results |

## 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