Music generation

Music generation is asynchronous. POST /v1/music/generations returns a task ID, status, and usually poll_url. Use that URL until the task is completed or failed.

Choose what to create

What to create	Key fields	Notes
Full song or instrumental	`model`, `mv`, `prompt`, optional `title`, `tags`, `action: "MUSIC"`	Use when the user expects final audio
Lyrics only	`model`, `prompt`, `action: "LYRICS"`	Use only with models that expose lyric generation
Continue an existing clip	`continue_clip_id`, optional `continue_at`	Keep the earlier clip ID

Get the current music-model list from:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

The example below uses suno_music with mv: "chirp-v4". For lyrics only, choose a model that documents lyric generation, send action: "LYRICS", and omit mv.

Create a music task

curl 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-v4",
    "prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
    "title": "Morning Static",
    "tags": "synth-pop, upbeat",
    "action": "MUSIC"
  }'

Prompts, titles, and tags may appear in your product history. Never place API keys, private URLs, or diagnostic data in them.

Get the finished audio

Use poll_url. If your client needs a fixed URL, call GET /v1/tasks/{id} with the returned id or task_id.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Response Shape

The create response is a task record, not the final audio:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

A completed polling response can include the final media fields:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

Final media fields are absent until status is completed. Failed tasks return status: "failed" with error. Statuses are pending, processing, completed, and failed. A completed task can include audio_url, video_url, title, lyrics, and other metadata. Store the final URLs so users can reopen the result without generating it again.

Show the right state

Show a pending state immediately after task creation.
Poll every 5-10s for long tasks, then stop on completed or failed.
Do not display a final player until the task is completed and an audio_url exists.
For lyric-only tasks, render text output separately from audio tasks so users understand what they are buying.
On refresh, resume from the stored task_id instead of creating a new task.

Billing records

Music tasks can reserve an estimated amount when created. The final amount is recorded after completion or failure. Save request_id, task_id, model, endpoint, and billing_transaction_id when it appears; use Management API usage records for the final charge.

Common Errors

Symptom	Likely cause	Fix
Task created but no player	Task is still pending or completed without `audio_url`	Keep polling until terminal, then handle missing output as a failed user job
Duplicate songs after refresh	UI recreated the task instead of resuming	Persist and reuse `task_id`
Lyric task returns no audio	`action: "LYRICS"` is text-only	Separate lyrics and music UI paths
Unsupported parameter	The selected model does not accept the field	Remove it or choose a model that documents it

API Reference

Topic	Reference
Create Music	Create Music
Get Music Status	Get Music Status
Get Task Status	Get Task Status
List Models	List Models
Billing & Pricing	Billing & Pricing

Getting Started

Core Guides

Media Guides

Choose what to create

Create a music task

Get the finished audio

Response Shape

Show the right state

Billing records

Common Errors

API Reference

​Choose what to create

​Create a music task

​Get the finished audio

​Response Shape

​Show the right state

​Billing records

​Common Errors

​API Reference

Choose what to create

Create a music task

Get the finished audio

Response Shape

Show the right state

Billing records

Common Errors

API Reference