Music Generation - TokenLab

Music generation is asynchronous. POST /v1/music/generations creates a public TokenLab task and returns id / task_id, status, and usually poll_url. Your application should store that task identity, show progress, and poll until a terminal status.

Choose The Workflow

Workflow	Key fields	Notes
Full song or instrumental	`model`, `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`	Store the previous public clip/task identity before offering continuation

Query the current model catalog before shipping a hard-coded model list:

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

The current public examples use suno_music for music generation. For lyric-only flows, send action: "LYRICS" with a model whose public contract documents lyric generation. Treat model IDs as public TokenLab IDs, not as a guarantee that provider-specific fields are public contract fields.

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

Keep prompts, titles, and tags user-visible and safe to store. Do not place API keys, private URLs, or internal routing information in any prompt field.

Poll For Completion

Use poll_url first. If your client needs a fixed route, 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"

Expected public statuses are pending, processing, completed, and failed. A completed music task can include audio_url, video_url, title, lyrics, and normalized metadata. Store final URLs in your own database so the user can reopen the result without restarting generation.

UI And State Handling

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 And Reconciliation

Music tasks can reserve an estimated amount at create time and settle after the terminal status is known. Store request_id, task_id, model, endpoint, and billing_transaction_id when it appears. Use Management API usage records for reconciliation instead of provider task IDs.

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	Field is not in the model public contract	Remove provider-specific fields or choose a model that documents them

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

​Choose The Workflow

​Create A Music Task

​Poll For Completion

​UI And State Handling

​Billing And Reconciliation

​Common Errors

​API Reference