The hardest part of reading an API reference is usually not authentication. It is knowing which endpoint belongs to the job you have now: starting a song, checking a task, retrieving a file, editing an existing track, or working with a voice. This page is the map; the detailed parameters remain in the individual docs pages.
Short answer: the four-step core workflow
- Create an API key and send it as
Authorization: Bearer YOUR_API_KEY. - Call
POST /api/music/createorPOST /api/music/create/custom. - Poll
POST /api/music/queryuntil the response says the song is completed. - Request the final media URL and download MP3 or WAV.
Read-only calls such as task queries and downloads are not charged separately. A normal generation costs 0.6 CNY and returns two tracks.
Find the docs page by task
| What you need | Start here | Typical path |
|---|---|---|
| First request | Quick Start | Key → create → query → download |
| Key and headers | Authentication | Authorization: Bearer … |
| Model names | Models | suno-v6, suno-v6-wild, suno-v6-mini |
| Idea-to-song | Simple generation | /api/music/create |
| Lyrics-style-title control | Custom generation | /api/music/create/custom |
| Task status and history | Query API | /api/music/query, /api/music/songs |
| Media files | Media download | MP3, WAV, video, cover, MIDI |
| Vocals and backing split | Separation API | two-stem or twelve-stem |
| Voice profile | Voice profile API | create voice → cover |
| Commercial license | Authorization API | bind identity → certificate |
What the status fields mean
A successful submit response is not the finished song. Treat pending, submitted and processing as in progress. Only completed should be handed to a player or download step. If an audio field is empty while the task is still processing, that is expected rather than a failed generation.
Which document path is the right one?
This site keeps two useful views of the documentation. The documentation hub is the index; the API overview is the compact list of current endpoints and billing. Use the overview when you already know the capability name. Use the task table above when you know only the product outcome you need.
Before you build the integration
- Keep the API key on your server rather than in browser code.
- Save the real
song_idand your own request ID. - Set a client timeout long enough for generation; do not retry immediately after a timeout.
- Poll at a sensible interval rather than in a tight loop.
- Store the final MP3 or WAV in your own storage instead of treating a temporary media URL as permanent.
Start with one endpoint, then expand
Build the create-query-download path first and confirm it with your own error handling. Add stems, covers, voice or Studio operations only after that baseline is stable. The first-song integration guide provides a complete request example, while pricing explains which calls consume balance.
¥0.6 per generation, 2 tracks, unlimited downloads
Runs on the Suno V6 engine. Download MP3 or WAV as often as you like. Signing up needs an email address, not a phone number.
