suno-music

Ace Data Cloud の Suno

AceDataCloud の Suno API を通じて、AI で音楽を生成します。

skills.sh からインストールして接続する

この連携は Ace Data Cloud が保守しており、Suno の公式掲載ではありません。npx skills add acedatacloud/skills --skill suno-music --yes でこの Skill のみをインストールするか、skills.sh の公開ページをご利用ください。選択時はスラッグ suno-music を指定してください。

登録、Applications → General application、API キーへのアクセスと料金の確認、およびコーディングエージェントの環境変数の場所については、初回実行の図解ガイド（简体中文）をご覧ください。skills.sh からインストールした場合は、このガイドをご利用ください。ClawHub 固有の設定は OpenClaw にのみ適用されます。ここにリンクされている共通リファレンスは、個別のインストールには兄弟フォルダーの _shared/ が含まれないため、オンラインで公開されています。

ClawHub / OpenClaw のセットアップ

1. skills.sh からインストール済みの場合は、手順 2 に進んでください。コーディングエージェントの場合は、npx skills add acedatacloud/skills --skill suno-music --yes でインストールしてください（インストールと初回実行）。OpenClaw の場合は、clawhub install @acedatacloud/suno を実行し、ClawHub の公開元が @acedatacloud であることを確認してください。
2. AceDataCloud → Applications にサインインし、General application を開いて、Suno へのアクセス、残高、現在の料金を確認してください。API キーをコピーするか、Manage Keys → Create を選択して別のキーを作成してください。Bearer を除いたキーの値をコピーしてください。platform-... の管理トークンはサービス API キーではありません。
3. Allowed APIs の制限を有効にする場合は、/suno/audios と /suno/tasks を含めてください。以下の高度なワークフローでは、追加のルートを呼び出す場合があります。
4. コーディングエージェントまたは直接コマンドを使用する場合は、Skill を実行するプロセスの環境で ACEDATACLOUD_API_TOKEN="your_api_key_here" をエクスポートしてください。プロジェクトの .env の読み込み方法はエージェントによって異なります。OpenClaw の場合は、Gateway ホスト上の ~/.openclaw/.env に ACEDATACLOUD_API_TOKEN=your_api_key_here を設定し、Gateway を再起動して新しいセッションを開始してください。キーをプロンプトに記載したり、.env ファイルをコミットしたりしないでください。
5. 以下の クイックスタート を実行してください。タスク ID が返された場合は、完了するまで同じタスクを照会してください。進行状況を確認するためだけに、課金対象の生成をもう一度送信しないでください。

キーの設定、初回実行、トラブルシューティングの図解 · トークンの詳細

skills.sh からアクセスした場合は、初回実行用の Applications をご利用ください。音楽を生成する前に現在の料金を確認してください。

クイックスタート

curl -X POST https://api.acedata.cloud/suno/audios \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a happy pop song about coding", "model": "chirp-v6", "async": true}'

非同期: すべての生成は非同期です。非同期タスクのポーリングをご覧ください。POST /suno/tasks に {"id": "<task_id>"} を指定して、3～5 秒ごとにポーリングします。

利用可能なモデル

モデル	おすすめの用途
chirp-v6	現行の v6 モデル
chirp-v6-wild	v6 Wild モデル
chirp-v6-mini	v6 Mini モデル
chirp-v5-5	互換性のために維持されている旧モデル名
chirp-v5	高品質
chirp-v4-5-plus	強化版 v4.5
chirp-v4-5	品質と速度のバランスが良好
chirp-v4	高速で安定
chirp-v3-5	レガシー版、安定
chirp-v3-0	レガシー版

主なワークフロー

1. クイック生成（インスピレーションモード）

テキストの説明から楽曲を生成します。Suno が歌詞、スタイル、音楽を自動で作成します。

POST /suno/audios
{
  "prompt": "an upbeat electronic track about the future of AI",
  "model": "chirp-v6",
  "instrumental": false
}

2. カスタム生成（細かく指定）

独自の歌詞、タイトル、スタイルを指定して、生成内容を細かく制御します。

POST /suno/audios
{
  "custom": true,
  "lyric": "[Verse]\nCode is poetry in motion\n[Chorus]\nWe build the future tonight",
  "title": "Digital Dreams",
  "style": "Synthwave, Electronic, Dreamy",
  "model": "chirp-v6",
  "vocal_gender": "f"
}

3. 楽曲を延長する

特定のタイムスタンプから新しい歌詞を加えて、既存の楽曲を続けます。

POST /suno/audios
{
  "action": "extend",
  "audio_id": "existing-audio-id",
  "lyric": "[Bridge]\nNew section lyrics here",
  "continue_at": 120.0,
  "style": "Same style as original"
}

4. カバー／リミックス

既存の曲を異なるスタイルで新しいバージョンにします。

POST /suno/audios
{
  "action": "cover",
  "audio_id": "existing-audio-id",
  "style": "Jazz, Acoustic, Mellow"
}

5. 曲全体の作成ワークフロー

最良の結果を得るには、次の複数ステップのワークフローに従ってください。

1. 歌詞を生成 — トピックやプロンプトを指定して POST /suno/lyrics
2. スタイルを最適化 — スタイルの説明を調整するために POST /suno/style
3. 音楽を生成 — カスタムアクションと歌詞、スタイルを指定して POST /suno/audios
4. タスクをポーリング — id（バッチ処理の場合は ids）を指定して POST /suno/tasks を呼び出し、ステータスが完了になるまで確認します
5. 任意：延長 — 延長アクションを使ってセクションを追加します
6. 任意：連結 — 連結アクションを使って延長したセグメントを結合します
7. 任意：変換 — MP3（/suno/mp3）、WAV（/suno/wav）、MIDI（/suno/midi）、または MP4（/suno/mp4）を取得します

利用可能なアクション

アクション	説明
generate	プロンプトから生成します（デフォルト）
extend	タイムスタンプから既存の音声を続けます
upload_extend	外部音声をアップロードしてから延長します
upload_cover	外部音声をアップロードしてからカバーを作成します
concat	延長したセグメントを連結して1つのトラックにします
cover	既存の音声のスタイルをコピーします
artist_consistency	カスタムシンガーのスタイルで生成します
artist_consistency_vox	ボーカルに重点を置いたアーティストの一貫性
stems	トラックをステムに分離します
all_stems	利用可能なすべてのステムに分離します
replace_section	曲の特定の時間範囲を置き換えます
underpainting	アップロードした曲に伴奏を追加します
overpainting	アップロードした曲にボーカルを追加します
remaster	既存の音声をリマスターします
mashup	複数の音声 ID を組み合わせます
samples	アップロードした曲にサンプルを追加します
inspo	既存の音声に着想を得た曲を生成します

カスタム音楽モデル（ベータ）

カスタムモデルは、使用許可を得た6〜24個の音声ファイルから、再利用可能な音楽的特徴を学習します。作成には料金が発生し、処理に時間がかかります。送信する前に、ファイルと費用をユーザーに確認してください。

作成

POST /suno/custom-models
{
  "action": "create",
  "name": "My Album Sound",
  "audio_urls": [
    "https://cdn.example.com/track-01.mp3",
    "https://cdn.example.com/track-02.mp3",
    "https://cdn.example.com/track-03.mp3",
    "https://cdn.example.com/track-04.mp3",
    "https://cdn.example.com/track-05.mp3",
    "https://cdn.example.com/track-06.mp3"
  ]
}

安定した Idempotency-Key ヘッダーを送信し、ネットワーク障害後も同じキーを再利用してください。返された id を保存し、status が ready になるまで照会してください。

照会と一覧表示

POST /suno/custom-models
{"action": "retrieve", "id": "<custom-model-id>"}

POST /suno/custom-models
{"action": "retrieve_batch", "status": "ready", "limit": 20, "offset": 0}

生成

POST /suno/custom-models
{
  "action": "generate",
  "id": "<ready-custom-model-id>",
  "lyric": "[Verse]\nOriginal lyrics here",
  "style": "warm indie pop",
  "title": "New Song",
  "async": true
}

非同期リクエストの受け付けは、処理の成功を意味しません。返されたタスクをポーリングし、response.success を確認してください。カスタムモデルのリクエストで別のモデルにフォールバックすることはありません。モデルは現在の Suno アプリケーションに属し、status: "ready" である必要があります。

アーカイブ

POST /suno/custom-models
{"action": "delete", "id": "<custom-model-id>"}

delete はプラットフォームのリソースをアーカイブし、それ以降の使用を防止します。capacity_released: false は、モデルの容量が解放されたことを保証しないという意味です。

スタジオプロジェクト（ベータ）

バージョン管理されたマルチトラック編集には、/suno/audios ではなく POST /suno/projects を使用してください。ユーザーに使用権のある音声のみを処理してください。retrieve 以外の各アクションでは、Idempotency-Key ヘッダー（1〜128文字）を送信してください。リクエストの結果が不明な場合は、同じキーとペイロードを使って再試行してください。新しい操作には新しいキーが必要です。異なるペイロードで同じキーを再利用すると、409 が返されます。

作成、取得、保存

POST /suno/projects
{"action":"create","title":"My Studio Project"}

data.id を保存し、編集する前に、そのプロジェクトの id を指定して retrieve を実行してください。返された state が正となるため、トラックやクリップの構造を推測して作成せず、取得した内容を変更してください。空のプロジェクトは {"tracks":[],"timing":{"bps":2}} で始まります。

POST /suno/projects
{"action":"retrieve","id":"PROJECT_ID"}

POST /suno/projects
{"action":"save","id":"PROJECT_ID","state":{"tracks":[],"timing":{"bps":2}}}

save はパッチではなく、状態全体を置き換えます。retrieve.data.state に含まれる未知のフィールドを保持してください。結果に task_id が含まれていても、処理は同期的に完了します。新規でバージョン未設定のプロジェクトを初めて保存する場合に限り、version_id を省略できます。それ以降は、すべての変更、候補の生成、レンダリングで最新の version_id を指定してください。save、add_track、commit_candidate、または remove_track の後は、結果から新しいバージョンを保持してください。upload、render、generate_track、replace_section ではプロジェクトのバージョンは変わりません。HTTP 409 が発生した場合は、最新のプロジェクトを取得して変更を調整し、新しいキーで送信してください。古い編集内容をそのまま再送しないでください。

timing.bps は1秒あたりの拍数で、正の値である必要があり、デフォルトは2（120 BPM）です。クリップの startBeats、endBeats、readStartBeats はプロジェクトの拍数であり、オーディオ分析上の小節位置ではありません。配置を指定するリクエストの start_beats／end_beats は、プロジェクト内の0以上の拍数です。start_seconds／end_seconds は、ソース音声内の秒数を指定します。

音声をアップロードして追加する

POST /suno/projects
{"action":"upload","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_url":"https://cdn.example.com/reference.mp3","async":true}

アップロードタスクが成功するまでポーリングし、その後 response.data.candidate.audio_id を読み取り、add_track で使用してください。

POST /suno/projects
{"action":"add_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_id":"AUDIO_ID","name":"Backing Vocals"}

デフォルトの配置では再生速度が維持され、timing.bps を使って音声の長さが拍数に換算されます。

候補を生成、選択してコミットする

プロジェクトで使用できる公開モデル名は、chirp-v3-5、chirp-v4、chirp-v4-5、chirp-v4-5-plus、chirp-v5、chirp-v5-5、chirp-v6、chirp-v6-wild、chirp-v6-miniのみです。サポート対象外の名前を指定すると送信前に400が返されます。サポート対象の名前でも、選択した操作の成功が保証されるわけではありません。モデルを黙って切り替えないでください。

POST /suno/projects
{"action":"replace_section","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","start_seconds":35.12,"end_seconds":48.76,"model":"chirp-v6","replacement_lyrics":"New section lyrics","async":true}

replace_sectionは、選択を行わずに2つの候補を返します。終了位置は、実際のソース音声の長さを超えてはなりません。promptにはソースの歌詞やコンテキストを指定し、replacement_lyricsには新しい区間の歌詞を指定します。fixed=trueの場合、範囲は26秒未満でなければなりません。この機能のサポート状況はモデルによって異なり、このモードはドキュメントに記載されたBackendの実行では検証されていません。

新しいトラックを作成するには、まずソース音声をプロジェクトに追加し、次に状態全体を取得して、新しい一意のid、type:"audio"、clips:[]、takeLanes:[]、mute:false、solo:false、amplitude:1、instrument:{"type":"song"}、color:"#7251F7"を持つ空のオーディオトラックを追加します。生成する前に状態全体を保存し、新しいバージョンと保存先トラックIDを保持します。そのバージョンを成功するまでレンダリングし、response.data.audio_idをミックス参照として使用します。

POST /suno/projects
{"action":"generate_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","render_audio_id":"RENDER_AUDIO_ID","model":"chirp-v5","start_seconds":12,"end_seconds":20,"stem_control_tags":"add Piano","tags":"gentle piano, instrumental","instrumental":true,"vocal_gender":"unspecified","async":true}

generate_trackは常に2つの候補を送信します。batch_sizeは送信しないでください。stem_control_tagsは説明テキストであり、列挙値ではありません。instrumentalのデフォルトはtrueです。新しいトラックのテキストや歌詞にはpromptを使い、好みを指定するにはvocal_gender（f、m、unspecified、デフォルトはunspecified）を使いますが、結果が保証されるわけではありません。どちらの生成アクションもtagsとnegative_tagsを受け付けます（デフォルトは空文字列です）。ソースの秒数で指定した範囲は出力の長さを保証しません。各候補の実際の長さを確認してください。生成しても、候補はプロジェクトに追加されません。

成功するまでポーリングし、response.data.operation_idと、選択したresponse.data.candidates[].idを読み取ります（プロジェクトIDやコミットタスクIDで代用しないでください）。コミットする前に、ユーザーに候補を選んでもらってください。

POST /suno/projects
{"action":"commit_candidate","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","operation_id":"OPERATION_ID","candidate_id":"CANDIDATE_ID","track_id":"TRACK_ID","async":true}

• 候補は、生成に使用したバージョンに紐付けられています。新しいトラックの候補を生成する前に空の保存先トラックを保存してください。あとから作成すると、候補は古くなります。
• 置換候補は、一意のソースクリップを含む元のトラックに適用してください。テイク全体の置換では配置が維持され、区間の置換では前後のクリップが維持されます。これらの置換ではstart_beats／end_beatsを指定しないでください。長さを確実に合わせられない場合、リクエストは400を返し、プロジェクトは変更されません。
• 新しいトラックの候補には保存済みの空トラックを使用し、デフォルトではソースクリップの開始位置に配置するか、重複しない範囲を明示的に指定します。保存先トラックで重複があると400が返されます。
• トラックを削除するには、対象のトラックを確認してから、現在のバージョンを送信し、再取得して残りの状態を確認します。

POST /suno/projects
{"action":"remove_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","track_id":"TRACK_ID"}

レンダリングと復旧

POST /suno/projects
{"action":"render","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","title":"Final Mix","async":true}

start_beats / end_beats を省略すると、最も早く聞こえるクリップの開始位置から、最も遅く聞こえるクリップの終了位置までをレンダリングします。ミュートされたトラック／クリップは除外されます。ソロトラックがある場合は、それらのトラックのみが対象になります。空または聞こえる音がないプロジェクト、負の境界値、開始位置以下の終了位置を指定すると、400 が返されます。処理が正常に完了したら、返された render_id、audio_id、audio_url、再生時間を保存してください。

upload、add_track、generate_track、replace_section、commit_candidate、render は、async:false を指定しても常に非同期で実行されます。すべての非同期 Projects 操作について、3～5 秒ごとに {"action":"retrieve","id":"TASK_ID"} を指定して POST /suno/tasks をポーリングしてください。成功とみなされるには、finished_at があり、response.success=true である必要があります。response.success=false は失敗を示します。失敗時は、コールバック後も含め、response.error を確認してください。HTTP 200 または task_id は受け付けられたことを示すものであり、音声の処理完了を示すものではありません。この Projects のルールは、以下の /suno/audios のクリップ状態に関するルールとは異なります。

候補の URL が読み取れることやコミットが成功したことは、プロジェクトをレンダリングできる証明にはなりません。ドキュメントに記載された Backend の実行では、新しいトラックが生成されてコミットされましたが、そのトラックを使ったレンダリングは studio_audio_unavailable で失敗しました。また、代替候補も、再生時間がソースまたは選択した区間のどちらとも一致せず、コミットに失敗しました。確認のため、元のプロジェクトと候補は保持してください。配置を推測したり、有料の生成を自動的に繰り返したりしないでください。利用できないトラックを削除する前に、ユーザーに意図する編集を確認し、現在の状態を取得して、そのトラックのみを削除してください。その後、新しいバージョンの状態を再取得してレンダリングし、復旧を検証してください。Projects と候補は、それぞれのアプリケーションおよび実行環境に紐づいています。アプリケーション間で再利用できる、または自動的にフェイルオーバーされると想定しないでください。

同一のキーとペイロードを再送すると、失敗を含め、元の結果が再現され、再生成は行われません。明示的に再試行するには、まず元のタスクが失敗したことを確認してから、新しいキーを使用してください。元の処理が進行中、または状態が不確かな間は、決して再送しないでください。トラブルシューティングのために trace_id を保持してください。studio_state_invalid（400）、studio_model_unsupported（400）、studio_unavailable / studio_model_unavailable（503）、too_many_requests（429）、studio_audio_unavailable / content_rejected（403）は、モデルを変更したり編集を破棄したりせず、そのまま報告してください。

補助エンドポイント

エンドポイント	メソッド	目的
/suno/lyrics	POST	プロンプトから構造化された歌詞を生成します（model："default" または "remi-v1"）
/suno/style	POST	スタイルの説明を最適化／調整します
/suno/mashup-lyrics	POST	2 組の歌詞を組み合わせます
/suno/mp4	POST	曲の MP4 動画版を取得します
/suno/wav	POST	ロスレス WAV 形式に変換します
/suno/midi	POST	DAW で編集するための MIDI データを抽出します
/suno/vox	POST	ボーカルトラックを抽出します（ステム分離）
/suno/voices	POST	音声 URL から再利用可能な音声を作成します。audio_url が必須で、name と description は任意です
/suno/timing	POST	単語単位のタイミング／字幕を取得します
/suno/persona	POST	ボーカルスタイルを再利用可能なペルソナとして保存します。audio_id と name が必須です
/suno/persona	GET	再利用可能なペルソナを一覧表示します
/suno/persona	DELETE	再利用可能なペルソナを削除します
/suno/upload	POST	外部音声をアップロードして、拡張／カバーに使用します
/suno/tasks	POST	タスクの状態と結果を照会します
/suno/custom-models	POST	カスタム音楽モデルの作成、生成への使用、照会、一覧表示、アーカイブを行います
/suno/projects	POST	バージョン管理された Studio プロジェクトの作成、取得、編集、候補の生成、レンダリングを行います（ベータ版）

高度なパラメーター

パラメーター	型	説明
lyric_prompt	object	歌詞を自動生成するための構造化されたプロンプトペイロード（明示的な lyric を指定せずに custom: true を使用する場合に使用）
negative_tags	string	避けるスタイルまたはジャンルのタグ（例："heavy metal, distortion"）。custom: true の場合にのみ適用されます。このエンドポイントでは現在、固定の文字数制限は設けられていませんが、入力が長すぎると失敗することがあるため、簡潔にしてください
style_influence	number	スタイルの影響度（高度なカスタムモード、v5 以降のみ）
audio_weight	number	カバー時の音声参照の重み（高度な設定、v5 以降のみ）
duration	integer	トラックの目標再生時間（秒。通常は 10～360 秒）。chirp-v5-5 などの新しいモデルでは、custom: true を指定した generate で最も適切にサポートされます

歌詞の形式

角括弧内にセクションマーカーを使用します。

[Verse 1]
Your verse lyrics here

[Chorus]
Catchy chorus lyrics

[Bridge]
Bridge section

[Outro]
Ending lyrics

音声処理に失敗した場合の復旧

音声ファイルをダウンロードできても、その audio_id をカバー、延長、ステム分離などの後続処理で引き続き使用できるとは限りません。元の音声とタスクの証拠を保持し、ダウンロード URL から処理の利用可否を推測しないでください。

/suno/audios では、以下の公開 HTTP 500 エラーコードを一般的なエラーとして報告せず、そのまま保持してください。

コード	意味
suno_processing_unavailable	音楽処理を利用できません
suno_model_unavailable	選択したモデルはこの操作では利用できません
suno_processing_failed	音楽処理で音声が返されませんでした

また、/suno/audios から返された場合は、メッセージ the account may have been offline を伴う HTTP 500 api_error もそのまま保持してください。

これらのエラーが発生した場合、返された task_id と trace_id を保持し、それらの ID を添えてサポートに問い合わせてください。API キーは絶対に共有しないでください。送信が成功したか不明な場合は、別のリクエストを検討する前に既存のタスクを照会してください。有料操作を自動的に再試行したり、通知なくモデルを切り替えたりしないでください。結果が失敗したからといって、新たな課金対象リクエストが許可されたことにはなりません。

注意点

• /suno/audios の生成は非同期です。すぐにタスク ID を取得するには "callback_url" を設定し、その後 {"id":"<task_id>"} または {"ids":[...],"action":"retrieve_batch"} を使用して /suno/tasks をポーリングしてください
• /suno/audios に関する重要事項： クリップの state フィールドを確認してください。state: "complete" かつ success: true の場合のみ完了です。pending 中に API が中間的な audio_url（ストリーミングプレビュー）を返すことがあります。audio_url が空でないという理由だけでポーリングを停止しないでください
• 歌詞の最大長は約 3000 文字です。より長い曲には延長ワークフローを使用してください
• スタイルタグは列挙値ではなく、説明的なフレーズです（例：「Synthwave, Electronic, Dreamy」）
• vocal_gender（「f」／「m」）は v4.5 以降のモデルでのみサポートされています
• variation_category（「high」／「normal」／「subtle」）は v5 以降のモデルでのみサポートされています
• duration は指定された値のまま転送されます。サポート状況はモデルとアクションによって異なり、サポートされていない組み合わせは無視されるかエラーを返すことがあるため、まとめてリクエストする前に 1 件で確認してください。リクエストの duration は目標再生時間であり、返される各クリップの duration は実際の再生時間で、多少変動します
• concat アクションは延長した曲のセグメントを結合します。延長したトラックの audio_id が必要です
• persona には既存の audio_id と name が必要です。オプションの vox_audio_id、vocal_start、vocal_end、description でボーカル参照を調整できます
• 外部音声を延長／カバーに使用する前に、/suno/upload からアップロードしてください

MCP： pip install mcp-suno | ホスト型：https://suno.mcp.acedata.cloud/mcp | すべての MCP サーバーを見る