Beta Suno Studio Projects API
POSThttps://api.fesilent.com/suno/projects
Create, edit, and render versioned multitrack music projects.
Request Headers
Idempotency-Keystring
Except for retrieve, all operations must be provided. The same key and the same request return the original result; different requests return 409.
authorizationstring
Bearer token
Request Body
actionstringRequired parameter
Please select
Response
Success200
Request successful. The asynchronous operation immediately returns the task ID.
Response Body
dataobject
Engineering data for a successful response. When an asynchronous operation is submitted, `task_id` is returned first, and the final result is in `response.data` of `/suno/tasks`.
idstring
Project ID, used as the id for subsequent requests.
stateobject
Fully editable project state. After modification, submit the entire project to save; clip positions in tracks use project beat units.
object <string, unknown>
titlestring
Current project title.
archivedboolean
Whether the project has been archived.
created_atstring
Project creation time.
updated_atstring
Project last updated time.
version_idstring
Current project version ID; use a new value after each modification. A newly created empty project may not have this field before its first save.
removed_track_idstring
The ID of the track that was just deleted.
committed_candidate_idstring
Candidate audio IDs just submitted to the project.
elapsednumber
Current synchronization request duration, in seconds.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
task_idstring
Asynchronous task ID, used for the retrieve request of `/suno/tasks`; submission acceptance does not mean the task is successful.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
started_atnumber
Request start time, Unix seconds.
finished_atnumber
Requested completion time, in Unix seconds. The terminal time of asynchronous operations shall be based on the task record in /suno/tasks.
Example
{
"data": {
"id": "af0e104a-2a4c-40e0-9c70-7614566824a6",
"state": {
"timing": {
"bps": 2
},
"tracks": []
},
"title": "Suno Projects Documentation Verification 2026-10-09",
"archived": false,
"created_at": "2026-10-09T15:06:20.939Z",
"updated_at": "2026-10-09T15:07:29.623Z",
"version_id": "8f0c62fb-304f-420e-9707-426e8b64b5e3"
},
"elapsed": 0.704,
"success": true,
"task_id": "ab172b47-4d89-404b-a10e-71f67c36ccba",
"trace_id": "fc7b2e43-7a7a-4276-8671-27008a1153ea",
"started_at": 1791558449.419,
"finished_at": 1791558450.123
}Success200
Request successful. The asynchronous operation immediately returns the task ID.
Response Body
task_idstring
Asynchronous task ID, used for the retrieve request of `/suno/tasks`; submission acceptance does not mean the task is successful.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
idempotent_replayboolean
Whether to read back the original request result through the same Idempotency-Key; it will not be regenerated.
Example
{
"task_id": "adc559fa-4a87-4a53-9336-28d4302a151b",
"trace_id": "165fde93-f34b-4b0b-a7cd-0fba7d7ac154"
}Failure400
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure401
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure403
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure404
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure409
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure413
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure429
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure500
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure503
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Failure504
Request failed.
Response Body
errorobject
Failure information, including code and message.
codestring
Error codes can be used to distinguish issues with parameters, versions, rate limiting, content, and audio availability.
messagestring
Error description for easier troubleshooting.
successboolean
Whether the operation was successful; asynchronous tasks must also query the final state response.success of /suno/tasks.
trace_idstring
Request tracking ID, provide it when troubleshooting issues.
Integration guide
Shell
Python
JavaScript
Java
Go
PHP
Kind reminder: For streaming requests, the above code may not be fully applicable. Please refer to the integration documentation for changes.
Suno Music Generation
Allow Use General Balance
When 'Allow General Balance' is enabled, the general balance is used automatically if an app's balance is insufficient.