Music
Create Music
Creates a music, lyrics, or sound generation task
Use GET /v1/models?recommended_for=music to get current music models.
Generate music, lyrics, and sound with AI. This is an asynchronous API. Create responses return a task identity. Poll GET /v1/tasks/{id} with it for status.
Models differ in the fields they accept. Check GET /v1/models/{model} before sending optional fields; a field the model does not list can return 400 unsupported_parameter. The Suno fields (mv, title, tags, negative_tags, audio_operation, and the fields that go with them) apply to Suno models. user is not supported and returns 400.
Request Body
suno-musicMusic model ID, such as suno-music or stable-audio-3. Send it explicitly. For lyrics only, choose a model whose current public operations include lyrics.
Music description or replacement text. Required for music, lyrics, upload-cover, upload-extend, and replace-section; optional for add-instrumental and stem separation.
Title for the generated song.
Style tags (e.g., "pop, upbeat, electronic").
Styles to avoid. Required when audio_operation is add-instrumental.
Optional MUSIC or LYRICS value. Choose a model that supports the corresponding public operation; this field does not add lyrics support to a music-only model.
Suno version selector. Required for generation, upload-cover, upload-extend, add-instrumental, and replacement from audio_url. Omit it for lyrics, replacement from task_id + audio_id, and stem separation. Accepted values: chirp-v6, chirp-v6-mini, chirp-v6-wild.
Set to true to generate instrumental output without vocals.
Publicly reachable reference or uploaded audio URL. When provided without audio_operation, TokenLab uses the upload-cover flow.
Audio operation: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.
vocal-separate, multi-stem-separation, and advanced-split require task_id + audio_id; advanced-split also requires stem_name. upload-extend requires continue_at greater than 0. add-instrumental requires audio_url, title, tags, and negative_tags.
For replace-section, send prompt, tags, title, infill_start_s, infill_end_s, and full_lyrics. Choose exactly one source: task_id + audio_id, or audio_url + mv. The replacement interval must be 6–60 seconds.
Source task ID belonging to your organization, for generated-audio replacement or stem separation.
Source audio ID returned in the source task result. Required with task_id for generated-audio replacement and stem separation.
Replacement start time in seconds, at least 0. Required for replace-section.
Replacement end time in seconds. Required for replace-section; it must be 6–60 seconds after infill_start_s.
Full lyrics for the resulting song. Required for replace-section.
Stem name. Required for advanced-split.
ID of a previous clip to continue from.
Time in seconds from which to continue. Required and greater than 0 for upload-extend.
Length of the generated audio in seconds, 1 to 380. Only for models that list it, such as stable-audio-3; the model's details give its own limit.
Audio file format listed by the model, for example mp3, wav, or flac. Only for models that list it.
Seed for repeatable output, 0 to 4294967294. Only for models that list it.
Number of generation steps. The range depends on the model (for example 4 to 8 for stable-audio-3). Only for models that list it.
Some models list more fields, such as negative_prompt, n, seconds, and guidance_scale. Send them only when the model's details list them; a field that the selected model does not take returns 400.
Prompt guidance strength, 1 to 25. Only for models that list it.
prompt accepts up to 5000 characters; tags and negative_tags accept up to 1000 characters each. Supported operations and parameters depend on the selected model's current details.
Response
Task ID for polling status.
Alias of the same asynchronous task ID, when returned.
Status URL for this task. Poll GET /v1/tasks/{id} with id.
Task status: pending, processing, completed, or failed.
Task creation time as a Unix timestamp, when returned.
Request
curl -X POST "https://api.tokenlab.sh/v1/music/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-music",
"mv": "chirp-v6",
"prompt": "An upbeat electronic dance track with heavy bass",
"title": "Night Drive",
"tags": "electronic, EDM, energetic"
}'Sound-generation example for a model that takes duration and output_format instead of the Suno fields:
{
"model": "stable-audio-3",
"prompt": "Warm lo-fi beat with soft vinyl crackle",
"duration": 30,
"output_format": "mp3"
}Response
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "suno-music"
}Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.
Value in
- "auto"
- "verified"
- "official"
Optional key that makes a create request safe to retry. Send a new unique value, such as a UUID, for each task. A retry with the same key and the same body returns the result of the original create request, usually the original task, and does not create, dispatch, or charge a second task. A different body with a key that was already accepted is rejected with 409. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json
application/json