acestep

ACE-Step 音楽生成スキル

音楽生成には ACE-Step V1.5 API を使用します。必ず scripts/acestep.sh スクリプトを使用してください — API エンドポイントを直接呼び出してはいけません。

クイックスタート

# 1. cd to this skill's directory
cd {project_root}/{.claude or .codex}/skills/acestep/

# 2. Check API service health
./scripts/acestep.sh health

# 3. Generate with lyrics (recommended)
./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] Your lyrics here..." --duration 120 --language zh

# 4. Output saved to: {project_root}/acestep_output/

ワークフロー

ボーカルを含むリクエストの場合：

1. 歌詞の作成、キャプションの作成、曲の長さ／BPM／キーの選定には acestep-songwriting スキルを使用します
2. 作詞ガイドに基づいて、完全で構成の整った歌詞を自分で作成します
3. -c と -l パラメーターを指定して、Caption モードで生成します

手早くアイデアを得たい場合やインストゥルメンタルを試したい場合に限り、Simple／Random モード（-d または random）を使用してください。

ユーザーがシンプルなミュージックビデオを必要としている場合は、acestep-simplemv スキルを使用して、波形の表示と歌詞の同期を含む動画をレンダリングします。

MV 制作要件：シンプルな MV を制作するには、追加で次の 3 つのスキルをインストールする必要があります。

• acestep-songwriting — 歌詞の作成と曲の構成の計画用
• acestep-lyrics-transcription — 音声をタイムスタンプ付きの歌詞（LRC）に書き起こすため
• acestep-simplemv — 最終的なミュージックビデオのレンダリング用
• acestep-thumbnail（任意）— Gemini API を使用したカバーアート／MV 背景画像の生成用

MV の背景画像：ユーザーから MV 制作を依頼された場合は、動画の背景画像が必要かどうかを確認してください。

1. Gemini で生成する — acestep-thumbnail スキルを使用します（Gemini API キーの設定が必要です）
2. 既存の画像を提供する — ユーザーがローカル画像のパスを指定します
3. スキップする — デフォルトのアニメーション付きグラデーション背景を使用します（画像は不要です）

MV のレンダリングに進む前に、AskUserQuestion を使用してユーザーに選択してもらいます。

並列処理：歌詞の書き起こしとサムネイルの生成は独立したタスクです。ユーザーが背景画像の生成を選んだ場合は、時間を節約するために acestep-lyrics-transcription と acestep-thumbnail を並列で実行し（例：2 つの Agent 呼び出しを同時に行う）、その後、両方の出力を最終的な MV のレンダリングに使用します。

スクリプトコマンド

重要 — 歌詞の全文入力：-l パラメーターで歌詞を指定する場合は、歌詞の内容を省略せずにすべて渡す必要があります。

• ユーザーが歌詞を提供した場合は、その全文を渡します
• 自分で歌詞を作成した場合は、作成した歌詞の全文を渡します
• 歌詞を切り詰めたり、短縮したり、一部だけ渡したりしてはいけません
• 歌詞が欠けると、不完全または一貫性のない曲になります

音楽パラメーター：曲の長さ、BPM、キー・スケール、拍子については、acestep-songwriting スキルを使用してください。

# need to cd to this skill's directory first
cd {project_root}/{.claude or .codex}/skills/acestep/

# Caption mode - RECOMMENDED: Write lyrics first, then generate
./scripts/acestep.sh generate -c "Electronic pop, energetic synths" -l "[Verse] Your complete lyrics
[Chorus] Full chorus here..." --duration 120 --bpm 128

# Instrumental only
./scripts/acestep.sh generate "Jazz with saxophone"

# Quick exploration (Simple/Random mode)
./scripts/acestep.sh generate -d "A cheerful song about spring"
./scripts/acestep.sh random

# Cover / Repainting from source audio
./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

# Music attribute options
./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    # Faster

# Other commands
./scripts/acestep.sh status <job_id>
./scripts/acestep.sh health
./scripts/acestep.sh models

カバー／オーディオの再描画

cover コマンドは、ソース音声ファイルに基づいて音楽を生成します。音声は Base64 エンコードされ、API に送信されます。

# Cover: regenerate with new style/lyrics, preserving melody structure
./scripts/acestep.sh cover input.mp3 -c "Jazz cover" -l "[Verse] New lyrics..." --duration 120

# Repainting: modify a specific region of the audio
./scripts/acestep.sh generate --src-audio input.mp3 --task-type repaint -c "Pop ballad" --repaint-start 30 --repaint-end 90

# Cover options
#   --src-audio         Source audio file path
#   --task-type         cover (default with --src-audio), repaint, text2music
#   --cover-strength    0.0-1.0 (default: 1.0, higher = closer to source)
#   --repaint-start     Repainting start position (seconds)
#   --repaint-end       Repainting end position (seconds)
#   --key-scale         Musical key (e.g. "E minor")
#   --time-signature    Time signature (e.g. "4/4")

注：クラウド API の使用時、大きな音声ファイルは Cloudflare に拒否されることがあります。必要に応じて、アップロード前に音声を圧縮してください（例：ffmpeg を使用して ffmpeg -i input.mp3 -b:a 64k -ar 24000 -ac 1 compressed.mp3 を実行します）。

出力ファイル

生成後、スクリプトは結果をプロジェクトルート（.claude と同じ階層）の acestep_output フォルダーに自動保存します。

project_root/
├── .claude/
│   └── skills/acestep/...
├── acestep_output/          # Output directory
│   ├── <job_id>.json         # Complete task result (JSON)
│   ├── <job_id>_1.mp3        # First audio file
│   ├── <job_id>_2.mp3        # Second audio file (if batch_size > 1)
│   └── ...
└── ...

JSON 結果の構造

重要：LM による拡張が有効な場合（use_format=true）、最終的に合成される内容は入力と異なる可能性があります。実際の値を確認するには、JSON ファイルを確認してください。

フィールド	説明
prompt	合成に使用された実際のキャプション（LM によって拡張されている場合があります）
lyrics	合成に使用された実際の歌詞（LM によって拡張されている場合があります）
metas.prompt	入力された元のキャプション
metas.lyrics	入力された元の歌詞
metas.bpm	使用された BPM
metas.keyscale	使用されたキー・スケール
metas.duration	長さ（秒）
generation_info	詳細なタイミング情報とモデル情報
seed_value	使用されたシード値（再現用）
lm_model	LM モデル名
dit_model	DiT モデル名

実際に合成された歌詞を取得するには、JSON を解析し、metas.lyrics ではなくトップレベルの lyrics フィールドを読み取ってください。

設定

重要：設定には、以下の優先順位（高い順）が適用されます。

1. コマンドライン引数 > config.json のデフォルト値
2. ユーザーが指定したパラメーターはデフォルト値を一時的に上書きしますが、config.json は変更しません
3. 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_url	http://127.0.0.1:8001	API サーバーのアドレス
api_key	""	API 認証キー（任意）
api_mode	completion	API モード：completion（OpenRouter、デフォルト）または native（ポーリング）
generation.thinking	true	5Hz LM を有効にします（品質は向上しますが、時間がかかります）
generation.audio_format	mp3	出力形式（mp3/wav/flac）
generation.vocal_language	en	ボーカルの言語

前提条件 - ACE-Step API サービス

重要：このスキルを使用するには、ACE-Step API サーバーが起動している必要があります。

必須の依存関係

script/acestep.sh スクリプトには、curl と jq が必要です。

# Check dependencies
curl --version
jq --version

jq がインストールされていない場合、スクリプトは自動インストールを試みます。自動インストールに失敗した場合：

• Windows：choco install jq を実行するか、https://jqlang.github.io/jq/download/ からダウンロードしてください
• macOS：brew install jq を実行してください
• Linux：sudo apt-get install jq（Debian/Ubuntu）または sudo dnf install jq（Fedora）を実行してください

初回使用前

先に進む前に、API キーと URL の状態を必ず確認してください。 次を実行します：

cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --check-key
cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --get api_url

ケース 1：API キーなしで公式クラウド API（https://api.acemusic.ai）を使用する場合

api_url が https://api.acemusic.ai で、api_key が empty の場合、必ず処理を中断し、キーの設定をユーザーに案内してください：

1. ユーザーに次のように伝えます：「ACE-Step 公式クラウド API を使用していますが、API キーが設定されていません。このサービスを使用するには API キーが必要です。」
2. キーの取得方法を説明します。API キーは現在、acemusic.ai から無料で取得できます。
3. AskUserQuestion を使用して、API キーを入力するようユーザーに尋ねます。
4. キーが入力されたら、次のように設定します：

   cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --set api_key <KEY>
   

5. さらに、次のようにユーザーに伝えます：「ミュージックビデオ（MV）もレンダリングする場合は、歌詞の文字起こし API キー（OpenAI Whisper または ElevenLabs Scribe）も設定することをおすすめします。これにより、正確なタイムスタンプ付きで歌詞を自動的に文字起こしできます。キーは後から acestep-lyrics-transcription スキルで設定できます。」

ケース 2：API キーが設定されている場合

API エンドポイントを確認します：./scripts/acestep.sh health を実行し、音楽生成に進んでください。

ケース 3：キーなしでローカルまたはカスタム API を使用する場合

ローカルサービス（http://127.0.0.1:*）では、通常キーは不要です。./scripts/acestep.sh health で確認してから、処理を続けてください。

ヘルスチェックに失敗した場合：

• 「ACE-Step はインストールされていますか？」と尋ねます
• インストール済みだが起動していない場合：acestep-docs スキルを使用して、サービスの起動を支援します
• インストールされていない場合：acestep-docs スキルを使用して、インストール方法を案内します

サービスの設定

公式クラウド API： ACE-Step は https://api.acemusic.ai に公式 API エンドポイントを提供しています。使用するには：

./scripts/acestep.sh config --set api_url "https://api.acemusic.ai"
./scripts/acestep.sh config --set api_key "your-key"
./scripts/acestep.sh config --set api_mode completion

API キーは現在、acemusic.ai から無料で取得できます。

ローカルサービス（デフォルト）： 設定は不要です。http://127.0.0.1:8001 に接続します。

カスタムリモートサービス： scripts/config.json を更新するか、次を使用します：

./scripts/acestep.sh config --set api_url "http://remote-server:8001"
./scripts/acestep.sh config --set api_key "your-key"

API キーの取り扱い：API キーが設定されているか確認するときは、実際のキーを表示せず configured または empty のみを報告する config --check-key を使用してください。config --get api_key を実行したり、config.json を直接読み取ったりしないでください。これらの方法では、ユーザーの API キーが漏えいするおそれがあります。config --list コマンドは安全です。出力内の API キーは自動的に *** にマスクされます。

API モード

このスキルは 2 つの API モードをサポートしています。scripts/config.json の api_mode で切り替えます:

モード	エンドポイント	説明
completion(デフォルト)	/v1/chat/completions	OpenRouter 互換、同期リクエスト、音声は base64 で返却
native	/release_task + /query_result	非同期ポーリングモード、すべてのパラメータをサポート

モードの切り替え:

./scripts/acestep.sh config --set api_mode completion
./scripts/acestep.sh config --set api_mode native

completion モードの注意点:

• ポーリングは不要 — 単一のリクエストで結果が直接返ります
• 音声はレスポンス内に base64 でインラインエンコードされます(自動的にデコードして保存)
• inference_steps、infer_method、shift は設定できません(サーバーのデフォルト値)
• --no-wait および status コマンドは completion モードでは使用できません
• model フィールドが必要です — 指定しない場合は /v1/models から自動検出されます

セットアップのヘルプに acestep-docs スキルを使用する

IMPORTANT: インストールと起動については、必ず acestep-docs スキルを使用して、完全で正確なガイダンスを取得してください。

簡略化した起動コマンドを提示しないでください — 各ユーザーの環境は異なる可能性があります。常に acestep-docs を使用して適切にセットアップするよう案内してください。

---

API のデバッグについては、API リファレンスを参照してください。