TokenLab

Music

Create Music

Creates a music, lyrics, or sound generation task

POST
/v1/music/generations

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

modelstringdefault: suno-music

Music 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.

promptstring

Music description or replacement text. Required for music, lyrics, upload-cover, upload-extend, and replace-section; optional for add-instrumental and stem separation.

titlestring

Title for the generated song.

tagsstring

Style tags (e.g., "pop, upbeat, electronic").

negative_tagsstring

Styles to avoid. Required when audio_operation is add-instrumental.

actionstring

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.

mvstring

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.

make_instrumentalboolean

Set to true to generate instrumental output without vocals.

audio_urlstring

Publicly reachable reference or uploaded audio URL. When provided without audio_operation, TokenLab uses the upload-cover flow.

audio_operationstring

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.

task_idstring

Source task ID belonging to your organization, for generated-audio replacement or stem separation.

audio_idstring

Source audio ID returned in the source task result. Required with task_id for generated-audio replacement and stem separation.

infill_start_snumber

Replacement start time in seconds, at least 0. Required for replace-section.

infill_end_snumber

Replacement end time in seconds. Required for replace-section; it must be 6–60 seconds after infill_start_s.

full_lyricsstring

Full lyrics for the resulting song. Required for replace-section.

stem_namestring

Stem name. Required for advanced-split.

continue_clip_idstring

ID of a previous clip to continue from.

continue_atnumber

Time in seconds from which to continue. Required and greater than 0 for upload-extend.

durationinteger

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.

output_formatstring

Audio file format listed by the model, for example mp3, wav, or flac. Only for models that list it.

seedinteger

Seed for repeatable output, 0 to 4294967294. Only for models that list it.

stepsinteger

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.

cfg_scalenumber

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

idstring

Task ID for polling status.

task_idstring

Alias of the same asynchronous task ID, when returned.

poll_urlstring

Status URL for this task. Poll GET /v1/tasks/{id} with id.

statusstring

Task status: pending, processing, completed, or failed.

createdinteger

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

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json