Интеграция и использование Suno Tasks API

Основная функция Suno Tasks API — запрашивать статус выполнения задачи путём ввода ID задачи, созданной Suno Audios Generation API или Suno Lyrics Generation API. Этот документ подробно представит инструкции по интеграции Suno Tasks API, помогая вам легко интегрировать и в полной мере использовать мощные возможности этого API. С помощью Suno Tasks API вы можете легко реализовать запрос статуса выполнения задач Suno Lyrics Generation API или Suno Audios Generation API.

Процесс подачи заявки

Чтобы использовать Suno Audios Generation API, сначала получите ваш API Token в консоли Ace Data Cloud, чтобы сохранить его для дальнейшего использования.

Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему, после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, без необходимости отдельно подавать заявку для каждого сервиса. При первой заявке предоставляются бесплатные лимиты, которые можно использовать для бесплатного ознакомления; при недостатке лимитов вы можете пополнить общий баланс в консоли.

📘 Полная документация: Suno Audios Generation API →

Пример запроса

Suno Tasks API может использоваться для запроса результатов двух API: Suno Audios Generation API и Suno Lyrics Generation API. О том, как использовать Suno Audios Generation API, обратитесь к документации Suno Audios Generation API . О том, как использовать Suno Lyrics Generation API, обратитесь к Suno Lyrics Generation API . Мы возьмём в качестве примера ID задачи, возвращённый сервисом Suno Audios Generation API, чтобы продемонстрировать, как использовать этот API. Предположим, у нас есть ID задачи: eae26f89-b64b-404d-a80c-761996660b1c, далее продемонстрируем, как через передачу 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": "La La La",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nMi vekiĝas ĉiumatene\nRigardas tra la fenestro\nSunbrilo brilanta hela\nKomenco de nova tago\n[Verse 2]\nLa birdoj kantas ĝoje\nMi dancas en la ĝardeno\nĈirkaŭas min floroj belaj\nĈiu momento ĉi estas mia\n[Chorus]\nLa la la la la la\nKantu kun mi\nNe haltu\nLa la la la la la\nĜoju ĝuante la vivon\n[Verse 3]\nLa maro blua kaj vasta\nOndoj tajdas dolĉe\nNi promenas sur plaĝoj\nSendepende de la tempo\n[Bridge]\nKaptu ĉiun horon\nAŭdu miajn kantadojn\nSentu vin libera\nFeliĉa\nDancu laŭ la ritmo nun\n[Chorus]\nLa la la la la la\nKantu kun mi\nNe haltu\nLa la la la la la\nĜoju ĝuante la vivon",
            "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": "la la la",
            "style": "pop",
            "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. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Интеграция и использование Suno Tasks API

Процесс подачи заявки

Пример запроса

Изображение примера задачи

Настройка заголовков запроса и тела запроса

Пример кода

CURL

Python

Пример ответа

Операция пакетного запроса

Пример кода

Пример ответа

CURL

Python

Обработка ошибок

Пример ответа с ошибкой

Заключение

​Процесс подачи заявки

​Пример запроса

​Изображение примера задачи

​Настройка заголовков запроса и тела запроса

​Пример кода

​CURL

​Python

​Пример ответа

​Операция пакетного запроса

​Пример кода

​Пример ответа

​CURL

​Python

​Обработка ошибок

​Пример ответа с ошибкой

​Заключение

Процесс подачи заявки

Пример запроса

Изображение примера задачи

Настройка заголовков запроса и тела запроса

Пример кода

CURL

Python

Пример ответа

Операция пакетного запроса

Пример кода

Пример ответа

CURL

Python

Обработка ошибок

Пример ответа с ошибкой

Заключение