메인 콘텐츠로 건너뛰기
POST https://api.acedata.cloud/suno/projects는 멀티트랙 프로젝트를 관리하는 Beta 인터페이스입니다. action을 통해 생성, 저장, 후보 생성, 후보 커밋 및 내보내기를 구분합니다.
retrieve를 제외하고, 매 작업마다 Idempotency-Key가 필요합니다. 동일한 키와 동일한 요청은 원래 결과만 다시 반환합니다. 동일한 키에 다른 요청을 사용하면 409를 반환합니다. 유료 생성에서 네트워크 시간 초과가 발생하거나 커밋 결과가 불확실한 경우, 먼저 원래 작업 ID 또는 동일한 멱등성 키로 조회해야 하며, 직접 키를 바꿔 재전송하면 안 됩니다.

식별자 및 시간 단위

start_seconds / end_seconds는 원본 오디오 내의 초 단위입니다. start_beats / end_beats는 프로젝트 타임라인상의 비트 수입니다. state.timing.bps는 초당 비트 수이며, 기본값은 2입니다. 예를 들어 41초 길이의 세그먼트가 0비트에서 시작하면 기본 종료점은 82비트입니다. generate_track의 초 단위 구간은 생성 참조를 지정하는 데 사용되며, 후보가 해당 구간 길이만 갖는다고 보장하지 않습니다.

작업 흐름

부분 교체만 수행하는 경우 기존에 사용 가능한 원본 오디오가 있으면 되며, 먼저 render할 필요가 없습니다. 원본 오디오가 이미 프로젝트에 있는 경우 upload 및 add_track도 건너뛸 수 있습니다. render_audio_id는 generate_track의 필수 참조일 뿐입니다. 비동기 작업 제출 시 먼저 { "task_id": "...", "trace_id": "..." }가 반환되며, 생성 성공을 의미하지는 않습니다. 폴링:
작업 레코드에 finished_at가 있고 그 안의 response.success가 true여야 성공으로 간주합니다. response.success=false일 때는 response.error를 읽습니다. save는 task_id를 포함할 수 있지만, 이 인터페이스 내에서는 동기적으로 완료됩니다. upload, render, generate_track, replace_section은 프로젝트 버전을 수정하지 않습니다. save, add_track, commit_candidate, remove_track가 성공한 후에는 새 version_id를 가져와야 합니다.

요청 규약

아래 예시는 각 작업 간의 ID 및 버전 전달을 순서대로 보여 줍니다. 응답에는 현재 단계와 관련된 필드만 나열됩니다. 연동 시 현재 애플리케이션의 응답 값으로 예시 ID를 대체하십시오.

프로젝트 생성 및 읽기

프로젝트 생성: create

요청:
응답:

프로젝트 읽기: retrieve

요청:```json { “action”: “retrieve”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6” }
{ “success”: true, “trace_id”: “a335ceac-5cb7-4b1c-9773-77b9d5c84bd7”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } } }
{ “action”: “save”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } }
{ “success”: true, “task_id”: “ab172b47-4d89-404b-a10e-71f67c36ccba”, “trace_id”: “fc7b2e43-7a7a-4276-8671-27008a1153ea”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “state”: { “timing”: { “bps”: 2 }, “tracks”: [] } } }
{ “action”: “upload”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_url”: “https://cdn.acedata.cloud/suno_demo.mp3”, “async”: true }
{ “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18” }
{ “success”: true, “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “candidate”: { “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “title”: “suno_demo”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/b21be571-bfe4-47c1-b59c-2abc55c6f9c3.m4a” } } }
{ “action”: “add_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “name”: “Source demo”, “start_beats”: 0 }
{ “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07” }
{ “success”: true, “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cf8a6aa5-0f6d-4da3-844e-cc156aa1b731”, “track”: { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “name”: “Source demo”, “clips”: [ { “clipId”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “startBeats”: 0, “endBeats”: 82 } ] } } }
{ “id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “type”: “audio”, “name”: “Generated piano”, “clips”: [], “takeLanes”: [], “mute”: false, “solo”: false, “amplitude”: 1, “instrument”: { “type”: “song” }, “color”: “#7251F7” }
{ “success”: true, “task_id”: “783f8d49-cc59-4a65-9f9d-ca00e7d7b8a9”, “trace_id”: “0a9c8f13-7e4f-4915-8a40-010ce4ac61dc”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d” } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “title”: “Suno Projects Docs Source Mix”, “lyrics”: “[Instrumental]”, “async”: true }
{ “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154” }
{ “success”: true, “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “render_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/41038732-4dc4-40bf-b00d-2728d99bc26e.m4a” } }
{ “action”: “generate_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “source_audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “render_audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “model”: “chirp-v5”, “start_seconds”: 12, “end_seconds”: 20, “stem_control_tags”: “add Piano”, “title”: “Documentation Piano Take”, “tags”: “gentle piano, instrumental”, “async”: true }
{ “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f” }
{ “success”: true, “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “operation_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “candidates”: [ { “id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 41.76, “audio_url”: “https://cdn.acedata2.cloud/suno/20f8ffe5063111b1eb866336242e2c0b2b9b7103a8dc0c0c19106cbf50843f86.mp3” }, { “id”: “18d6e0a4-2d73-43c3-92e9-be87cf11e139”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 40.96, “audio_url”: “https://cdn.acedata2.cloud/suno/c1c50a016333e3a037f18f651c0a88061880b3069aee7c6a258d6c9cdc041a6b.mp3” } ] } }
{ “action”: “commit_candidate”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “operation_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “candidate_id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “async”: true }
{ “task_id”: “3291bd86-d524-4720-9b6e-655efa600e3d”, “trace_id”: “1bfee6c0-e936-4147-8a75-a903173d13d6” }
{ “success”: true, “task_id”: “3291bd86-d524-4720-9b6e-655efa600e3d”, “trace_id”: “1bfee6c0-e936-4147-8a75-a903173d13d6”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “committed_candidate_id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “clips”: [ { “clipId”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “startBeats”: 0, “endBeats”: 82 } ] }, { “id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “clips”: [ { “clipId”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “startBeats”: 0, “endBeats”: 83.52 } ] } ] } } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “title”: “Suno Projects Docs Mix With Piano”, “lyrics”: “[Instrumental]”, “async”: true }
{ “task_id”: “12fe503c-017e-46db-9d99-8cfb861ad4fc”, “trace_id”: “2f376c45-a081-4c2a-b6a5-658401fe8dc0” }
{ “success”: false, “task_id”: “12fe503c-017e-46db-9d99-8cfb861ad4fc”, “trace_id”: “2f376c45-a081-4c2a-b6a5-658401fe8dc0”, “error”: { “code”: “studio_audio_unavailable”, “message”: “A referenced audio is not available for project rendering. Keep the original project and use a supported audio.” } }
{ “action”: “replace_section”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “source_audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “model”: “chirp-v5”, “title”: “Documentation Verse Edit”, “tags”: “dreamy Chinese pop”, “prompt”: “[Verse 1]\n晨光洒在海边\n浪花笑得灿烂\n你和我在沙滩\n钟表停止转动\n冰淇淋在融化\n手牵手去散步\n[Chorus]\n风儿轻轻吹过\n心跳不停鼓\n夏天夏天\n时间停在这一天\n笑声回荡\n微蓝天空在身旁”, “replacement_lyrics”: “我们走在海边\n微风吹过晴天”, “start_seconds”: 12, “end_seconds”: 20, “async”: true }
{ “task_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “trace_id”: “9f9c0bec-963d-417f-aaf2-0b7f89e0dcbc” }
{ “success”: true, “task_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “trace_id”: “9f9c0bec-963d-417f-aaf2-0b7f89e0dcbc”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “operation_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “candidates”: [ { “id”: “c486e799-5f89-4db0-b414-3b666e0db2b3”, “title”: “Documentation Verse Edit”, “state”: “complete”, “duration”: 36, “audio_url”: “https://cdn.acedata2.cloud/suno/287a448c0e6099b5e66901f363607bcfcf38d06312c344b03a3486bbb4fe037b.mp3” }, { “id”: “f0b66dff-9f8e-45f2-b441-c94e2ecd3a11”, “title”: “Documentation Verse Edit”, “state”: “complete”, “duration”: 36, “audio_url”: “https://cdn.acedata2.cloud/suno/172227abd70f2201081a8f58e4c3b401f1e75fd0b29c03aa95abdb6689bfd0a5.mp3” } ] } }
{ “action”: “commit_candidate”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “operation_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “candidate_id”: “c486e799-5f89-4db0-b414-3b666e0db2b3”, “track_id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “async”: true }
{ “task_id”: “2261a2a6-d7fb-42ac-ae58-41005cfc8173”, “trace_id”: “25c6e92d-e0b9-4f9b-ba35-434635ec7bb3” }
{ “success”: false, “task_id”: “2261a2a6-d7fb-42ac-ae58-41005cfc8173”, “trace_id”: “25c6e92d-e0b9-4f9b-ba35-434635ec7bb3”, “error”: { “code”: “bad_request”, “message”: “Candidate duration does not match the source or selected section. Keep the original track and inspect the candidate before editing.” } }
{ “action”: “remove_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06” }
{ “success”: true, “trace_id”: “5df2f4b4-6f09-4006-93bd-ad44f4ccb8c1”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “removed_track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9” } ] } } }
{ “success”: true, “trace_id”: “c7613f9b-6484-47b1-83ff-f8a0c1529d8e”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9” } ] } } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “title”: “Suno Projects Docs Mix After Remove”, “async”: true }
{ “task_id”: “41c8bcb2-eb98-4da7-8081-7755bcc7be8d”, “trace_id”: “6480a230-7553-4dd1-a8e2-9131dab418a9” }
{ “success”: true, “task_id”: “41c8bcb2-eb98-4da7-8081-7755bcc7be8d”, “trace_id”: “6480a230-7553-4dd1-a8e2-9131dab418a9”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “render_id”: “75aaaa5f-e633-4006-9200-98d03f3542af”, “audio_id”: “75aaaa5f-e633-4006-9200-98d03f3542af”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/75aaaa5f-e633-4006-9200-98d03f3542af.m4a” } }