用途
acestep-thumbnail 用于生成歌曲封面或缩略图图像，借助 Google Gemini 的图像生成 API 完成。生成的图像可以直接作为 MV 背景，与 acestep-simplemv 技能配合使用。
主要能力
- 通过提示词（prompt）生成图像，适合制作专辑封面、歌曲缩略图与 MV 背景。
- 支持设定宽高比：16:9、1:1 或 9:16，默认 16:9（适合 MV），1:1 适合专辑封面。
- 支持自定义输出路径，默认输出到 {project_root}/acestep_output/<timestamp>_thumbnail.png。
- 提供配置管理命令，可设置 API Key、模型与默认宽高比，并查看配置（API Key 会以 *** 掩码显示）。
使用方式
前置条件
- curl、jq、base64（或 python3）
- 一个 Gemini API Key，可在 https://aistudio.google.com/apikey 获取（需要 Google 账号）
API Key 检查与配置
生成前必须先检查 API Key 是否已配置，运行：
cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --check-key
该命令只报告 Key 是否设置，不会打印实际值。不要读取或显示用户的 API Key 内容，不要使用 config --get 读取 key 字段，也不要直接读取 config.json。config --list 命令是安全的，会自动将 API Key 掩码为 ***。
如果命令报告 Key 为空，必须停止并引导用户先完成配置，不得在无有效 Key 的情况下尝试生成，否则会失败。此时通过 AskUserQuestion 请用户提供 API Key，并告知其 Gemini API Key 尚未配置、无法继续图像生成，同时给出获取地址：https://aistudio.google.com/apikey（需要 Google 账号）。用户提供 Key 后，使用以下命令配置：
cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --set api_key <KEY>
配置完成后，重新运行 config --check-key 验证 Key 已设置，再继续。如果 Key 已配置，可直接进入生成步骤，无需询问。
快速开始
1. 进入该技能目录
cd {project_root}/{.claude or .codex}/skills/acestep-thumbnail/
2. 配置 API Key
./scripts/acestep-thumbnail.sh config --set api_key <YOUR_GEMINI_KEY>
3. 生成缩略图
./scripts/acestep-thumbnail.sh generate --prompt "Cherry blossoms at night with moonlight"
4. 输出保存到：{project_root}/acestep_output/<timestamp>_thumbnail.png
脚本用法
./scripts/acestep-thumbnail.sh generate [options]
选项：
- --prompt：图像描述（必填）
- --aspect-ratio：16:9、1:1 或 9:16（默认 16:9）
- --output：输出图像路径（默认 acestep_output/<timestamp>_thumbnail.png）
提示词指南
为歌曲缩略图撰写提示词时：
- 描述尽量具体、有氛围感："Neon-lit rain-soaked Tokyo street at midnight" 比 "city at night" 效果更好。
- 匹配音乐情绪：爵士歌曲可能需要 "Warm smoky lounge with dim golden lighting"，而 EDM 可能需要 "Abstract geometric patterns with vibrant electric colors"。
- 避免要求生成文字：图像生成模型往往难以处理好文字，如有需要可加上 "No text or letters in the image"。
- 作为 MV 背景时：图像上会叠加可视化内容，因此避免过于繁杂的构图，氛围感强、渐变丰富的场景效果最佳。
配置
配置文件：scripts/config.json
设置 API Key
./scripts/acestep-thumbnail.sh config --set api_key <YOUR_KEY>
更换模型
./scripts/acestep-thumbnail.sh config --set model gemini-3.1-flash-image-preview
修改默认宽高比
./scripts/acestep-thumbnail.sh config --set aspect_ratio 1:1
查看配置（API Key 已掩码）
./scripts/acestep-thumbnail.sh config --list
配置项：
- api_key：默认 ""，Gemini API Key
- api_url：默认 https://generativelanguage.googleapis.com/v1beta，Gemini API 基础 URL
- model：默认 gemini-3.1-flash-image-preview，支持图像生成的 Gemini 模型
- aspect_ratio：默认 16:9，默认宽高比（16:9 用于 MV，1:1 用于专辑封面）
与 MV 渲染集成
生成的缩略图可直接用作 MV 背景：
1. 生成缩略图
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. 用作 MV 背景
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
工作流：完整歌曲流水线
结合全部 ACE-Step 技能的完整流程：
- acestep-songwriting — 编写歌词并规划结构
- acestep — 根据歌词生成音乐
- acestep-lyrics-transcription — 将音频转录为带时间戳的 LRC
- acestep-thumbnail — 生成封面图 / MV 背景
- acestep-simplemv — 合成最终音乐视频（封面 + 音频 + 歌词）
限制
- 必须配置有效的 Gemini API Key，否则无法生成，且密钥缺失时不应尝试生成。
- 图像生成模型在渲染文字方面表现不佳，建议在提示词中避免文字要求。
- 运行环境需具备 curl、jq、base64（或 python3）。
- 关于具体收费、价格与生成效果等更多信息暂未提供。