SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场acestep

acestep

设计与创作

查看项目

更新于 10-15 11:22

技能介绍

ACE-Step 音乐生成技能基于 ACE-Step V1.5 API，用于音乐生成、歌曲编辑与混音。使用时必须通过 scripts/acestep.sh 脚本调用，不要直接调用 API 端点。

一、用途 该技能面向需要生成音乐、编写歌词、续写音频或对音频局部重绘的场景。支持文字生成音乐（text-to-music）、歌词生成、音频续写（audio continuation）与音频重绘（audio repainting）。

二、主要能力

  1. Caption 模式：推荐方式，先写歌词再生成，使用 -c 指定风格描述、-l 传入完整歌词。
  2. 纯器乐生成：直接传入风格描述即可。
  3. 快速探索：Simple/Random 模式（-d 或 random），适合快速获取灵感或器乐探索。
  4. 翻唱（cover）：基于源音频重新生成，保留旋律结构，可指定新风格与歌词。
  5. 音频重绘（repaint）：修改音频的特定区域，可指定重绘起止时间。
  6. 音乐属性控制：可设置时长、BPM、调式（key-scale）、拍号（time-signature）、批量生成数量等。
  7. 其他命令：status（查询任务）、health（健康检查）、models（模型列表）。

三、使用方式

  1. 进入技能目录：cd {project_root}/{.claude 或 .codex}/skills/acestep/
  2. 检查 API 服务健康：./scripts/acestep.sh health
  3. 带歌词生成（推荐）：./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] Your lyrics here..." --duration 120 --language zh
  4. 输出保存到：{project_root}/acestep_output/

脚本命令示例：

  • Caption 模式：./scripts/acestep.sh generate -c "Electronic pop, energetic synths" -l "[Verse] ..." --duration 120 --bpm 128
  • 纯器乐：./scripts/acestep.sh generate "Jazz with saxophone"
  • 快速探索：./scripts/acestep.sh generate -d "A cheerful song about spring" 或 ./scripts/acestep.sh random
  • 翻唱：./scripts/acestep.sh cover song.mp3 -c "Rock cover style" -l "[Verse] Lyrics..." --duration 120 --bpm 128
  • 重绘：./scripts/acestep.sh generate --src-audio song.mp3 --task-type repaint -c "Pop" --repaint-start 30 --repaint-end 60
  • 属性设置：./scripts/acestep.sh generate "Rock" --duration 60 --bpm 120 --key-scale "C major" --time-sig "4/4"
  • 批量：./scripts/acestep.sh generate "Rock" --duration 60 --batch 2
  • 更快生成：./scripts/acestep.sh generate "EDM" --no-thinking

歌词输入要求：通过 -l 参数提供歌词时，必须传入全部歌词内容，不得截断或省略，否则会导致歌曲不完整或不连贯。

四、输出文件 生成后脚本自动将结果保存到项目根目录的 acestep_output 文件夹（与 .claude 同级），包含 <job_id>.json（完整任务结果）与 <job_id>_1.mp3 等音频文件（batch_size 大于 1 时会有多个）。

JSON 结果中，prompt 与 lyrics 为实际用于合成的（可能经 LM 增强）内容，metas.prompt 与 metas.lyrics 为原始输入；metas 还包含 bpm、keyscale、duration；另有 generation_info、seed_value、lm_model、dit_model 等字段。要获取实际合成歌词，应读取顶层 lyrics 字段而非 metas.lyrics。

五、配置 配置优先级：命令行参数 > config.json 默认值。用户指定参数临时覆盖默认值但不修改 config.json；只有 config --set 命令会永久修改 config.json。

默认配置文件 scripts/config.json 包含：api_url（默认 http://127.0.0.1:8001）、api_key（默认空）、api_mode（默认 completion）、generation 下的 thinking（默认 true）、use_format（默认 false）、use_cot_caption（默认 true）、use_cot_language（默认 false）、batch_size（默认 1）、audio_format（默认 mp3）、vocal_language（默认 en）。

API 模式：completion（默认，OpenRouter 兼容，同步请求，音频以 base64 返回）与 native（异步轮询，支持全部参数）。切换：./scripts/acestep.sh config --set api_mode completion 或 native。completion 模式无需轮询，单次请求直接返回结果；inference_steps、infer_method、shift 不可配置；--no-wait 与 status 命令不适用；需要 model 字段，未指定时从 /v1/models 自动检测。

六、前置条件 该技能需要 ACE-Step API 服务处于运行状态。脚本依赖 curl 与 jq；若 jq 未安装，脚本会尝试自动安装，失败时可按平台手动安装（Windows：choco install jq 或从 https://jqlang.github.io/jq/download/ 下载；macOS：brew install jq；Linux：sudo apt-get install jq 或 sudo dnf install jq）。

首次使用前必须检查 API 密钥与地址状态： cd "{project_root}/{.claude 或 .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --check-key cd "{project_root}/{.claude 或 .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --get api_url

情况一：使用官方云 API（https://api.acemusic.ai）但未配置密钥时，必须停止并引导用户配置密钥。API 密钥目前可通过 acemusic.ai 免费获取。配置命令：bash ./scripts/acestep.sh config --set api_key <KEY>。 情况二：已配置密钥，验证端点后继续生成。 情况三：使用本地/自定义 API 且无需密钥，本地服务通常不需要密钥，验证健康后继续。

若健康检查失败：询问用户是否已安装 ACE-Step；已安装但未运行，使用 acestep-docs 技能帮助启动；未安装则使用 acestep-docs 技能引导安装。

服务配置：官方云 API 可设置 api_url 为 https://api.acemusic.ai、api_key 与 api_mode completion；本地服务默认无需配置，连接 http://127.0.0.1:8001；自定义远程服务可更新 scripts/config.json 或使用 config --set。

API 密钥处理：检查密钥是否配置时使用 config --check-key，它只报告已配置或为空，不打印实际密钥。切勿使用 config --get api_key 或直接读取 config.json，以免暴露密钥。config --list 命令是安全的，会自动将密钥掩码为 ***。

七、MV 制作相关 若用户需要简单音乐视频，可使用 acestep-simplemv 技能渲染带波形可视化与同步歌词的 MV。制作简单 MV 需要额外安装三个技能：acestep-songwriting（写歌词与规划歌曲结构）、acestep-lyrics-transcription（将音频转录为带时间戳的歌词 LRC）、acestep-simplemv（渲染最终 MV）；acestep-thumbnail（可选，通过 Gemini API 生成封面/MV 背景图）。

MV 背景图：用户请求 MV 制作时，需询问是否要背景图，可选通过 Gemini 生成（需配置 Gemini API 密钥）、提供已有本地图片路径，或跳过使用默认动态渐变背景。

并行处理：歌词转录与缩略图生成相互独立，用户选择生成背景图时，可并行运行 acestep-lyrics-transcription 与 acestep-thumbnail 以节省时间，再用于最终 MV 渲染。

八、限制与注意事项

  • 必须通过脚本调用，不要直接调用 API 端点。
  • 云 API 使用时，大音频文件可能被 Cloudflare 拒绝，必要时先压缩（如 ffmpeg -i input.mp3 -b:a 64k -ar 24000 -ac 1 compressed.mp3）。
  • 启用 LM 增强（use_format=true）时，最终合成内容可能与输入不同，需查看 JSON 中的实际值。
  • 安装与启动应始终使用 acestep-docs 技能获取完整准确指引，不要提供简化启动命令。
  • 关于具体收费、价格、平台支持范围等，资料暂未提供。