action i begäran avgör åtgärdstypen. Projektets primärnyckel använder konsekvent id; version_id representerar den aktuella projektversionen, och alla ändrings- och exportåtgärder måste skicka in den senaste versionen för att undvika samtidiga överskrivningar.
Översikt över åtgärder
Asynkrona åtgärder returnerar omedelbart
task_id. Använd det kostnadsfria gränssnittet /suno/tasks för polling, eller skicka callback_url för att ta emot resultat i slutstatus.
Skapa och läsa
Idempotency-Key Header. Efter att skapandet lyckats är data.id i svaret projekt-ID:t. Ett nytt tomt projekt kan sakna version_id före den första sparningen.
state. Ett nytt tomt projekt returnerar {"tracks":[],"timing":{"bps":2}}, vilket kan användas direkt för den första sparningen. timing.bps anger slag per sekund, standardvärdet är 2 (120 BPM), och måste vara positivt; klippets startBeats, endBeats och readStartBeats använder projektets slagenheter, och du kan inte direkt använda taktpositioner i ljudanalysen som tidslinjekoordinater.
Spara fullständigt tillstånd
version_id; efter att den första sparningen har skapat en version måste efterföljande sparningar skicka in det senaste värdet. Om versionen redan har ändrats returnerar gränssnittet HTTP 409. Kör då retrieve igen, slå samman ändringarna och skicka sedan med en ny idempotensnyckel; försök inte blint igen med den gamla begäran.
Ladda upp och lägga till spår
response.data.candidate.audio_id. Lägg sedan till det i projektet:
timing.bps. Efter varje save, add_track, commit_candidate eller remove_track bör du använda det nya version_id i svaret.
Generering och ersättning
generate_track genererar spårkandidater för ett projektintervall; replace_section returnerar två kandidater för lokal ersättning. Inget av de två åtgärderna väljer automatiskt det konstnärliga resultatet. Modellen måste använda offentliga namn: chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild eller chirp-v6-mini; tillgängligheten för den specifika åtgärden beror fortfarande på uppgiftens slutstatus, och namn som inte stöds returnerar 400 före inskickning. Ingen annan modell används automatiskt i stället.
generate_track måste dessutom tillhandahålla render_audio_id (färdigt exporterat projektljud), stem_control_tags och källjudets source_audio_id. batch_size är 1–4, med standardvärdet 2; start_seconds och end_seconds är sekunder i källjudet. Ersättningsintervallet för fixed=true måste vara kortare än 26 sekunder.
Skicka in efter att ha valt kandidat:
start_beats eller end_beats. Kandidater för nya spår bör skickas till ett tomt spår som sparats i förväg, använder som standard källklippets startpunkt eller skickar uttryckligen in ett intervall utan överlappning; överlappande befintliga klipp på samma spår returnerar 400. Generera inte först och skapa sedan ett nytt spår, eftersom versionsändringen då gör kandidaten föråldrad.
Exportera fullständig låt
start_beats och end_beats utelämnas exporteras som standard från den tidigaste startpunkten till den senaste slutpunkten av alla hörbara klipp; tysta spår/klipp inkluderas inte, och när solo-spår finns väljs endast solo-spåren. Ett tomt projekt eller inga giltiga hörbara spår returnerar 400. Resultatet i slutstatus innehåller render_id, audio_id, audio_url och längd. Projektet är bundet till exekveringsmiljön vid skapandet och kan inte migreras mellan miljöer eller automatiskt växla vid fel.
Du får endast ladda upp eller bearbeta ljud som du har laglig användningsrätt till. Project API är för närvarande i Beta; spara den slutliga ljud-URL:en i viktiga resultat permanent.
Polling och felåterställning
/suno/tasks. Projects-uppgifter anses lyckade när finished_at finns och response.success=true; response.success=false betyder misslyckande. Att skicka in returnerar HTTP 200 eller task_id betyder endast att den har tagits emot, inte att ljudet är färdigt.
Samma Idempotency-Key med samma begäran läser tillbaka det ursprungliga resultatet (inklusive misslyckanden) och genererar inte automatiskt på nytt eller debiterar dubbelt. För att uttryckligen försöka igen med en misslyckad operation, fråga först den ursprungliga uppgiften för att bekräfta misslyckandet och använd sedan en ny nyckel; skicka inte in igen medan den ursprungliga uppgiften fortfarande behandlas eller resultatet är osäkert.
Felklassificeringar omfattar studio_unavailable / studio_model_unavailable (503, kan tillfälligt inte bearbetas eller modellen är otillgänglig), studio_model_unsupported (400, modellen stöder inte operationen), studio_state_invalid (400, projektstatusen eller exportomfånget är ogiltigt), too_many_requests (429), studio_audio_unavailable (403, refererat ljud kan inte användas för projektexport) och content_rejected (403). Behåll trace_id för felsökning.