You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Find General application. If it has not been created, choose Initialize General Application. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and current pricing.
Copy the API Key from the application card, or open Keys / Manage Keys → Create to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
When creating a key, review Expiration Time, Set Usage Limitation, and Allowed APIs. Enable only the restrictions you need, allow the operations you will call, then click Create and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
Copy only the token value, without quotation marks, spaces, or Bearer . An API Key / API Token field expects this raw value; only a manually configured HTTP Authorization header needs the Bearer prefix. A platform-... account-management token cannot replace a generation API key.
Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.
MP3 export
Use POST /suno/mp3 with the completed song's audio_id. Set async=true to receive a task ID and poll /suno/tasks; use the final returned audio_url. See the MP3 integration guide.
English integration guides, API references, and service documentation
Global-ready workflow for developers building chat, image, video, music, and search products
Audio generation and processing
For POST /suno/audios, negative_tags excludes styles or genres only when custom is true. The API currently sets no fixed character limit for this field, but overly long content may still fail to process; keep it concise.
A downloadable audio file does not guarantee that its audio_id remains available for follow-up operations such as covers, extensions or stem separation. If suno_processing_unavailable, suno_model_unavailable or suno_processing_failed is returned, retain the task_id and trace_id and contact support. See the audio generation integration guide for the documented error messages.
Audio availability check (Beta)
Before an extension or cover, optionally call POST /suno/availability with the completed song's UUID as audio_id, not its task_id. The check requires a Bearer API token, returns synchronously, and currently consumes no Credits. A successful check returns data.id and data.available: true, meaning positive evidence of availability on the current channel—not a guarantee that the next operation will succeed. If availability cannot be confirmed, 503 availability_unknown is returned instead of false; other errors are not negative availability results either. See the precheck procedure and error handling.
Custom Models (Beta)
Create a reusable music model from 6–24 authorized audio files, query its status, and generate new tracks through POST /suno/custom-models. See the custom models integration guide.
Studio Projects (Beta)
Use POST /suno/projects to manage versioned multitrack projects. The public API reference and integration guide contain the complete schema and recorded examples.
Send Authorization: Bearer YOUR_API_KEY, Content-Type: application/json, and an Idempotency-Key of 1–128 characters for every action except retrieve. Use a new key for each new operation. The same key and request replay the original success or failure without regenerating; changing the request under the same key returns 409. If submission times out, query the original task or replay with the same key before considering a new paid operation.
Project workflow
Action
Required inputs beyond action
Result and next step
create
title (1–200 characters)
Synchronous; retain data.id as the project ID.
retrieve
id
Synchronous; read the latest data.version_id and complete data.state.
save
id, complete state, latest version_id
Synchronous even if a task_id is returned; use the new version. Only the first save of an empty project may omit version_id.
upload
id, version_id, public HTTPS audio_url
Async; read response.data.candidate.audio_id from the completed task.
add_track
id, version_id, completed audio_id
Async; add the source audio and retain the new version.
render
id, version_id, title
Async; read response.data.audio_id and audio_url for the mix.
Async; submit a selected candidate and retain the new version.
remove_track
id, version_id, track_id
Synchronous; retain the new version.
For async actions, async=false does not make them synchronous. Poll POST /suno/tasks with {"action":"retrieve","id":"TASK_ID"}, or set callback_url. A task ID means accepted, not successful: wait for finished_at and check response.success; failures are in response.error. See the task result guide.
save replaces the entire state, not a partial patch. Retrieve it first, edit only the intended fields, and preserve unknown fields. Save a uniquely identified audio track with type:"audio" and clips:[] before generating a new-track candidate, because candidates are tied to that saved version. Do not create the target track after generation. Read operation_id and candidates[].id from the completed generation task, and track_id from the project's state.tracks[].id; none of these is the project ID or the new submission's task ID.
Timing and optional controls
start_seconds / end_seconds select a range in the source audio, with 0 ≤ start_seconds < end_seconds. Replacement must not extend past the source duration. The selected range does not guarantee candidate output length.
start_beats / end_beats are project timeline beats. state.timing.bps is positive beats per second, default 2. Clip fields startBeats, endBeats, and readStartBeats also use project beats. Adding 41 seconds at beat 0 gives a default end of beat 82 at 2 bps.
add_track accepts name, color (default #7251F7), title, start_beats (default 0), end_beats, and nonnegative gain (default 1). The default end is start plus audio duration times bps.
Generation and replacement accept title, tags, and negative_tags. generate_track always submits two candidates; do not send batch_size. It additionally accepts prompt, instrumental (default true), and vocal_gender (f, m, or unspecified, default unspecified). stem_control_tags is a description such as add Piano, not an enum.
For replacement, prompt supplies source lyrics or context, while replacement_lyrics supplies the new lyrics. fixed defaults to false; fixed=true requires a range shorter than 26 seconds and remains unverified in the recorded workflow.
For new-track commits, optional name, nonnegative gain (default 1), and non-overlapping start_beats / end_beats control placement. Defaults use the source clip's start and the candidate's actual duration. Replacement commits target the original track containing the unique source clip and must omit start_beats and end_beats.
Rendering accepts lyrics (default [Instrumental]), tags, and an optional beat range. Without a range it uses the earliest and latest audible clips; muted clips are excluded and solo tracks take precedence. An empty or inaudible project cannot be rendered.
The generation model enums are chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild, and chirp-v6-mini. Passing validation does not guarantee that the model supports the selected operation; check the terminal task result. There is no automatic model substitution.
Beta limitations and recovery
The recorded October 9, 2026 workflow generated and committed a new-track candidate, but rendering the project containing it failed with studio_audio_unavailable. Removing that candidate track and rendering the latest version succeeded. The same workflow produced 36-second replacement candidates for an 8-second selection in a 41-second source; committing one failed with bad_request, leaving the original track unchanged. Candidate generation, a playable URL, or a successful commit is not proof that the whole project can be rendered.
On project_version_conflict or project_candidate_stale (409), retrieve the latest project and replan; do not replay stale candidates. If a candidate duration cannot safely match the source or selected section, retain the original track and inspect the candidate rather than forcing guessed beat positions. For audio-access failures, preserve the project and check the source and trace_id. Do not automatically repeat paid generation to resolve these failures. Projects and candidates are bound to their application and execution environment; do not assume cross-application reuse or automatic failover. Use only audio you have rights to process and retain final exported audio URLs.
Integrate Suno AI music generation capabilities into your application through a stable and comprehensive REST API. Create custom songs, pure music, remixes, covers, and more—all through a unified interface.
```
Suno currently does not provide a public, self-service REST API. Its music generation features can only be accessed through the Suno official website and application.
Ace Data Cloud fills this gap by providing a stable, production-ready API, allowing you to programmatically access all of Suno's music generation features—including the latest Chirp v5 model—through a simple REST interface, equipped with OpenAPI specifications, Webhook support, streaming, and pay-as-you-go pricing.
All Features of the Suno API
A comprehensive API suite covering the complete workflow of Suno music generation
🎵
Complete Music Generation
Generate complete songs with lyrics, vocals, and instruments from text prompts, or create pure instrumental music. Supports inspiration mode and custom mode, providing fine control.
🔄
16 Actions, One API
Generate, Extend, Cover, Blend, Stems, Remaster, Underpaint, Overpaint, Replace Section, etc.—all accomplished through the /suno/audios endpoint.
🎤
Custom Persona
Create and save custom singer voice styles through the Persona API. Reuse a consistent vocal identity across unlimited song generations.
📝
AI Lyrics Generation
Automatically generate structured lyrics with paragraph markers (verse, chorus, bridge). The required model parameter accepts default or remi-v1. Also supports mashup lyrics, blending the lyrics of two songs.
🔀
Multi-format Output
Supports output in MP3 (default), MP4 (with visualized video), WAV (lossless audio), and MIDI (music notation) formats. Vocal separation can extract vocals, drums, bass, etc.
⚡
Streaming and Webhook
Supports NDJSON real-time streaming for progress updates, or set a callback_url to asynchronously receive results. No polling required.
Example URL note: Media hosts in historical response snapshots are normalized to media.example.com for publication; they show response structure and are not downloadable assets. Terminal audio and WAV results preferentially use Ace Data Cloud CDN URLs, while intermediate preview URLs are not persisted.
cURL
curl -X POST https://api.acedata.cloud/suno/audios \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "generate",
"prompt": "A cheerful pop song about a summer road trip",
"model": "chirp-v6",
"custom": false,
"callback_url": "https://your-app.com/webhook"
}'
