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 createCopy Anchor Link

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 taskCopy Anchor Link

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 audioCopy Anchor Link

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 ShapeCopy Anchor Link

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 stateCopy Anchor Link

• 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 recordsCopy Anchor Link

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 ErrorsCopy Anchor Link

API ReferenceCopy Anchor Link