image-provider-routing git:20261011.bdeb65cA

Immutable. This exact content never changes and is served at /api/v1/blob/fb62e34a5b52112a.

---
model_tier: inherit
name: image-provider-routing
description: "Pick the image provider from job shape — text-in-image to Ideogram, photoreal to Flux, illustrative vector to Recraft, general to Gemini/GPT."
domain: product
personas: []
workspaces:
  - small-business
packs:
  - ai-image
trust:
  level: experimental
install:
  removable: true
scope:
  write: []
  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
execution:
  type: manual
---

# image-provider-routing

Route an image generation job to the right provider based on job shape. Adapters
are scaffold-tier (dry-run only) — selection produces a plan; execution waits on
promotion per `provider-lifecycle-discipline`.

## When to use

- Choosing which image model fits a brief (logo, banner, photo, icon, general art).
- Before calling any `node_modules/@event4u/agent-config/src/scripts/ai-image/adapters/*.sh` adapter.
- When the user asks "which image model should I use?" or "route this image job."

## Provider decision table

| Job shape | Provider | Why |
|---|---|---|
| Text-in-image (logo, banner, typographic art) | **Ideogram** | Best glyph rendering; raster models garble text |
| Photoreal (product shot, portrait, scene) | **Flux** | Photorealism specialist; routed via fal/Replicate |
| Icon the set lacks | `iconography` first, then [`svg-authoring`](../svg-authoring/SKILL.md) | The incumbent set wins; a missing glyph is hand-authored against its grid and checked — no provider involved |
| Simple geometric mark | [`svg-authoring`](../svg-authoring/SKILL.md) | A `rect`/`circle`/`path` mark is cheaper and more editable hand-authored than generated, and it ends in a file rather than a plan |
| Complex illustrative vector art | **Recraft** | The only job shape left for a vector provider. State the adapter's lifecycle in the answer: `experimental — scaffold tier, dry-run plumbing only`, so the caller knows no asset is produced |
| General art / edit / multimodal | **Gemini-image** or **GPT Image 2** | Broad capability; natural-language prompts |
| Budget-conscious 4K upscale | Flux via Replicate | Cost-competitive at high resolution |

Decision order: an icon → the incumbent set, then `svg-authoring` for a missing
glyph; a simple geometric mark → `svg-authoring`; text-in-image → Ideogram;
complex illustrative vector art → Recraft, with its scaffold-tier lifecycle
stated; photoreal → Flux; everything else → Gemini-image (default) or GPT
Image 2 (when an OpenAI key is available and an existing image is being edited).

The split exists because the single "Vector / SVG logo or icon" row sent every
icon and every geometric mark to an adapter whose header reads `experimental —
scaffold tier. dry-run plumbing only` and whose live calls exit at
the adapter's own live-call guard. The routed path ended in a plan;
the icon floor meanwhile sent icons to the set. Neither produced an asset for
the one case that needs one — a glyph the set does not have.

## Procedure

1. **Extract job shape** from the brief: does it need embedded text? vector output?
   photorealistic rendering? or general illustration?
2. **Apply table** — match the dominant shape to the provider row above.
3. **Check lifecycle tier** — all adapters are `experimental` (scaffold). Surface
   this before any live invocation.
4. **Confirm with the user** when shape is ambiguous (e.g., logo that could be
   vector OR raster typographic art → ask once).
5. **Emit the routing decision** in the Output format below.

## Output format

1. **Chosen provider** — name + one-line rationale citing the job-shape match.
2. **Lifecycle-tier caveat** — "adapter is experimental (scaffold tier); dry-run
   only until a smoke trace is captured per `provider-lifecycle-discipline`."
3. **Fallback** — if the primary adapter is unavailable or the smoke trace is
   missing, name the next best provider and what changes.

## Gotcha

- **Routing a text-in-image job to a photoreal model is the #1 failure** — send a
  logo/banner with embedded text to Flux and the text renders as garbled glyphs;
  it must go to Ideogram. Likewise a vector logo sent to Ideogram/Flux returns a
  raster PNG, not the editable `<path>` SVG a brand mark needs (→ Recraft).
- All four adapters (`ideogram.sh`, `flux.sh`, `recraft.sh`, `gemini-image.sh`) are
  **scaffold-tier** — dry-run plumbing only, no live generation yet. Routing
  produces a selection + plan; actual API calls require promotion to `stable`
  first (maintainer-captured smoke trace under `agents/reference/ai-image/smoke-traces/`).
  Surfacing a provider without its `experimental` tier caveat misleads the caller
  into expecting a rendered asset that won't come.

**Good example:** "Text logo for a bakery → Ideogram (text-in-image); lifecycle:
experimental — dry-run plan only."

**Bad example:** "Use Recraft for the product photo" — Recraft is the vector path;
photoreal jobs go to Flux.

## Do NOT

- Do NOT invoke an adapter without surfacing its lifecycle tier (all are `experimental`).
- Do NOT route a text-in-image job to Flux — Flux has no glyph renderer; text garbles.
- Do NOT route a vector/SVG job to Ideogram or Flux — neither outputs genuine `<path>` SVG.
- Do NOT skip `image-likeness-and-rights` when the brief names a real person or brand mark.
- Do NOT promote an adapter from `experimental` to `stable` — that is maintainer-only via smoke trace.

## See also

- [`prompt-engineering-image`](../prompt-engineering-image/SKILL.md) — translate the brief into provider-specific prompt grammar.
- [`provider-lifecycle-discipline`](../../rules/provider-lifecycle-discipline.md) — read lifecycle tier before any run.
- `node_modules/@event4u/agent-config/src/scripts/ai-image/adapters/` — the four adapter files and their header comments.
- [`media-governance-routing`](../../rules/media-governance-routing.md) — rights / likeness policies before generation.