Hoppa till huvudinnehåll
POST https://api.acedata.cloud/suno/projects är Beta-gränssnittet för att hantera flerspårsprojekt. Använd action för att skilja mellan skapande, sparande, generering av kandidater, inskickning av kandidater och export.
Förutom retrieve kräver varje åtgärd Idempotency-Key. Samma nyckel och samma begäran läser endast tillbaka det ursprungliga resultatet; samma nyckel med en annan begäran returnerar 409. Vid nätverkstimeout eller osäkerhet kring inskickningsresultatet för avgiftsbelagd generering, fråga först med det ursprungliga uppgifts-ID:t eller samma idempotensnyckel; byt inte direkt nyckel och skicka igen.

Identifierare och tidsenheter

start_seconds / end_seconds är sekunder inom källjudet; start_beats / end_beats är antal taktslag på projektets tidslinje. state.timing.bps är taktslag per sekund, med standardvärdet 2. Till exempel har ett segment på 41 sekunder som börjar vid taktslag 0 som standard ett slut vid taktslag 82. Sekundintervallet för generate_track används för att ange genereringsreferensen och garanterar inte att kandidaten endast har längden för det intervallet.

Åtgärdsflöde

Om endast lokal ersättning utförs räcker befintligt användbart källjud, och render behöver inte köras först; om källjudet redan finns i projektet kan även upload och add_track hoppas över. render_audio_id är endast en obligatorisk referens för generate_track. Vid inskickning av en asynkron åtgärd returneras först { "task_id": "...", "trace_id": "..." }, vilket inte betyder att genereringen har lyckats. Pollning:
En uppgift räknas som lyckad först när dess post har finished_at och dess response.success är true; när response.success=false ska response.error läsas. Även om save kan innehålla task_id, slutförs den synkront i detta gränssnitt. upload, render, generate_track, replace_section ändrar inte projektversionen; efter lyckad save, add_track, commit_candidate eller remove_track ska det nya version_id hämtas.

Begärandekonventioner

Följande exempel visar kopplat hur ID:n och versioner överförs mellan åtgärder. Svaren listar endast fält som är relevanta för det aktuella steget; vid integrering ska exempel-ID:n ersättas med svarsvärden från den aktuella applikationen.

Skapa och läsa projekt

Skapa projekt: create

Begäran:
Svar:

Läs projekt: retrieve

Begäran:```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” } ] } }
12–20 sekunder i begäran är referensintervallet för källjudet, och kandidatljudet är cirka 41 sekunder; start_seconds/end_seconds är inte en garanti för utdata-längd.

Använd kandidat: commit_candidate

Generering producerar endast kandidater och placerar dem inte automatiskt i projektet. commit_candidate kontrollerar att kandidaten fortfarande tillhör den aktuella versionen. Kandidater för lokal ersättning kan endast skickas automatiskt när den faktiska längden tillförlitligt kan matchas mot hela källjudet eller det valda intervallet; vid bristande matchning behålls det ursprungliga projektet och ett fel returneras, och det går inte att framtvinga sammanfogning genom att manuellt gissa taktantalet.
Godkännandesvar:
Uppgiftens slutliga status:

Exportera efter inlämning

Efter att kandidaten för det nya spåret har skickats in avvisades exporten av hela låten som innehåller kandidaten. Begäran och slutlig status:
Godkännandesvar:
Uppgiftens slutliga status:
Att kandidatens ljudlänk går att läsa betyder inte att projektet som innehåller den nödvändigtvis kan exporteras. När studio_audio_unavailable tas emot ska det ursprungliga projektet behållas och tillgängligheten för det refererade ljudet kontrolleras.

Ersätt befintligt klipp

replace_section kan direkt använda befintligt källjud utan att först exportera en mix. Generering returnerar endast kandidater; vid inlämning väljs originalspåret som innehåller det unika källklippet.

Generera ersättningskandidat: replace_section

Godkännandesvar:
Uppgiftens slutstatus:

Kandidatlängder stämmer inte överens

När en kandidat för partiell ersättning skickas in ska track_id peka på det ursprungliga spåret som innehåller det enda källsegmentet, och start_beats och end_beats ska utelämnas. Endast när kandidatens längd på ett tillförlitligt sätt kan matchas med hela källjudet eller det valda intervallet uppdaterar gränssnittet projektet. Efter att ha valt ett 8-sekundersintervall är båda kandidaterna 36 sekunder, vilket varken är lika med originaljudets 41 sekunder eller det valda intervallets 8 sekunder. När en av kandidaterna skickas in returneras:
Accepteringssvar:
Uppgiftens slutstatus:
Därför ändrades inte originalspåret. Vid detta fel bör kandidaten behållas för avlyssning och manuell hantering, och den bör inte betraktas som att den redan har fogats in i projektet framgångsrikt, och betald generering bör inte automatiskt skickas in på nytt.

Ta bort spår

remove_track kräver aktuellt version_id och state.tracks[].id; använd den nya version som returneras efter lyckad åtgärd. Nedan tas kandidatspåret bort som inte kan användas för export av hela låten, och projektets status läses tillbaka.
Svar:
Läs projektet igen:

Export efter borttagning

Efter att detta kandidatspår tagits bort finns det ursprungliga källspåret fortfarande kvar, och exporten lyckas igen med den senaste versionen:
Accepteringssvar:
Uppgiftens slutstatus:
Den framgångsrikt exporterade audio_url kan användas för nedladdning eller uppspelning. Att ljudlänken är åtkomlig bevisar inte att andra kandidater också är kvalificerade för projektexport.

Fel och återställning

Projekt och kandidater är kopplade till det program som skapade dem; använd det ursprungliga programmet för åtkomst. Spara den slutliga ljud-URL:en efter en lyckad export och behåll trace_id för felsökning.