Generate 2D Media

The route layer. It makes raw media; the owning skill plans the asset before and checks it after.

Use when

• Any Forge skill (or its pipeline script) needs a generated image, reference edit or image-to-video clip.
• Once per session, to see which routes work here (forge_doctor.py).
• The user asks to configure an API key, to use a particular route, or about spend.

Do not use when

• Planning, keying, registering or packaging: generate2dsprite, video2dsprite, generate2dmap.
• Code-drawn art the user asked for: codeart2d.

Route order (owner decision 2026-10-06)

1. API, every provider whose key is configured, in this order (the user's providers.order goes first). Images: OpenAI (gpt-image-2.5-sunburst), Google Gemini (gemini-3.1-flash-image; --tier hero takes gemini-3-pro-image for hero masters), xAI (grok-imagine-image-2.0), BytePlus ModelArk (Seedream 5.0), fal.ai (reference edits). Video: xAI (grok-imagine-video-1.5; --tier draft takes 1.5 Lite), BytePlus ModelArk (Seedance 2.0), fal.ai (Kling v3, Veo 3.1, Luma, MiniMax, Wan, Vidu, LTX). A configured key is the owner's consent: no per-call question.
2. Local: your own image tool if you have one (Codex image_gen, Grok's native tools), otherwise the user's signed-in CLI: Codex (local CLI) image_gen with references attached, then Grok (local CLI) one-shot image or edit; video Grok (local CLI) in ACP mode. An installed CLI is used as is; its first successful run records the VERIFIED proof.
3. codeart2d, only when the user explicitly asks for code-drawn art or route_media.py prints no-route (exit 3).

Always name the route that ran ("OpenAI API", "Google Gemini API", "xAI API", "BytePlus ModelArk API", "fal.ai API", "Codex (local CLI)", "Grok (local CLI)"). Details: route-media.md.

Capability check (once per session)

Run python "<skill-dir>/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json, where <tools> lists the media tools in your own tool list (image_gen, image_edit, image_to_video) or none. Its ROUTES block shows which API keys are configured (yes or no, never a key), the local readiness of each CLI and the resolved order (routeOrder). If encoding.stdout fails, set PYTHONUTF8=1.

Generate (route_media.py)

Success prints one ASCII JSON line and exits 0: {"status":"ok","route":"api:openai","artifact":"<out-dir>/generated.png","sha256":...,"estimateUsd":...} plus model, job and, for video, lastFrameUsed, durationRequested and durationUsed (a length is snapped to the nearest one the model renders; Grok (local CLI) renders 6 or 10 s and never pins a last frame) and crop when the frames were padded to 16:9 for a model without 1:1. Every clip is published without audio. No route prints {"status":"no-route","fallback":"codeart2d"} and exits 3. A failure prints one error: <route>: <code>: <message> line and exits 1. A route whose account cannot serve the request (no credit, no access, not signed in) passes it to the next route; a refusal such as moderation stops. Write prompts yourself into UTF-8 files; local routes take the size and every instruction from the prompt.

Keys

Each provider reads only its own key: OPENAI_API_KEY, GOOGLE_API_KEY or GEMINI_API_KEY (GOOGLE_API_KEY wins), XAI_API_KEY, ARK_API_KEY (BytePlus ModelArk) and FAL_KEY (fal.ai), from the environment or from the user config file, never from a project: %APPDATA%\agent-sprite-forge\config.json on Windows, ~/.config/agent-sprite-forge/config.json elsewhere ($XDG_CONFIG_HOME when set), as {"OPENAI_API_KEY": "...", "FAL_KEY": "..."} with optional "models" and "providers": {"order": [...]}. Never print, log, commit or paste a key, and never put one in a prompt. A Codex or Grok sign-in is never an API key.

Spend and the ledger

Every call, paid or local, is a line in <project>/.forge/ledger.jsonl with its estimate (estimateUsd is null when no verified price exists; say "price unknown"). There is no cap by default; --budget-usd, --max-calls, FORGE_MAX_PAID_REQUESTS and FORGE_SESSION_IMAGES / FORGE_SESSION_VIDEOS set one when the user asks. python "<skill-dir>/scripts/media_ledger.py" summary shows spend; media_ledger.py settle <id> --status ... closes an unknown outcome.

Lower-level tools

Host notes

• Codex: image_gen is your own tool: with no configured key use it and adopt the result (cli_media.py adopt); scripts reach Codex (local CLI) through route_media.py. This skill is explicit-only in Codex.
• Claude Code: no media tools; route_media.py takes the API or the local CLIs. <skill-dir> is ${CLAUDE_SKILL_DIR}; look at results with Read.
• Grok: its native media tools are your own tools; the same grok executable is the "Grok (local CLI)" route for other hosts. Agent setups: agent-profiles/README.md.

Commands and outputs

Run each tool as one line from the user's project root: python "<skill-dir>/scripts/<tool>.py" .... Outputs go to a new --out-dir inside the project. Results are raw media: hand them to the owning skill for identity, size, alpha, motion and seam checks. Keep prompts, input hashes, job ids and result hashes; report the model requested and the model returned separately. Providers: provider-survey.md (last verified 2026-10-06, with the shutdown dates); capabilities: references/capabilities.json (python "<skill-dir>/scripts/media_providers.py" list); prices: references/prices.json; data contracts: references/schemas/media.schema.json.