Thumbnail Generation Skill

Generate song cover/thumbnail images using Google Gemini's image generation API. Output images can be used directly as MV backgrounds with the acestep-simplemv skill.

API Key Setup Guide

Before generating, you MUST check whether the user's API key is configured. Run the following command to check:

cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --check-key

This command only reports whether the API key is set or empty — it does NOT print the actual key value. NEVER read or display the user's API key content. Do not use config --get on key fields or read config.json directly. The config --list command is safe — it automatically masks API keys as *** in output.

If the command reports the key is empty, you MUST stop and guide the user to configure it before proceeding. Do NOT attempt generation without a valid key — it will fail.

Use AskUserQuestion to ask the user to provide their API key, with the following guidance:

Tell the user the Gemini API key is not configured and image generation cannot proceed without it.
Provide instructions on where to get a key:
- Google AI Studio: Get a API key at https://aistudio.google.com/apikey — requires a Google account.

Once the user provides the key, configure it using:

cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --set api_key <KEY>

After configuring, re-run config --check-key to verify the key is set before proceeding.

If the API key is already configured, proceed directly to generation without asking.

Quick Start

# 1. cd to this skill's directory
cd {project_root}/{.claude or .codex}/skills/acestep-thumbnail/

# 2. Configure API key
./scripts/acestep-thumbnail.sh config --set api_key <YOUR_GEMINI_KEY>

# 3. Generate thumbnail
./scripts/acestep-thumbnail.sh generate --prompt "Cherry blossoms at night with moonlight"

# 4. Output saved to: {project_root}/acestep_output/<timestamp>_thumbnail.png

Prerequisites

curl, jq, base64 (or python3)
A Gemini API key (at https://aistudio.google.com/apikey)

Script Usage

./scripts/acestep-thumbnail.sh generate [options]

Options:
  --prompt       Image description (required)
  --aspect-ratio 16:9, 1:1, or 9:16 (default: 16:9)
  --output       Output image path (default: acestep_output/<timestamp>_thumbnail.png)

Prompt Guidelines

When crafting prompts for song thumbnails:

Be descriptive and atmospheric: "Neon-lit rain-soaked Tokyo street at midnight" works better than "city at night"
Match the music mood: A jazz song might need "Warm smoky lounge with dim golden lighting", while EDM might need "Abstract geometric patterns with vibrant electric colors"
Avoid text requests: Image generation models often struggle with text. Add "No text or letters in the image" if needed
For MV backgrounds: The image will be overlaid with visualizations, so avoid overly busy compositions. Atmospheric, gradient-rich scenes work best

Configuration

Config file: scripts/config.json

# Set API key
./scripts/acestep-thumbnail.sh config --set api_key <YOUR_KEY>

# Change model
./scripts/acestep-thumbnail.sh config --set model gemini-3.1-flash-image-preview

# Change default aspect ratio
./scripts/acestep-thumbnail.sh config --set aspect_ratio 1:1

# View config (API key masked)
./scripts/acestep-thumbnail.sh config --list

Option	Default	Description
`api_key`	`""`	Gemini API key
`api_url`	`https://generativelanguage.googleapis.com/v1beta`	Gemini API base URL
`model`	`gemini-3.1-flash-image-preview`	Gemini model with image generation
`aspect_ratio`	`16:9`	Default aspect ratio (16:9 for MV, 1:1 for album art)

Integration with MV Rendering

Generated thumbnails can be directly used as MV backgrounds:

# 1. Generate thumbnail
cd {project_root}/{.claude or .codex}/skills/acestep-thumbnail/
./scripts/acestep-thumbnail.sh generate --prompt "Energetic pop concert stage with colorful lights" --output /tmp/cover.png

# 2. Use as MV background
cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song Name" --background /tmp/cover.png

Workflow: Full Song Pipeline

The complete workflow with all ACE-Step skills:

acestep-songwriting — Write lyrics and plan structure
acestep — Generate music from lyrics
acestep-lyrics-transcription — Transcribe audio to timestamped LRC
acestep-thumbnail — Generate cover art / MV background
acestep-simplemv — Render final music video with cover + audio + lyrics