Przejdź do głównej treści
POST https://api.acedata.cloud/suno/projects to interfejs Beta do zarządzania projektami wielościeżkowymi. Za pomocą action rozróżnia się tworzenie, zapisywanie, generowanie kandydatów, zatwierdzanie kandydatów i eksportowanie.
Z wyjątkiem retrieve, każda operacja wymaga Idempotency-Key. Ten sam klucz i to samo żądanie jedynie zwracają ponownie pierwotny wynik; ten sam klucz z innym żądaniem zwraca 409. Gdy płatne generowanie napotka przekroczenie limitu czasu sieci lub wynik zatwierdzenia jest niepewny, najpierw użyj pierwotnego ID zadania lub tego samego klucza idempotencji do zapytania, nie można bezpośrednio zmienić klucza i wysłać ponownie.

Identyfikatory i jednostki czasu

start_seconds / end_seconds to liczba sekund w źródłowym audio; start_beats / end_beats to liczba beatów na osi czasu projektu. state.timing.bps to liczba beatów na sekundę, domyślnie 2. Na przykład fragment o długości 41 sekund, zaczynający się od beatu 0, ma domyślny punkt końcowy na beacie 82. Zakres sekund generate_track służy do określenia referencji generowania i nie gwarantuje, że kandydat będzie miał długość tylko tego zakresu.

Przepływ operacji

Jeśli wykonywane jest tylko częściowe zastąpienie, wystarczy istniejące dostępne źródłowe audio i nie trzeba najpierw używać render; jeśli źródłowe audio jest już w projekcie, można również pominąć upload i add_track. render_audio_id jest jedynie obowiązkową referencją dla generate_track. Podczas przesyłania operacji asynchronicznej najpierw zwracane jest { "task_id": "...", "trace_id": "..." }, co nie oznacza pomyślnego wygenerowania. Odpytywanie:
Dopiero gdy rekord zadania ma finished_at, a zawarte w nim response.success ma wartość true, uznaje się je za sukces; gdy response.success=false, odczytaj response.error. Chociaż save może zawierać task_id, w tym interfejsie jest wykonywane synchronicznie. upload, render, generate_track, replace_section nie modyfikują wersji projektu; po pomyślnym save, add_track, commit_candidate, remove_track należy pobrać nowe version_id.

Konwencje żądań

Poniższe przykłady w łańcuchu pokazują przekazywanie ID i wersji między poszczególnymi operacjami. Odpowiedzi zawierają tylko pola związane z bieżącym krokiem; podczas integracji zastąp przykładowe ID wartościami odpowiedzi bieżącej aplikacji.

Tworzenie i odczytywanie projektu

Tworzenie projektu: create

Żądanie:
Odpowiedź:

Odczytywanie projektu: retrieve

Żądanie:```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” } }