Suno Tasks API の連携と使用方法

Suno Music Generation API guide - Ace Data Cloud

Suno Tasks API の主な機能は、Suno Audios Generation API または Suno Lyrics Generation API によって生成されたタスクIDを入力して、そのタスクの実行状況を照会することです。

本ドキュメントでは、Suno Tasks API の連携に関する説明を詳しく紹介し、この API の強力な機能を簡単に統合して十分に活用できるよう支援します。Suno Tasks API を使用すると、Suno Lyrics Generation API または Suno Audios Generation API のタスク実行状況を簡単に照会できます。

​

申請プロセス

Suno Audios Generation API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えておいてください。

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインが求められます。完了後、自動的に現在のページへ戻ります。

1つの API Token でプラットフォーム上のすべてのサービスを呼び出すことができ、サービスごとに個別で申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます。残高が不足した場合は、コンソール で共通残高をチャージできます。

📘 完全なドキュメント：Suno Audios Generation API →

​

リクエスト例

Suno Tasks API は、Suno Audios Generation API と Suno Lyrics Generation API の2つの API の結果を照会するために使用できます。Suno Audios Generation API の使用方法については、ドキュメント Suno Audios Generation API を参照してください。Suno Lyrics Generation API の使用方法については、Suno Lyrics Generation API を参照してください。

ここでは、Suno Audios Generation API サービスから返された1つのタスクIDを例として、この API の使用方法を説明します。タスクID：eae26f89-b64b-404d-a80c-761996660b1c があると仮定し、次に1つのタスクIDを渡してどのようにするかを説明します。

​

タスク例の図

​

リクエストヘッダーとリクエストボディの設定

Request Headers には以下が含まれます：

• accept：JSON 形式のレスポンス結果を受け取るよう指定します。ここでは application/json を入力します。
• authorization：API を呼び出すためのキーです。申請後、直接ドロップダウンから選択できます。

Request Body には以下が含まれます：

• id：アップロードされたタスクID。
• action：タスクに対する操作方法。

設定は以下の図のとおりです：

​

コード例

ページ右側には、すでにさまざまな言語のコードが自動生成されていることが確認できます。図のとおりです：

一部のコード例は以下のとおりです：

​

CURL

curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "action": "retrieve"
}'

​

Python

import requests

url = "https://api.acedata.cloud/suno/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​

レスポンス例

リクエストが成功すると、API はここでの楽曲タスクの詳細情報を返します。例えば：

{
  "_id": "66d2add5550a4144a5a88dfe",
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
  "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
  "created_at": 1725083093.077,
  "started_at": 1725083093.137,
  "finished_at": 1725083131.537,
  "elapsed": 38.4,
  "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
  "request": {
    "action": "generate",
    "prompt": "A song for Christmas"
  },
  "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "data": [
      {
        "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 154.44
      },
      {
        "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 147.16
      }
    ]
  }
}

返される結果には複数のフィールドがあり、request フィールドはタスク開始時の request body であり、同時に response フィールドはタスク完了後に返される response body です。フィールドの説明は以下のとおりです。

• id、この楽曲生成タスクの ID であり、今回の楽曲生成タスクを一意に識別するために使用されます。
• request、楽曲タスクのクエリにおけるリクエスト情報です。
• response、楽曲タスクのクエリにおける返却情報です。
• created_at、タスク作成時刻、Unix タイムスタンプ（秒、浮動小数点）です。
• started_at、タスク実行開始時刻、Unix タイムスタンプ（秒、浮動小数点）です。
• finished_at、タスク完了時刻、Unix タイムスタンプ（秒、浮動小数点）です。タスクが未完了の場合、このフィールドは返されません。
• elapsed、タスクの実行時間で、単位は秒（浮動小数点、小数点以下 3 桁まで）です。タスクが未完了の場合、このフィールドは返されません。

​

一括クエリ操作

これは複数のタスク ID を対象に楽曲タスクの詳細をクエリするもので、上記との違いは action を retrieve_batch に選択する必要があることです。

Request Body には以下が含まれます：

• ids：アップロードしたタスク ID の配列。
• action：タスクに対する操作方法。

設定は以下の図のとおりです：

​

コード例

ページ右側にはすでに各種言語のコードが自動生成されていることがわかります。図のとおりです：

一部のコード例は以下のとおりです：

​

レスポンス例

リクエストが成功すると、API は今回のすべての一括楽曲タスクの具体的な詳細情報を返します。例えば：

  "items": [
    {
      "_id": "66d2add5550a4144a5a88dfe",
      "id": "eae26f89-b64b-404d-a80c-761996660b1c",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083093.077,
      "started_at": 1725083093.137,
      "finished_at": 1725083131.537,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "generate",
        "prompt": "A song for Christmas"
      },
      "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
        "data":
[
          {
            "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
            "title": "ホリデーの願い",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[ヴァース]\n雪が柔らかく白く降っている\n明かりがとても明るくきらめいている\n子どもたちは喜びに満ちて笑っている\nついにクリスマスの時が来た\n[ヴァース 2]\n夜に鐘が鳴っている\n暖炉は光で暖かい\n木のそばで歌われるキャロル\nみんなが一緒だと私たちは同意する\n[コーラス]\nホリデーの願いが叶う\nあなたと喜びを分かち合う時\nみんなに笑顔とハグを\nメリークリスマス、楽しもう\n[ヴァース 3]\n贈り物は愛情を込めて包まれている\n魔法が空中に漂っている\nオーブンでクッキーが焼かれている\n与えられるクリスマスの愛\n[コーラス]\nホリデーの願いが叶う\nあなたと喜びを分かち合う時\nみんなに笑顔とハグを\nメリークリスマス、楽しもう\n[ブリッジ]\n星が空に輝いている\n愛する人たちを抱きしめて、理由は聞かないで\n心と心で、私たちは皆ひとつになっている\nこの夜、私たちは喜んでいる",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "クリスマスのための歌",
            "style": "ポップ",
            "duration": 154.44
          }, {
            "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
            "title": "ホリデーの願い",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[ヴァース]\n雪が柔らかく白く降っている\n明かりがとても明るくきらめいている\n子どもたちは喜びに満ちて笑っている\nついにクリスマスの時が来た\n[ヴァース 2]\n夜に鐘が鳴っている\n暖炉は光で暖かい\n木のそばで歌われるキャロル\nみんなが一緒だと私たちは同意する\n[コーラス]\nホリデーの願いが叶う\nあなたと喜びを分かち合う時\nみんなに笑顔とハグを\nメリークリスマス、楽しもう\n[ヴァース 3]\n贈り物は愛情を込めて包まれている\n魔法が空中に漂っている\nオーブンでクッキーが焼かれている\n与えられるクリスマスの愛\n[コーラス]\nホリデーの願いが叶う\nあなたと喜びを分かち合う時\nみんなに笑顔とハグを\nメリークリスマス、楽しもう\n[ブリッジ]\n星が空に輝いている\n愛する人たちを抱きしめて、理由は聞かないで\n心と心で、私たちは皆ひとつになっている\nこの夜、私たちは喜んでいる",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "クリスマスのための歌",
            "style": "ポップ",
            "duration": 147.16
          }
        ]
      }
    }, {
      "_id": "66d2b03c550a4144a5a8d93d",
      "id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083708.53,
      "started_at": 1725083708.59,
      "finished_at": 1725083746.99,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "生成",
        "prompt": "ラ・ラ・ラ"
      },
      "trace_id": "29ebb919-1126-4156-86cc-4ad899432a8c",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
        "data": [
          {
            "id": "b4f498b2-e86f-4172-926a-39da9df84dd3",
            "title": "ラ・ラ・ラ",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[ヴァース]\n私は毎朝目を覚ます\n窓の外を見る\n明るく輝く陽の光\n新しい一日の始まり\n[ヴァース 2]\n鳥たちが楽しげに歌う\n私は庭で踊る\n美しい花々が私を囲む\nこの瞬間はすべて私のもの\n[コーラス]\nラ・ラ・ラ・ラ・ラ・ラ\n私と一緒に歌って\n止まらないで\nラ・ラ・ラ・ラ・ラ・ラ\n人生を楽しんで喜ぼう\n[ヴァース 3]\n青く広大な海\n波が優しく寄せては返す\n私たちは浜辺を歩く\n天気に関係なく\n[ブリッジ]\n一時間一時間をつかんで\n私の歌声を聞いて\n自由を感じて\n幸せに\n今、リズムに合わせて踊って\n[コーラス]\nラ・ラ・ラ・ラ・ラ・ラ\n私と一緒に歌って\n止まらないで\nラ・ラ・ラ・ラ・ラ・ラ\n人生を楽しんで喜ぼう",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "ラ・ラ・ラ",
            "style": "ポップ",
            "duration": 154.32
          },
{
            "id": "8b44fdf1-3b88-47ac-a351-7c4b4de60549",
            "title": "ラ・ラ・ラ",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[ヴァース]\n私は毎朝目を覚ます\n窓の外を見る\n明るく輝く陽光\n新しい一日の始まり\n[ヴァース 2]\n鳥たちは楽しく歌う\n私は庭で踊る\n美しい花々が私を囲む\nこの一瞬一瞬が私のもの\n[コーラス]\nラ・ラ・ラ・ラ・ラ・ラ\n私と一緒に歌って\n止まらないで\nラ・ラ・ラ・ラ・ラ・ラ\n人生を楽しみながら喜ぼう\n[ヴァース 3]\n青く広い海\n波がやさしく寄せる\n私たちは浜辺を歩く\n天気に関係なく\n[ブリッジ]\nすべての時間をつかんで\n私の歌声を聞いて\n自由を感じて\n幸せに\n今、リズムに合わせて踊って\n[コーラス]\nラ・ラ・ラ・ラ・ラ・ラ\n私と一緒に歌って\n止まらないで\nラ・ラ・ラ・ラ・ラ・ラ\n人生を楽しみながら喜ぼう",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "ラ・ラ・ラ",
            "style": "ポップ",
            "duration": 177.36
          }
        ]
      }
    }
  ],
  "count": 2
}

返される結果には複数のフィールドがあり、そのうち items にはバッチ歌曲タスクの具体的な詳細情報が含まれます。各歌曲タスクの具体的な情報は上記のフィールドと同じであり、フィールド情報は以下のとおりです。

• items、バッチ歌曲タスクのすべての具体的な詳細情報。これは配列であり、各配列要素の形式は上記の単一タスク照会の返却結果と同じです。
• count、ここでバッチ照会する歌曲タスクの数。

​

CURL

curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
  "action": "retrieve_batch"
}'

​

Python

import requests

url = "https://api.acedata.cloud/suno/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
    "action": "retrieve_batch"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​

エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

• 400 token_mismatched：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
• 400 api_not_implemented：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
• 401 invalid_token：未認証。認可トークンが無効または欠落しています。
• 429 too_many_requests：リクエストが多すぎます。レート制限を超えています。
• 500 api_error：内部サーバーエラー。サーバーで問題が発生しました。

​

エラー応答の例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

結論

本ドキュメントを通じて、Suno Tasks API を使用して単一またはバッチの歌曲タスクに関するすべての具体的な詳細情報を照会する方法をご理解いただけたと思います。本ドキュメントが、この API の連携および利用により役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。