Zum Hauptinhalt springen
POST https://api.acedata.cloud/suno/projects ist die Beta-Schnittstelle zur Verwaltung von Mehrspurprojekten. Über action werden Erstellen, Speichern, Generieren von Kandidaten, Übermitteln von Kandidaten und Exportieren unterschieden.
Außer bei retrieve ist für jede Operation ein Idempotency-Key erforderlich. Derselbe Schlüssel und dieselbe Anfrage lesen nur das ursprüngliche Ergebnis zurück; derselbe Schlüssel mit einer anderen Anfrage gibt 409 zurück. Wenn bei kostenpflichtiger Generierung ein Netzwerk-Timeout auftritt oder das Übermittlungsergebnis ungewiss ist, fragen Sie zuerst mit der ursprünglichen Aufgaben-ID oder demselben Idempotenzschlüssel ab und senden Sie nicht direkt mit einem neuen Schlüssel erneut.

Kennungen und Zeiteinheiten

start_seconds / end_seconds sind Sekunden innerhalb des Quellaudios; start_beats / end_beats sind Schläge auf der Projekt-Zeitachse. state.timing.bps ist die Anzahl der Schläge pro Sekunde, standardmäßig 2. Beispielsweise beginnt ein 41-Sekunden-Clip bei Schlag 0, und sein Standardendpunkt ist Schlag 82. Der Sekundenbereich von generate_track dient zur Angabe der Generierungsreferenz und garantiert nicht, dass ein Kandidat nur die Länge dieses Bereichs hat.

Operationsablauf

Wenn nur eine lokale Ersetzung durchgeführt wird, genügt vorhandenes verwendbares Quellaudio, ein vorheriges render ist nicht erforderlich; wenn sich das Quellaudio bereits im Projekt befindet, können upload und add_track ebenfalls übersprungen werden. render_audio_id ist nur die erforderliche Referenz für generate_track. Bei der Übermittlung einer asynchronen Operation wird zuerst { "task_id": "...", "trace_id": "..." } zurückgegeben, was nicht bedeutet, dass die Generierung erfolgreich war. Abfrage:
Eine Aufgabe gilt erst als erfolgreich, wenn der Aufgabeneintrag finished_at enthält und darin response.success den Wert true hat; bei response.success=false lesen Sie response.error. Obwohl save möglicherweise eine task_id enthält, wird es innerhalb dieser Schnittstelle synchron abgeschlossen. upload, render, generate_track, replace_section ändern die Projektversion nicht; nach erfolgreichem save, add_track, commit_candidate, remove_track sollte die neue version_id übernommen werden.

Anfragerichtlinien

Die folgenden Beispiele zeigen zusammenhängend die Übergabe von IDs und Versionen zwischen den einzelnen Operationen. Die Antworten enthalten nur die für den aktuellen Schritt relevanten Felder; ersetzen Sie bei der Integration die Beispiel-IDs durch die Antwortwerte der aktuellen Anwendung.

Projekt erstellen und lesen

Projekt erstellen: create

Anfrage:
Antwort:

Projekt lesen: retrieve

Anfrage:```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” } }