Generate song cover/thumbnail images using Gemini API. Creates artistic images suitable for music video backgrounds. Use when users want to generate album art, song covers, thumbnails, or background images for MVs.
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.
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:
cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --set api_key <KEY>
config --check-key to verify the key is set before proceeding.If the API key is already configured, proceed directly to generation without asking.
# 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
./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)
When crafting prompts for song thumbnails:
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) |
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
The complete workflow with all ACE-Step skills: