楽曲照会と履歴 API

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

本ページは無料の照会エンドポイントを 3 つ扱います：

生成エンドポイントの受理レシートモード（accept_mode=async）を使った場合、手元にあるのは歌曲 ID ではなく 受理番号です。進捗は GET /api/music/requests/{request_id} で照会し、実際の song_id を取得してから 本ページのエンドポイントに戻ってください。詳しくはひらめきモード生成 API の 「受理レシートモード」をご覧ください。

認証とデータ範囲

3 つのエンドポイントはいずれも同じ API Key で認証します：

Authorization: Bearer YOUR_API_KEY

楽曲履歴は API Key が属する user_id ごとに分離されます。同じメインアカウントで作成した複数の API Key はそのメインアカウントの楽曲履歴を照会できますが、他のユーザーやサブサイトアカウントの楽曲は照会できません。

履歴系エンドポイントは実際に生成された楽曲だけを返します。次は含まれません：

• pending: で始まる生成のプレースホルダー記録；
• ソース音声のアップロードと強化アップロードの記録；
• ボーカル／伴奏分離やステムなどの副次的な結果；
• 他のユーザーやサブサイトアカウントの楽曲。

1. 生成状態の照会

1 つまたは複数の楽曲 ID から、現在の生成状態と最終結果を照会します。

エンドポイント：POST /api/music/query

課金：無料。

Headers

Body パラメータ

リクエスト例

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

レスポンス例

[
  {
    "song_id": "clip_id_1",
    "song_title": "曲のタイトル",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "歌詞の本文",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

互換性の注意

旧版のドキュメントでは song_ids を配列としている場合があります。現在はカンマ区切りの文字列を推奨しており、実際の呼び出し方法と一致します。

song_ids は実在する楽曲 ID である必要があります。pending: で始まるプレースホルダー ID は最終的な song_id ではなく、本エンドポイントには使えません。プレースホルダー ID だけを照会すると空配列 [] が返ることがあります。

レスポンスの model、model_version、プラットフォームの model_name は過去の値が残ることがあります。新しいタスクには suno-v6、suno-v6-wild、suno-v6-mini を使ってください。suno-v2 〜 suno-v5-5 は提供終了しており、履歴にこれらの名前が現れても、そのモデルを引き続き投入できることを意味しません。

生成タスクが pending、submitted、processing の間は、audio_url、video_url、cover_url が空になることがあり、これはタスク未完了の正常な状態です。アドレスが空ということだけで失敗と判断せず、status とあわせて判断し、状態が完了してから再度照会してください。状態が完了しているのにアドレスが空のままの場合に限り、song_id を添えてテクニカルサポートにご連絡ください。

⚠️ 音声アドレスの有効期間は 7 日です。早めに転送してください

本エンドポイントが返す audio_url、video_url（および WAV などの他のメディアアドレス）はプラットフォームのオブジェクトストレージから提供され、既定で 7 日後に失効します。期限を過ぎるとファイルは回収され、古いアドレスにアクセスすると 404 が返ります。

• 7 日以内にご自身のストレージへファイルを転送してください。長期利用できるリンクとは考えないでください。
• アドレスの失効は楽曲の再生成を必要とせず、再度課金もされません。本エンドポイント（POST /api/music/query）をもう一度呼び出せば、その楽曲の新しい有効なアドレスが取得できます。

2. アカウントの楽曲履歴を照会

現在の API Key が属するメインアカウントが生成した楽曲を照会します。独自の楽曲一覧、セレクタ、履歴ページの構築に向いています。

エンドポイント：GET /api/music/songs

課金：無料。

Query パラメータ

結果は created_at と内部レコード ID の降順で並び、ページ送りの順序が安定します。

投稿がタイムアウトしたときの見つけ方：生成系エンドポイントは受理前に中間レスポンスを返しません。投稿時にクライアントがタイムアウトした、あるいは接続が切れた場合、その注文はすでに受理され生成されている可能性があります。本エンドポイントを新しい順に一度確認してください。受理済みの楽曲は通常どおり一覧に現れます。本当に無いことを確認してから再投稿し、二重課金を避けてください。詳しくは新版 API 概要の「待ち時間とタイムアウト設定」をご覧ください。

リクエスト例

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "夜の街",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

返却フィールド

一覧エンドポイントはプロンプト、課金フィールド、アカウント情報、生のレスポンスを返しません。プロンプトや生成パラメータが必要な場合は楽曲詳細エンドポイントを呼び出してください。

3. 生成パラメータの照会

楽曲 ID から、生成時にプラットフォームが保存したプロンプト、スタイル、モデル、ソース楽曲などのパラメータを照会します。

エンドポイント：GET /api/music/songs/:song_id

課金：無料。

現在の API Key が属するメインアカウントの楽曲のみ照会できます。他のユーザーやサブサイトアカウントの楽曲は一律で「楽曲が存在しません」として扱われます。

パスパラメータ

リクエスト例

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "夜の街",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "雨上がりの街角、再会についての歌詞",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "夜の街",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

parameters フィールド

prompt_view フィールド（プロンプト表示用、2026-09-28 追加）

prompt_view は「プロンプト表示」専用の正規化構造です。生成タイプごとに固定の区画へデータを整理するため、 クライアント側でどのフィールドを表示すべきか判断する必要がなくなります。純粋な追加フィールドであり、従来の フィールド（parameters、parameter_retention）の名前と意味は変わらず、新しいフィールドを解析しない クライアントはまったく影響を受けません。

"prompt_view": {
  "type": "custom_generate",
  "type_label": "プロモード",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "午前四時#701f37", "title_base": "午前四時", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "……", "user_text_kind": "lyrics",
    "user_style": "国潮エレクトロ, 重低音ベース, レトロシンセ",
    "style_tags": "国潮エレクトロ, 重低音ベース, レトロシンセ",
    "style_source": "user", "lyrics": "……",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

extended に現れうるフィールド：vocal_gender、style_weight、audio_weight、 weirdness_constraint、variety、lyrics_mode、custom_mode、およびサウンドエフェクト系の sound_type / sound_bpm / sound_key / sound_loop。空値は一律で返しません。

表示ルールは 3 つです（推測せず、このとおりに実装してください）：

1. スタイルの出所を区別する：style_source=suno_derived の場合は 「スタイル（Suno があなたの説明からまとめたもの）」と表示し、「あなたが入力したスタイル」と書かないでください；
2. 内部プロンプトは現れない：音色カバー系はユーザーが入力した【スタイル要件】／【カバー要件】だけを返し、 モデル向けに組み立てる固定の構造部分はどのフィールドにも現れません（履歴データも同様にマスク済み）；
3. 保存されていないパラメータを推測しない：extended に無ければ当時記録されていないので、retention を使って理由を説明してください。

パラメータ保存の説明

parameter_retention は「明示的に空値を渡した」場合と「歴史的にそのフィールドを保存していない」場合を区別するためのものです：

• core_parameters_available：主楽曲タスク記録が存在するか。正常な詳細では常に true；
• extended_parameters_available：関連する拡張音楽タスク記録が見つかったか；
• sources：今回のパラメータがどのデータテーブル由来か；
• unavailable_fields：履歴データから確実に復元できないフィールド。これらは parameters 内で null を返します。

通常の履歴楽曲はプロンプト、スタイル、現在のタイトル、モデル、生成タイプ、ソース楽曲を保存していますが、すべての高度なパラメータを個別には保存していません。プラットフォームは generation_type から欠損値を推測しません。

一部の拡張音楽タスクは元のプロンプト、スタイル、タイトル、モデルに加えて、custom_mode、negative_tags、vocal_gender、style_weight、weirdness_constraint も保存しています。拡張レコードが存在しても、instrumental、lyrics_mode、wait_audio は復元できないことがあります。

楽曲タイトルは後からユーザーが変更できます。通常の履歴タスクで元のタイトルを別途保存していない場合、parameters.title は現在のタイトルのことがあります。拡張タスク記録がある場合は、そこに保存された元の生成タイトルを優先して返します。

存在しない／権限が無い場合

業務エラーは共通のレスポンス封筒を使います。楽曲が存在しない、または現在のアカウントに属さない場合は次を返します：

{
  "success": false,
  "message": "song not found"
}

この業務エラーは現在 HTTP 200 で返されるため、結果は success フィールドで判断してください。API Key の欠落、無効、期限切れ、無効化の場合は HTTP 401 を返します。

セキュリティについて

楽曲履歴と詳細のエンドポイントは次を返しません：

• API Key、Token ID；
• クォータ、課金、返金のフィールド；
• アカウント情報と生のレスポンス；
• オブジェクトストレージの内部キー；
• 管理者エラーと内部リソースのエラー。