acestep-thumbnail

# 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: ```bash 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: 1. Tell the user the Gemini API key is not configured and image generation cannot proceed without it. 2. 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. 3. Once the user provides the key, configure it using: ```bash cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --set api_key <KEY> ``` 4. 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 ```bash # 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 ```bash ./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` ```bash # 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: ```bash # 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: 1. **acestep-songwriting** — Write lyrics and plan structure 2. **acestep** — Generate music from lyrics 3. **acestep-lyrics-transcription** — Transcribe audio to timestamped LRC 4. **acestep-thumbnail** — Generate cover art / MV background 5. **acestep-simplemv** — Render final music video with cover + audio + lyrics