強化アップロード API

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

インターフェースの説明

強化アップロードはローカルの音声ファイルを送信し、システムがバックグラウンドで強化処理を行って再生可能な完成楽曲を生成します。送信するとすぐにタスク情報が返り、クライアントは照会エンドポイントで進捗をポーリングします。

送信エンドポイント: POST /api/music/enhanced-upload

単一タスク照会: GET /api/music/enhanced-upload/:id

タスクのキャンセル: POST /api/music/enhanced-upload/:id/cancel

一覧照会: GET /api/music/enhanced-upload

課金: 1 回 10 元。suno-enhanced-upload の固定価格で事前に課金されます。タスクが失敗した場合、または許可された段階でキャンセルした場合は、事前に引かれた費用が自動的に返金されます。実際の請求額は現在の管理画面の価格設定に従います。

呼び出しフロー

1. POST /api/music/enhanced-upload を呼び出して音声ファイルをアップロードします。
2. 返ってきた task_id を保存します。
3. GET /api/music/enhanced-upload/:id を呼び出して進捗と結果を照会します。
4. Suno の最終レンダリングが完了すると、サービスはそのタスクに紐づく Suno アカウントで Studio の認可ダウンロードエンドポイントを呼び出し、MP3 を CN2 メディアサービスに書き込みます。
5. CN2 の資産準備が成功して初めてタスクは completed になり、そのときレスポンスの audio_url から CDN の音声アドレスを取得します。

/api/forbidden は Suno Studio のメタデータに現れることがあるプレースホルダーアドレスで、再生もダウンロードもできるリソースではありません。お客様に返されることも、完了判定の根拠に使われることもありません。レンダリングが完了していても CN2 がまだ準備中の場合、エンドポイントは processing を返し続け audio_url を返しません。クライアントはポーリングを続け、空のアドレスを失敗と見なさないでください。

強化アップロードの送信

Headers

Form パラメータ

リクエスト例

以下の例は本番検証時と同じ呼び出し方ですが、API Key はプレースホルダーに置き換えています。

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

レスポンス結果

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

単一タスクの照会

リクエスト例

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

処理中のレスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

完了レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

タスクのキャンセル

キャンセルできるのは、タスクとバックエンドのワークフローがともに queued 段階にある間だけです。leasing、running、processing に入った後や完了後はキャンセルできません。

リクエスト例

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

レスポンス結果

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

タスクがすでに処理を開始している場合、エンドポイントは次を返します。

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

タスク一覧の照会

一覧エンドポイントは、現在の API Key が属するユーザーの強化アップロードタスクのみを返し、通常生成・カバー・続き生成などのタスクは混ざりません。

Query パラメータ

リクエスト例

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

レスポンス結果

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

返却フィールドの説明

注意事項

• 現在このエンドポイントは multipart のファイルアップロードのみに対応し、JSON の file_url や file_base64 には対応していません。
• アップロードできるファイルは最大 80 MB です。
• 送信エンドポイントは非同期です。queued が返るのはタスクがキューに入ったという意味で、音声が完成したという意味ではありません。
• キャンセルはまだ処理が始まっていないタスクにのみ有効です。処理段階に入るとプラットフォームアカウントのワークフローは中断されません。
• クライアントコードに実際の API Key を露出させないでください。

強化アップロード完了後のカバー開始

強化アップロードが完了したら、その完了結果をソース clip として POST /api/music/generate-from-source を呼び出し、カバーを開始できます。

注意：カバーは同期エンドポイントで、レスポンスが返った時点で初めて注文が受理されます。実測では最大約 230 秒待つことがあります。クライアントのタイムアウトは 300 秒以上に設定し、タイムアウト後すぐに再試行しないでください。詳しくは新版 API 概要の「待ち時間とタイムアウト設定」をご覧ください。

まず GET /api/music/enhanced-upload/:id をポーリングし、task.status が completed になるまで待ちます。そのとき：

• task.song_id は実在の楽曲 ID で、カバーエンドポイントが必要とする sourceClipId でもあります。
• task.audio_url は sourceAudioUrl として一緒に渡すことをおすすめします。ソース clip と実行アカウントが一致しない場合にサーバーが処理しやすくなります。
• task.task_id は強化アップロードのタスク ID にすぎず、sourceClipId には使えません。
• pending:enhanced-upload:* は処理段階のプレースホルダー ID で、カバーには使えません。

カバーを開始するときは、強化アップロードと同じ API Key を使い、以下のフィールド対応でリクエストを組み立ててください。

残りの歌詞・スタイル・タイトル・モデルなどのパラメータはソース clip からのカバー APIに従って記入します。カバーエンドポイントが新しい clips[].song_id を返したら、POST /api/music/query で生成状態と最終的な音声を照会してください。