ambient-imagegen

name	ambient-imagegen
description	Generate raster images through hosted APIs such as OpenAI, Google Nano Banana Pro, fal/FLUX, Replicate, Stability AI, and Ideogram.

Ambient Hosted Image Generation

Use this package when the user asks for a bitmap image from a hosted image API and accepts cloud execution, provider policy, cost, and secret setup. Prefer local ComfyUI only when the user wants local model control, offline/privacy-first generation, or an explicit workflow/model cache.

Discovery And Setup

• Find this package with ambient_cli_search using terms like hosted image generation, OpenAI image, Google Nano Banana, Nano Banana Pro, Flux, fal image, Replicate image, Stability image, or Ideogram.
• Call ambient_cli_describe before first use so the current provider aliases, env names, and artifact contract are visible.
• Run hosted_image_doctor --json to see provider aliases and which secret env names are configured. It does not call provider APIs and must not reveal secret values.
• Use Ambient-managed secret flows for keys. Do not ask the user to paste API keys into chat.

Providers

• openai: OpenAI GPT Image, default model gpt-image-2, env OPENAI_API_KEY.
• google: Google Nano Banana efficient image route, default model gemini-3.1-flash-image, env GEMINI_API_KEY or GOOGLE_API_KEY.
• google-nano-banana-pro: Google Nano Banana Pro, default model gemini-3-pro-image, env GEMINI_API_KEY or GOOGLE_API_KEY.
• fal: fal Model APIs, default model fal-ai/flux/dev, env FAL_KEY.
• flux: convenience alias for the fal FLUX route, default model fal-ai/flux/dev, env FAL_KEY.
• replicate: Replicate predictions for hosted image models, default model black-forest-labs/flux-schnell, env REPLICATE_API_TOKEN.
• stability: Stability AI Stable Image, default model stable-image-ultra, env STABILITY_API_KEY.
• ideogram: Ideogram 4.0 image generation, env IDEOGRAM_API_KEY.

Commands

• hosted_image_doctor --json: reports supported providers, aliases, required env names, default models, and key presence.
• hosted_image_generate --provider <provider> --prompt <text> --output <path> --json: generates one image and writes a metadata JSON next to the image.
• hosted_image_generate --provider <provider> --prompt-file <path> --dry-run --json: returns the planned provider/model/host/env contract without making a network request.

Useful flags:

• --model <id> overrides the provider default.
• --size <WxH> requests dimensions when the provider supports it.
• --aspect-ratio <ratio> requests provider-native aspect ratio when supported.
• --format png|jpeg|webp requests output format when supported.
• --negative-prompt <text> is passed only to providers that support it.

Artifact Contract

Every successful generation writes:

• The generated image file in the workspace.
• A sibling metadata JSON file with provider id, model id, byte size, MIME type, dimensions when detectable, SHA-256, latency, and secret env names only.
• Bounded stdout JSON for the transcript.

The command downloads temporary remote URLs into workspace files. Do not leave only provider-hosted URLs as the durable result.

Safety And Boundaries

• Provider prompts and source images leave the machine. State this when the user has not already acknowledged cloud use.
• Never print, log, or store secret values. Report only env names and configured/not-configured state.
• Surface provider policy, quota, auth, and malformed-request errors as errors. Do not rewrite prompts to bypass policy.
• Keep generated images as raster artifacts. Use document, SVG, or authored-motion tools when the user asks for editable documents, vector artwork, or deterministic video.