用途
acestep-thumbnail 是一个缩略图生成技能，使用 Google Gemini 的图像生成 API 来生成歌曲封面或缩略图图片。生成的图片可以直接作为 MV 背景，配合 acestep-simplemv 技能使用。
主要能力
- 根据文字提示词生成艺术图片，适合用作音乐视频背景或专辑封面。
- 支持指定宽高比：16:9、1:1 或 9:16，默认 16:9。
- 支持自定义输出路径，默认保存到 acestep_output/<timestamp>_thumbnail.png。
- 提供配置管理功能，可设置 API 密钥、模型和默认宽高比。
使用方式
前置条件
- 需要 curl、jq、base64（或 python3）。
- 需要一个 Gemini API 密钥，可从 https://aistudio.google.com/apikey 获取（需要 Google 账号）。
API 密钥配置
在生成之前，必须先检查用户是否已配置 API 密钥。运行以下命令检查：
cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --check-key
该命令只报告密钥是否已设置或为空，不会打印实际密钥值。切勿读取或显示用户的 API 密钥内容。不要对密钥字段使用 config --get 或直接读取 config.json。config --list 命令是安全的，它会自动将 API 密钥掩码为 ***。
如果命令报告密钥为空，必须停止并引导用户先配置密钥，不要在无有效密钥的情况下尝试生成。
使用 AskUserQuestion 要求用户提供 API 密钥，并告知用户 Gemini API 密钥未配置，没有密钥无法进行图像生成。提供获取密钥的指引：Google AI Studio：在 https://aistudio.google.com/apikey 获取 API 密钥，需要 Google 账号。
用户提供密钥后，使用以下命令配置：
cd "{project_root}/{.claude or .codex}/skills/acestep-thumbnail/" && bash ./scripts/acestep-thumbnail.sh config --set api_key <KEY>
配置完成后，重新运行 config --check-key 验证密钥已设置，然后再继续。如果 API 密钥已配置，则直接进行生成，无需询问。
快速开始
1. 切换到本技能目录
cd {project_root}/{.claude or .codex}/skills/acestep-thumbnail/
2. 配置 API 密钥
./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 密钥
./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 密钥已掩码）
./scripts/acestep-thumbnail.sh config --list
配置项：
- api_key：默认 ""，Gemini API 密钥。
- 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 — 渲染最终音乐视频（封面 + 音频 + 歌词）
适用场景
- 为歌曲生成专辑封面或缩略图。
- 为音乐视频生成背景图片。
- 作为 ACE-Step 歌曲制作流水线的一部分，与作词、音乐生成、歌词转录和 MV 渲染技能配合使用。
限制
- 需要有效的 Gemini API 密钥，否则无法生成。
- 图像生成模型通常难以处理文字，提示词中应避免要求文字。
- 用于 MV 背景时，过于复杂的构图可能不适合，因为会叠加可视化效果。
- 关于收费、价格、平台支持范围等信息，资料中暂未提供。