nano-banana-pro — single-image generator via OpenRouter

Generates one PNG from a text prompt (optionally seeded with an input image for editing). Used by meta-short-drama for per-shot first-frame generation, but standalone for any single-image request.

Inputs (with:)

To pass an input image for edit mode, invoke the script directly with --input-image PATH. The meta-skill engine does not route input images through with: by convention; for edit workflows call the script.

Auth

API-key resolution order (first hit wins):

1. --api-key CLI argument (rarely used; meta-skills don't pass it)
2. The parent-injected atomic connection OPENSQUILLA_META_CAPABILITY_PROVIDER, OPENSQUILLA_META_CAPABILITY_API_KEY, and OPENSQUILLA_META_CAPABILITY_BASE_URL. An optional OPENSQUILLA_META_CAPABILITY_PROXY applies only to requests to that matching provider API. These internal, volatile values are scoped to this bundled skill and are not written to argv, run inputs, or transcripts.
3. OPENSQUILLA_META_OPENROUTER_API_KEY, retained for older parent runtimes and bound only to OpenRouter's official API origin.
4. OPENROUTER_API_KEY environment variable for direct CLI use, also bound only to OpenRouter's official API origin.

The parent-injected generic key is accepted only when its provider and base URL are present as one tuple. --base-url may change the path for a parent or canonical credential but cannot change its scheme, hostname, or effective port. To intentionally use a different API origin from the direct CLI, pass both --api-key and --base-url. Authenticated requests reject URL userinfo, queries, fragments, malformed ports, and redirects before a key can be sent.

The child script never discovers or parses opensquilla.toml from its current working directory and never lets a workspace choose an arbitrary llm.api_key_env. Configure the active Gateway normally; the parent runtime performs that resolution before launching this bundled subprocess.

No Google Gemini key needed — OpenRouter routes the request to the Gemini image model on the user's behalf.

When a parent-resolved profile-pool credential receives an authentication, credit, or rate-limit failure, OpenSquilla parks that key for the next explicitly authorized run. It never repeats the current paid generation automatically.

Output

Prints the absolute path of the saved PNG, then an IMAGE_GENERATION_RECEIPT: {...} line on stdout. A matching sanitized receipt is saved as <filename>.receipt.json; it records provider, model, provider request id when available, and whether the file is a real model result or a local placeholder. It never contains the API key or prompt. Provider image MIME, decoded format, dimensions, and payload integrity are verified and supported formats are normalized to PNG before a generated receipt is written. Consumers must not report a placeholder receipt as a real image-generation success. A provider result without a request id is marked generated_unverified and likewise cannot satisfy verified E2E provenance. Non-zero exit on any hard error; stderr carries the diagnostic.

Image generation is a paid, non-idempotent operation. The script never submits a second paid request automatically after any provider response, timeout, lost connection, malformed response, policy refusal, or other ambiguous outcome. The retry/fallback inputs remain accepted for compatibility, but can advance only from an explicitly classified pre-submit failure.

Cost / latency

• 1K ~ 4-8s
• 2K ~ 8-15s
• 4K ~ 20-40s
• Use 1K for draft, 4K only when the prompt is locked.

Common failures

• no OpenRouter API key found → for direct CLI use, set OPENROUTER_API_KEY or pass --api-key; for a meta-skill run, configure the Gateway's OpenRouter provider connection and retry from that Gateway.
• OpenRouter returned no image → the model rejected the prompt (content moderation or unsupported request). Rewrite prompt; check IP-safety rules in ai-video-script.
• OpenRouter HTTP 402 / 429 → out of credits / rate-limited.