> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # 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 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 예비용으로 보관하세요. ![](https://cdn.acedata.cloud/dvc3cg.jpg) 아직 로그인 또는 가입하지 않은 경우, 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. **하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족한 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios) ## 요청 예시 Suno Tasks API는 Suno Audios Generation API와 Suno Lyrics Generation API, 두 API의 결과를 조회하는 데 사용할 수 있습니다. Suno Audios Generation API 사용 방법에 대해서는 [Suno Audios Generation API](https://platform.acedata.cloud/documents/suno-audios-integration) 문서를 참조하세요. Suno Lyrics Generation API 사용 방법에 대해서는 [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics-generation-integration)를 참조하세요. Suno Audios Generation API 서비스가 반환한 작업 ID 하나를 예시로 들어, 해당 API를 사용하는 방법을 보여드리겠습니다. 작업 ID가 `eae26f89-b64b-404d-a80c-761996660b1c`이라고 가정하고, 이어서 하나의 작업 ID를 전달하는 방법을 시연합니다. ### 작업 예시 이미지 ![](https://cdn.acedata.cloud/bc6754.png) ### 요청 헤더 및 요청 본문 설정 **Request Headers**에는 다음이 포함됩니다: * `accept`: JSON 형식의 응답 결과를 수신하도록 지정하며, 여기에는 `application/json`을 입력합니다. * `authorization`: API 호출 키이며, 신청 후 직접 드롭다운에서 선택할 수 있습니다. **Request Body**에는 다음이 포함됩니다: * `id`: 업로드된 작업 ID입니다. * `action`: 작업에 대한 처리 방식입니다. 설정은 아래 이미지와 같습니다: ![](https://cdn.acedata.cloud/uo7t6n.png) ### 코드 예시 페이지 오른쪽에서 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있으며, 아래 이미지와 같습니다: ![](https://cdn.acedata.cloud/p6vi9o.png) 일부 코드 예시는 다음과 같습니다: #### CURL ```bash theme={null} 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 ```python theme={null} 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는 여기에서 음악 작업의 상세 정보를 반환합니다. 예: ```json theme={null} { "_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`: 작업에 대한 수행 방식입니다. 설정은 다음 그림과 같습니다. ![](https://cdn.acedata.cloud/dqeknz.png) ### 코드 예시 페이지 오른쪽에 이미 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있으며, 그림과 같습니다. ![](https://cdn.acedata.cloud/1yk792.png) 일부 코드 예시는 다음과 같습니다. ### 응답 예시 요청이 성공한 후, API는 이번에 일괄 처리된 모든 노래 작업의 구체적인 상세 정보를 반환합니다. 예를 들면 다음과 같습니다. ```json { theme={null} "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": "[Verse]\n눈이 부드럽고 하얗게 내리고 있어\n불빛들이 아주 밝게 반짝이고 있어\n아이들은 기쁨으로 가득 차 웃고 있어\n드디어 크리스마스 시간이 왔어\n[Verse 2]\n밤에 종들이 울리고 있어\n벽난로는 빛으로 따뜻해\n트리 곁에서 부르는 캐럴\n우리 모두 함께라는 데 동의해\n[Chorus]\n홀리데이 소원이 이루어져\n너와 기쁨을 나눌 시간이야\n모두를 위한 미소와 포옹\n메리 크리스마스 재미있게 놀자\n[Verse 3]\n선물들은 사랑을 담아 포장되어 있어\n마법이 공기 속에 떠다니고 있어\n오븐에서 쿠키가 구워지고 있어\n전해질 크리스마스 사랑\n[Chorus]\n홀리데이 소원이 이루어져\n너와 기쁨을 나눌 시간이야\n모두를 위한 미소와 포옹\n메리 크리스마스 재미있게 놀자\n[Bridge]\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": "[Verse]\n눈이 부드럽고 하얗게 내리고 있어\n불빛들이 아주 밝게 반짝이고 있어\n아이들은 기쁨으로 가득 차 웃고 있어\n드디어 크리스마스 시간이 왔어\n[Verse 2]\n밤에 종들이 울리고 있어\n벽난로는 빛으로 따뜻해\n트리 곁에서 부르는 캐럴\n우리 모두 함께라는 데 동의해\n[Chorus]\n홀리데이 소원이 이루어져\n너와 기쁨을 나눌 시간이야\n모두를 위한 미소와 포옹\n메리 크리스마스 재미있게 놀자\n[Verse 3]\n선물들은 사랑을 담아 포장되어 있어\n마법이 공기 속에 떠다니고 있어\n오븐에서 쿠키가 구워지고 있어\n전해질 크리스마스 사랑\n[Chorus]\n홀리데이 소원이 이루어져\n너와 기쁨을 나눌 시간이야\n모두를 위한 미소와 포옹\n메리 크리스마스 재미있게 놀자\n[Bridge]\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": "[Verse]\n나는 매일 아침 깨어나\n창문 너머를 바라봐\n밝게 빛나는 햇살\n새로운 하루의 시작\n[Verse 2]\n새들이 즐겁게 노래해\n나는 정원에서 춤춰\n아름다운 꽃들이 나를 둘러싸\n이 모든 순간은 내 것이야\n[Chorus]\n라 라 라 라 라 라\n나와 함께 노래해\n멈추지 마\n라 라 라 라 라 라\n삶을 즐기며 기뻐해\n[Verse 3]\n푸르고 넓은 바다\n파도가 부드럽게 밀려와\n우리는 해변을 거닐어\n시간과 관계없이\n[Bridge]\n매 시간을 붙잡아\n내 노랫소리를 들어\n자유롭게 느껴\n행복하게\n지금 리듬에 맞춰 춤춰\n[Chorus]\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 ```bash theme={null} 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 ```python theme={null} 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`: 내부 서버 오류이며, 서버에서 문제가 발생했습니다. ### 오류 응답 예시 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 결론 이 문서를 통해 Suno Tasks API를 사용하여 단일 또는 일괄 노래 작업의 모든 구체적인 상세 정보를 조회하는 방법을 이해했습니다. 이 문서가 이 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 문의 사항이 있으면 언제든지 기술 지원 팀에 연락해 주세요. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.