Media Guides
Music generation
Create songs or lyrics and wait for the finished audio
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://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}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. The media URLs are TokenLab URLs that stay valid for 30 days; download or save a result that you need for longer.
Show the right state
- Show a pending state immediately after task creation.
- Poll every
5-10sfor long tasks, then stop oncompletedorfailed. - Do not display a final player until the task is
completedand anaudio_urlexists. - 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_idinstead 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 |