Spaces:

DengLi1208
/

ACE-Step-1.5

Build error

App Files Files Community

ACE-Step-1.5 / docs /ja /API.md

DengLi1208

Upload folder using huggingface_hub

6c38ec5 verified 1 day ago

preview code

raw

history blame contribute delete

21.5 kB

ACE-Step API クライアントドキュメント

Language / 语言 / 言語: English | 中文 | 日本語

本サービスはHTTPベースの非同期音楽生成APIを提供します。

基本的なワークフロー：

POST /v1/music/generate を呼び出してタスクを送信し、job_id を取得します。
GET /v1/jobs/{job_id} を呼び出してタスクステータスをポーリングし、status が succeeded または failed になるまで待ちます。
結果で返された GET /v1/audio?path=... URL から音声ファイルをダウンロードします。

1. タスクステータスの説明

タスクステータス（status）には以下の種類があります：

queued：タスクがキューに入り、実行待ちです。この時点で queue_position と eta_seconds を確認できます。
running：生成が進行中です。
succeeded：生成が成功し、結果は result フィールドにあります。
failed：生成が失敗し、エラー情報は error フィールドにあります。

2. 生成タスクの作成

2.1 API 定義

URL：/v1/music/generate
メソッド：POST
Content-Type：application/json、multipart/form-data、または application/x-www-form-urlencoded

2.2 リクエストパラメータ

パラメータ命名規則

APIはほとんどのパラメータで snake_case と camelCase の両方の命名をサポートしています。例：

audio_duration / duration / audioDuration
key_scale / keyscale / keyScale
time_signature / timesignature / timeSignature
sample_query / sampleQuery / description / desc
use_format / useFormat / format

また、メタデータはネストされたオブジェクト（metas、metadata、または user_metadata）で渡すことができます。

方法 A：JSONリクエスト（application/json）

テキストパラメータのみを渡す場合、またはサーバー上に既に存在する音声ファイルパスを参照する場合に適しています。

基本パラメータ：

パラメータ名	型	デフォルト	説明
`caption`	string	`""`	音楽の説明プロンプト
`lyrics`	string	`""`	歌詞の内容
`thinking`	bool	`false`	5Hz LMを使用してオーディオコードを生成するかどうか（lm-dit動作）
`vocal_language`	string	`"en"`	歌詞の言語（en、zh、jaなど）
`audio_format`	string	`"mp3"`	出力形式（mp3、wav、flac）

サンプル/説明モードパラメータ：

パラメータ名	型	デフォルト	説明
`sample_mode`	bool	`false`	ランダムサンプル生成モードを有効にする（LM経由でcaption/lyrics/metasを自動生成）
`sample_query`	string	`""`	サンプル生成のための自然言語の説明（例：「静かな夜のための柔らかいベンガルのラブソング」）。別名：`description`、`desc`
`use_format`	bool	`false`	LMを使用して提供されたcaptionとlyricsを強化/フォーマットする。別名：`format`

マルチモデルサポート：

パラメータ名	型	デフォルト	説明
`model`	string	null	使用するDiTモデルを選択（例：`"acestep-v15-turbo"`、`"acestep-v15-turbo-shift3"`）。`/v1/models` で利用可能なモデルを一覧表示。指定しない場合はデフォルトモデルを使用。

thinkingのセマンティクス（重要）：

thinking=false：
- サーバーは5Hz LMを使用して audio_code_string を生成しません。
- DiTは text2music モードで実行され、提供された audio_code_string を無視します。
thinking=true：
- サーバーは5Hz LMを使用して audio_code_string を生成します（lm-dit動作）。
- DiTはLM生成のコードで実行され、音楽品質が向上します。

メタデータの自動補完（条件付き）：

use_cot_caption=true または use_cot_language=true またはメタデータフィールドが欠落している場合、サーバーは caption/lyrics に基づいて5Hz LMを呼び出し、欠落しているフィールドを補完することがあります：

bpm
key_scale
time_signature
audio_duration

ユーザー提供の値が常に優先されます。LMは空/欠落しているフィールドのみを補完します。

音楽属性パラメータ：

パラメータ名	型	デフォルト	説明
`bpm`	int	null	テンポ（BPM）を指定、範囲30-300
`key_scale`	string	`""`	キー/スケール（例：「C Major」、「Am」）。別名：`keyscale`、`keyScale`
`time_signature`	string	`""`	拍子記号（2、3、4、6はそれぞれ2/4、3/4、4/4、6/8）。別名：`timesignature`、`timeSignature`
`audio_duration`	float	null	生成時間（秒）、範囲10-600。別名：`duration`、`target_duration`

オーディオコード（オプション）：

パラメータ名	型	デフォルト	説明
`audio_code_string`	string または string[]	`""`	`llm_dit` 用のオーディオセマンティックトークン（5Hz）。別名：`audioCodeString`

生成制御パラメータ：

パラメータ名	型	デフォルト	説明
`inference_steps`	int	`8`	推論ステップ数。Turboモデル：1-20（推奨8）。Baseモデル：1-200（推奨32-64）
`guidance_scale`	float	`7.0`	プロンプトガイダンス係数。baseモデルのみ有効
`use_random_seed`	bool	`true`	ランダムシードを使用するかどうか
`seed`	int	`-1`	シードを指定（use_random_seed=falseの場合）
`batch_size`	int	`2`	バッチ生成数（最大8）

高度なDiTパラメータ：

パラメータ名	型	デフォルト	説明
`shift`	float	`3.0`	タイムステップシフト係数（範囲1.0-5.0）。baseモデルのみ有効、turboモデルには無効
`infer_method`	string	`"ode"`	拡散推論方法：`"ode"`（Euler、より高速）または `"sde"`（確率的）
`timesteps`	string	null	カンマ区切りのカスタムタイムステップ（例：`"0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0"`）。`inference_steps` と `shift` をオーバーライド
`use_adg`	bool	`false`	適応デュアルガイダンスを使用（baseモデルのみ）
`cfg_interval_start`	float	`0.0`	CFG適用開始比率（0.0-1.0）
`cfg_interval_end`	float	`1.0`	CFG適用終了比率（0.0-1.0）

5Hz LMパラメータ（オプション、サーバー側）：

これらのパラメータは5Hz LMサンプリングを制御し、メタデータの自動補完と（thinking=true の場合）コード生成に使用されます。

パラメータ名	型	デフォルト	説明
`lm_model_path`	string	null	5Hz LMチェックポイントディレクトリ名（例：`acestep-5Hz-lm-0.6B`）
`lm_backend`	string	`"vllm"`	`vllm` または `pt`
`lm_temperature`	float	`0.85`	サンプリング温度
`lm_cfg_scale`	float	`2.5`	CFGスケール（>1でCFGを有効化）
`lm_negative_prompt`	string	`"NO USER INPUT"`	CFGで使用するネガティブプロンプト
`lm_top_k`	int	null	Top-k（0/nullで無効）
`lm_top_p`	float	`0.9`	Top-p（>=1は無効として扱われる）
`lm_repetition_penalty`	float	`1.0`	繰り返しペナルティ

LM CoT（思考の連鎖）パラメータ：

パラメータ名	型	デフォルト	説明
`use_cot_caption`	bool	`true`	LMにCoT推論で入力captionを書き換え/強化させる。別名：`cot_caption`、`cot-caption`
`use_cot_language`	bool	`true`	LMにCoTでボーカル言語を検出させる。別名：`cot_language`、`cot-language`
`constrained_decoding`	bool	`true`	構造化されたLM出力のためのFSMベースの制約付きデコーディングを有効にする。別名：`constrainedDecoding`、`constrained`
`constrained_decoding_debug`	bool	`false`	制約付きデコーディングのデバッグログを有効にする

編集/参照オーディオパラメータ（サーバー上の絶対パスが必要）：

パラメータ名	型	デフォルト	説明
`reference_audio_path`	string	null	参照オーディオパス（スタイル転送）
`src_audio_path`	string	null	ソースオーディオパス（リペイント/カバー）
`task_type`	string	`"text2music"`	タスクタイプ：`text2music`、`cover`、`repaint`、`lego`、`extract`、`complete`
`instruction`	string	auto	編集指示（提供されない場合はtask_typeに基づいて自動生成）
`repainting_start`	float	`0.0`	リペイント開始時間（秒）
`repainting_end`	float	null	リペイント終了時間（秒）、-1でオーディオの終端
`audio_cover_strength`	float	`1.0`	カバー強度（0.0-1.0）。スタイル転送には小さい値（0.2）を使用

方法 B：ファイルアップロード（multipart/form-data）

参照またはソースオーディオとしてローカルオーディオファイルをアップロードする必要がある場合に使用します。

上記のすべてのフィールドをフォームフィールドとしてサポートすることに加えて、以下のファイルフィールドもサポートしています：

reference_audio：（ファイル）参照オーディオファイルをアップロード
src_audio：（ファイル）ソースオーディオファイルをアップロード

注意：ファイルをアップロードすると、対応する _path パラメータは自動的に無視され、システムはアップロード後の一時ファイルパスを使用します。

2.3 レスポンス例

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "queue_position": 1
}

2.4 使用例（cURL）

基本的なJSONメソッド：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "アップビートなポップソング",
    "lyrics": "Hello world",
    "inference_steps": 8
  }'

thinking=trueの場合（LMがコードを生成 + 欠落メタを補完）：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "アップビートなポップソング",
    "lyrics": "Hello world",
    "thinking": true,
    "lm_temperature": 0.85,
    "lm_cfg_scale": 2.5
  }'

説明駆動型生成（sample_query）：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "sample_query": "静かな夜のための柔らかいベンガルのラブソング",
    "thinking": true
  }'

フォーマット強化（use_format=true）：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "ポップロック",
    "lyrics": "[Verse 1]\n街を歩いて...",
    "use_format": true,
    "thinking": true
  }'

特定のモデルを選択：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "エレクトロニックダンスミュージック",
    "model": "acestep-v15-turbo",
    "thinking": true
  }'

カスタムタイムステップを使用：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "ジャズピアノトリオ",
    "timesteps": "0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0",
    "thinking": true
  }'

thinking=falseの場合（DiTのみ、ただし欠落メタを補完）：

curl -X POST http://localhost:8001/v1/music/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "caption": "ゆっくりとした感情的なバラード",
    "lyrics": "...",
    "thinking": false,
    "bpm": 72
  }'

ファイルアップロードメソッド：

curl -X POST http://localhost:8001/v1/music/generate \
  -F "caption=この曲をリミックス" \
  -F "src_audio=@/path/to/local/song.mp3" \
  -F "task_type=repaint"

3. タスク結果の照会

3.1 API 定義

URL：/v1/jobs/{job_id}
メソッド：GET

3.2 レスポンスパラメータ

レスポンスには基本的なタスク情報、キューステータス、最終結果が含まれます。

主要フィールド：

status：現在のステータス
queue_position：現在のキュー位置（0は実行中または完了を意味）
eta_seconds：推定残り待ち時間（秒）
avg_job_seconds：平均ジョブ時間（ETA推定用）
result：成功時の結果オブジェクト
- audio_paths：生成されたオーディオファイルURLのリスト（/v1/audio エンドポイントと併用）
- first_audio_path：最初のオーディオパス（URL）
- second_audio_path：2番目のオーディオパス（URL、batch_size >= 2の場合）
- generation_info：生成パラメータの詳細
- status_message：簡潔な結果説明
- seed_value：使用されたシード値（カンマ区切り）
- metas：完全なメタデータ辞書
- bpm：検出/使用されたBPM
- duration：検出/使用された長さ
- keyscale：検出/使用されたキー
- timesignature：検出/使用された拍子
- genres：検出されたジャンル（利用可能な場合）
- lm_model：使用されたLMモデルの名前
- dit_model：使用されたDiTモデルの名前
error：失敗時のエラー情報

3.3 レスポンス例

キュー中：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "created_at": 1700000000.0,
  "queue_position": 5,
  "eta_seconds": 25.0,
  "avg_job_seconds": 5.0,
  "result": null,
  "error": null
}

実行成功：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "created_at": 1700000000.0,
  "started_at": 1700000001.0,
  "finished_at": 1700000010.0,
  "queue_position": 0,
  "result": {
    "first_audio_path": "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3",
    "second_audio_path": "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fdef456.mp3",
    "audio_paths": [
      "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3",
      "/v1/audio?path=%2Ftmp%2Fapi_audio%2Fdef456.mp3"
    ],
    "generation_info": "🎵 2つのオーディオを生成\n⏱️ 合計：8.5s\n🎲 シード：12345,67890",
    "status_message": "✅ 生成が正常に完了しました！",
    "seed_value": "12345,67890",
    "metas": {
      "bpm": 120,
      "duration": 30,
      "keyscale": "C Major",
      "timesignature": "4",
      "caption": "キャッチーなメロディのアップビートなポップソング"
    },
    "bpm": 120,
    "duration": 30,
    "keyscale": "C Major",
    "timesignature": "4",
    "genres": null,
    "lm_model": "acestep-5Hz-lm-0.6B",
    "dit_model": "acestep-v15-turbo"
  },
  "error": null
}

4. ランダムサンプル生成

4.1 API 定義

URL：/v1/music/random
メソッド：POST

このエンドポイントは5Hz LM経由でcaption、lyrics、メタデータを自動生成するサンプルモードジョブを作成します。

4.2 リクエストパラメータ

パラメータ名	型	デフォルト	説明
`thinking`	bool	`true`	LM経由でオーディオコードも生成するかどうか

4.3 レスポンス例

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "queue_position": 1
}

4.4 使用例

curl -X POST http://localhost:8001/v1/music/random \
  -H 'Content-Type: application/json' \
  -d '{"thinking": true}'

5. 利用可能なモデルの一覧

5.1 API 定義

URL：/v1/models
メソッド：GET

サーバーにロードされている利用可能なDiTモデルのリストを返します。

5.2 レスポンス例

{
  "models": [
    {
      "name": "acestep-v15-turbo",
      "is_default": true
    },
    {
      "name": "acestep-v15-turbo-shift3",
      "is_default": false
    }
  ],
  "default_model": "acestep-v15-turbo"
}

5.3 使用例

curl http://localhost:8001/v1/models

6. 音声ファイルのダウンロード

6.1 API 定義

URL：/v1/audio
メソッド：GET

パスで生成されたオーディオファイルをダウンロードします。

6.2 リクエストパラメータ

パラメータ名	型	説明
`path`	string	URLエンコードされたオーディオファイルパス

6.3 使用例

# ジョブ結果のURLを使用してダウンロード
curl "http://localhost:8001/v1/audio?path=%2Ftmp%2Fapi_audio%2Fabc123.mp3" -o output.mp3

7. ヘルスチェック

7.1 API 定義

URL：/health
メソッド：GET

サービスのヘルスステータスを返します。

7.2 レスポンス例

{
  "status": "ok",
  "service": "ACE-Step API",
  "version": "1.0"
}

8. 環境変数

APIサーバーは環境変数で設定できます：

変数	デフォルト	説明
`ACESTEP_API_HOST`	`127.0.0.1`	サーバーバインドホスト
`ACESTEP_API_PORT`	`8001`	サーバーバインドポート
`ACESTEP_CONFIG_PATH`	`acestep-v15-turbo`	プライマリDiTモデルパス
`ACESTEP_CONFIG_PATH2`	（空）	セカンダリDiTモデルパス（オプション）
`ACESTEP_CONFIG_PATH3`	（空）	3番目のDiTモデルパス（オプション）
`ACESTEP_DEVICE`	`auto`	モデルロードデバイス
`ACESTEP_USE_FLASH_ATTENTION`	`true`	flash attentionを有効化
`ACESTEP_OFFLOAD_TO_CPU`	`false`	アイドル時にモデルをCPUにオフロード
`ACESTEP_OFFLOAD_DIT_TO_CPU`	`false`	DiTを特にCPUにオフロード
`ACESTEP_LM_MODEL_PATH`	`acestep-5Hz-lm-0.6B`	デフォルト5Hz LMモデル
`ACESTEP_LM_BACKEND`	`vllm`	LMバックエンド（vllmまたはpt）
`ACESTEP_LM_DEVICE`	（ACESTEP_DEVICEと同じ）	LMデバイス
`ACESTEP_LM_OFFLOAD_TO_CPU`	`false`	LMをCPUにオフロード
`ACESTEP_QUEUE_MAXSIZE`	`200`	最大キューサイズ
`ACESTEP_QUEUE_WORKERS`	`1`	キューワーカー数
`ACESTEP_AVG_JOB_SECONDS`	`5.0`	初期平均ジョブ時間推定
`ACESTEP_TMPDIR`	`.cache/acestep/tmp`	一時ファイルディレクトリ

エラー処理

HTTPステータスコード：

200：成功
400：無効なリクエスト（不正なJSON、フィールドの欠落）
404：ジョブが見つからない
415：サポートされていないContent-Type
429：サーバービジー（キューが満杯）
500：内部サーバーエラー

エラーレスポンス形式：

{
  "detail": "問題を説明するエラーメッセージ"
}

ベストプラクティス

thinking=true を使用 してLM強化生成で最高品質の結果を得る。
sample_query/description を使用 して自然言語の説明から素早く生成。
use_format=true を使用 してcaption/lyricsがあるがLMに強化してもらいたい場合。
ジョブステータスのポーリング は適切な間隔（例：1-2秒ごと）で行い、サーバーの過負荷を避ける。
avg_job_seconds を確認 してレスポンスで待ち時間を推定。
マルチモデルサポートを使用 するには ACESTEP_CONFIG_PATH2 と ACESTEP_CONFIG_PATH3 環境変数を設定し、model パラメータで選択。
本番環境 では常に適切なContent-Typeヘッダーを設定して415エラーを回避。