cover-image-generation

Cover Image Generation

Generate a cover image for a podcast episode using the Gemini 3 Flash Image model, with an automatic fallback to the Gemini 3 Pro Image model ("Nano Banana Pro") if the primary model errors out.

This is a pipeline producer skill: the orchestrator (podcast-studio) invokes it after metadata, passing the run directory via --workspace, the metadata file via --metadata, and the GEMINI_API_KEY in the subprocess environment. The cover's title text comes from show_notes.json; any house style for the cover comes from the active show profile via the prompt the orchestrator supplies — this skill ships only generic, neutral fallback templates.

Requirements

• Python 3.10+ — supplied by the orchestrator's uv-managed venv (R70).
• google-genai (>= 2.0.1) — installed into that venv (not the system Python).

Interpreter (R70). generate_image.py imports google-genai, which lives in the orchestrator's uv-managed venv — run it through the venv interpreter the orchestrator resolved in Step 0 ("$PODCAST_PY" <script>), not bare python3. The python3 … in the examples is shorthand; substitute the resolved venv interpreter. See podcast-studio SKILL.md Step 0.

Inputs

• --metadata <path> — a show_notes.json produced by metadata-generation. The script reads show_title from it and builds the prompt from a built-in template set (preferred path).
• or --prompt "<text>" — a fully constructed prompt you supply yourself.
• --workspace <run-dir> — used to derive the default output path when --output is omitted.

One of --metadata or --prompt is required.

Invocation

Preferred — drive the cover from the episode metadata:

python3 "${CLAUDE_SKILL_DIR}/scripts/generate_image.py" \
  --workspace <run-dir> \
  --metadata <run-dir>/data/show_notes.json

Alternative — supply a manual prompt:

python3 "${CLAUDE_SKILL_DIR}/scripts/generate_image.py" \
  --workspace <run-dir> \
  --prompt "A prompt describing the cover"

Arguments

Argument	Default	Description
--workspace	workspace	Run directory; used for the default output path.
--metadata	—	Path to show_notes.json; the title drives a templated prompt.
--prompt	—	A manually constructed prompt (mutually sufficient with --metadata).
--output	{workspace}/images/cover.png	Output image path. The extension is rewritten to match the bytes actually returned.
--reference	—	Optional reference image uploaded for visual consistency.

Output

The image is saved to {workspace}/images/cover.<ext>, where <ext> matches the actual returned format (.png or .jpg, sniffed from the image magic bytes). Reference the file by its real name (e.g. glob cover.*); do not assume .png.

Model

• Primary: gemini-3.1-flash-image-preview
• Fallback: gemini-3-pro-image-preview
• Aspect ratio: 1:1 (the script appends a 1:1 instruction to every prompt)

Prompting rules

When --metadata is used, the script selects one of its built-in prompt templates at random and inserts the episode title. The title text is the only text that should appear on the cover.

When you construct a prompt yourself via --prompt:

• Include the episode title as the only on-cover text.
• Keep the visual direction consistent with the active show profile's house style (supplied to you by the orchestrator) — this skill does not encode any brand look of its own.

Forbidden themes

• No futuristic, cyberpunk, or neon themes.
• No text on the cover other than the episode title.