fearovex/ai-media-generation

ai-media-generation

Stack-agnostic governance for generating images, video, and audio with AI providers. Security of API keys and explicit cost control come first — generation is never automatic.

Triggers: generate image/illustration/asset with AI, "generate an image", "generá una imagen", nano banana, gemini image, generate video, configure image API, AI media generation, FLUX, image model setup

---

Patterns

Pattern 1: Key lives in a machine environment variable, never in the repo

The provider SDK reads the key from a process environment variable. The user stores it as a machine-level (OS) environment variable, NOT in any file inside the repository. This is the safest default: there is no .env to accidentally commit, and the same key works for every project on that machine.

• Variable name: GEMINI_API_KEY. This is the official name @google/genai reads from process.env.GEMINI_API_KEY by default — do NOT invent another name.
• Windows: System Properties → Environment Variables → User variables → New → name GEMINI_API_KEY, value <the key>. Restart the terminal so the value is loaded.
• macOS / Linux: add export GEMINI_API_KEY="<the key>" to ~/.zshrc or ~/.bashrc, then source the file or open a new shell.
• New machine onboarding: to replicate on another computer, set the same GEMINI_API_KEY env var with the same key. That single step is the entire setup — no repo file changes.

Pattern 2: Obtaining the key (Google AI Studio)

1. Go to Google AI Studio → Get API key.
2. Create the key under a project with billing enabled: choose "Continue with pay per request" (billing Tier 1+). The free tier does not cover paid image models.
3. Copy the key ONCE into the env var (Pattern 1). Never paste it into source, chat, or a tracked file.

Pattern 3: Prefer the official provider SDK over a third-party MCP

Use the provider's official SDK (e.g. @google/genai) over a community MCP server. A community MCP runs third-party code with your key — only acceptable if it is open-source, audited, and the user explicitly approves it for this task. When unsure, default to the official SDK.

Pattern 4: Cost-aware generation flow

Generate small and curated, never in large batches. The loop:

1. Declare before generating: how many images, resolution, and estimated cost.
2. Generate one (or very few).
3. Show the result to the user.
4. Iterate by editing the SAME image (image-to-image edit) before regenerating from scratch — editing is cheaper and faster than a fresh generation.
5. Save assets to a project folder (e.g. assets/generated/), never to a temp directory.
6. Track the running session spend and report it.

Pattern 5: Estimated cost reference (Gemini image)

| Resolution | Approx. cost per image | |------------|------------------------| | 1K–2K | ~$0.134 | | 4K | ~$0.24 |

Always restate the current provider's pricing before a generation — these figures are a reference point, not a guarantee, and providers change pricing.

---

Examples

Example: minimal @google/genai script reading the env var

// generate.mjs — run with: node generate.mjs
// Requires the GEMINI_API_KEY machine env var to be set (see Pattern 1).
import { GoogleGenAI } from "@google/genai";
import { writeFile } from "node:fs/promises";

// The SDK reads process.env.GEMINI_API_KEY automatically — do NOT hardcode the key.
const ai = new GoogleGenAI({});

if (!process.env.GEMINI_API_KEY) {
  console.error("GEMINI_API_KEY is not set. Add it as a machine env var (see Pattern 1).");
  process.exit(1);
}

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-image", // Nano Banana Pro image model
  contents: "A minimalist mountain logo, flat vector style, single accent color",
});

// Persist the returned image to a PROJECT folder, not temp.
for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    const buffer = Buffer.from(part.inlineData.data, "base64");
    await writeFile("assets/generated/logo-01.png", buffer);
    console.log("Saved assets/generated/logo-01.png");
  }
}

Example: .gitignore guard before writing any local key file

If the user insists on a local file instead of a machine env var, verify .gitignore ignores it before writing the key. Never create the file otherwise.

# Local secrets — never committed
.env
.env.local
*.local

Example: pre-generation declaration to the user

About to generate:
  - Count: 2 images
  - Resolution: 2K
  - Model: gemini-2.5-flash-image
  - Estimated cost: 2 × ~$0.134 = ~$0.27
  - Session spend so far: $0.40 → after this: ~$0.67
Approve? (waiting for explicit OK before generating)

---

Rules

• API keys are NEVER committed. They live in environment variables or git-ignored .local files. Verify .gitignore before writing any key to disk. Never paste a key into source code or into chat.
• GEMINI_API_KEY is the canonical variable name for @google/genai. Do not rename it.
• Prefer the official provider SDK over a third-party MCP. A community MCP runs third-party code with your key — use only if open-source, audited, and explicitly approved by the user.
• Never generate without explicit user approval for THAT specific generation. Before generating, declare count, resolution, and estimated cost. Generate small and curated, not in large batches. Track and report the session spend.
• Edit before regenerate. Iterate on the same image (image-to-image edit) before generating from scratch — it saves cost. Save assets to a project folder, never to temp.
• Respect rights and authorship. Never generate content the user has no rights to, and never imitate the style of an identifiable living artist unless the user explicitly requests it.