楽曲メディアのダウンロードと試聴 API

2026-09-18 更新 · Suno-API チーム

インターフェースの説明

この一群のエンドポイントは「メディアアドレスの取得」と「実際のファイルダウンロード」を分けています。

そのまま再生・ダウンロードできるアドレスが欲しい場合（自分のプレイヤーに入れる、オブジェクトストレージへ転送するなど）：POST /api/music/download-url、またはレスポンスにすでに含まれる GET /api/music/download を使います。
ブラウザに直接ファイルを保存させたい場合：POST /api/music/download-file（単一ファイル）または POST /api/music/download-all（まとめて）を使います。
楽曲がまだ生成中で先に試聴したい場合：POST /api/music/generation-stream-url を使います。

課金: すべて無料。ダウンロードと試聴はプラットフォームがすでにホストしているメディアを読むだけで、Suno を呼び出さず、課金もありません。

推奨モデル: suno-v6。suno-v6、suno-v6-wild、suno-v6-mini が利用できます。

認証

パラメータ名	型	必須	説明
Authorization	string	はい	`Bearer YOUR_API_KEY`（`GET /api/music/download` はログイン状態も受け付けます）
Content-Type	string	はい	`application/json`

対応するメディア種別（`kind`）

kind	説明
`song`	音声（`mp3` はその別名で既定値。レスポンスでは常に `song` として返します）
`wav`	WAV ファイル。WAV 生成／取得 API で先に準備が必要です
`video`	動画（`mp4` は別名）
`midi`	分離したステムの MIDI。分離が完了したステムにのみ有効です。MIDI 取得 API を参照
`cover`	カバー画像（`image` は別名）
`lyrics`	歌詞テキスト（`.txt`）。`download-file` / `GET /api/music/download` でのみ取得でき、`download-url` は歌詞のアドレスを返しません
`timestamped_lyrics`	タイムライン歌詞ファイル（`.lrc`、別名 `lrc`）。現在は一部の楽曲のみ対応。`success:false` が返った場合はタイムライン歌詞 API でタイムラインを取得し、自分で生成してください

1) メディアアドレスの取得

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

パラメータ名	型	必須	説明
song_id	string	はい	自分の楽曲 ID
kind	string	いいえ	上の表を参照。既定は `song`
refresh	boolean	いいえ	`true` を渡すとリソースを強制的に再準備します（CDN 上のファイルが回収された後など）

url は再生や自分のストレージへの転送に使います。nav_url は Content-Disposition: attachment 付きで、ブラウザのアドレスバーにそのまま貼り付けてダウンロードするのに向いています（モバイルブラウザが blob ダウンロードに対応していない場合に使います）。

⚠️ アドレスの有効期限：7 日、お早めに転送してください

url / nav_url はプラットフォームのオブジェクトストレージを指し、既定で 7 日後に失効します（ファイルが期限で回収され、古いアドレスは 404 を返します）。この 7 日のうちにご自身のストレージへ転送してください。

失効後も楽曲を再生成する必要はありません：POST /api/music/download-url を再度呼ぶ（または refresh に true を渡す）だけで、その楽曲の新しい有効なアドレスを取得できます。この一群のエンドポイント自体は無料で、追加課金はありません。

2) 単一ファイルを直接ダウンロード

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

レスポンスボディはファイルストリーム（JSON ではありません）で、Content-Disposition にファイル名が入っています。歌詞とタイムライン歌詞はこのエンドポイントでのみ取得できます（download-url はメディアアドレスのみを返し、歌詞は返しません）。 .lrc ファイルは現在一部の楽曲のみ対応です。success:false が返った場合は、次の節のタイムライン歌詞 API の方法で .lrc を自分で生成してください。再試行は不要です。

タイムライン歌詞（.lrc）の取得方法

どの楽曲にも使える 2 ステップをおすすめします。

ステップ 1：単語ごとのタイムラインを取得（無料）

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

戻り値はそのまま配列です（data の外側ラッパーはありません）。各要素は {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99} の形です。 word にはすでに改行が含まれるので行ごとに分割できます。フィールドの意味や器楽セクションの除外などの注意点はタイムライン歌詞 API の「フィールド説明」「利用上の注意」をご覧ください。

ステップ 2：start_s から .lrc を自分で組み立てる（時刻形式 [mm:ss.cc]）

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc でもサーバー生成の .lrc を直接ダウンロードできますが、 現在は一部の楽曲のみ対応しています。success:false が返ったら上記の方法で自分で生成してください。再試行は不要で、課金にも影響しません。

3) まとめてダウンロード

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

song_id（単体）と song_ids（一括、最大 50 件）のどちらかを使います。レスポンスボディは ZIP ファイルストリームです。

4) 安定したダウンロードアドレス

GET /api/music/download?song_id=<id>&kind=<kind> は楽曲レスポンスに直接含まれるダウンロード入口です。 API キーとログイン状態の両方を受け付け、動作は download-file と同等で、クライアントやサードパーティのプレイヤーに固定で組み込むのに向いています。

5) 生成中の試聴

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

パラメータ名	型	必須	説明
song_id	string	いいえ	単一の楽曲 ID
song_ids	string[]	いいえ	一括、最大 24 件（自動分離バッチのステム数上限）

playable_until_completed が true の場合は生成中の一時試聴アドレスです。楽曲完成後は正式なアドレスに切り替えてください。 1 曲が失敗した場合、その項目に error フィールドが付き、他の楽曲は通常どおり返ります。

注意事項

すべてのエンドポイントはプラットフォームがホストするメディアアドレスのみを返し、Suno 側の暗号化ソースや一時署名アドレスは返しません。
アドレスは恒久的ではありません。長期保存する場合はご自身で転送してください。原本をディスクに保存したい場合は download-file を使ってください。
ステムの MIDI はそのステムの分離が完了している必要があり、完了していない場合はエラーを返します。

次のページFree2 ダウンロード API

API キーの取得

登録後、コンソールで API キーを作成できます。1 回 0.6 元で 2 曲が生成され、ダウンロードは無制限、電話番号は不要です。

API キーを取得概要に戻る