TokenLab

Music

Get Music Status

Retrieves the status and result of a music generation task

GET
/v1/tasks/{id}

GET /v1/music/generations/{id} is a compatibility endpoint. It remains supported for existing integrations. New integrations poll GET /v1/tasks/{id}; see Get Task Status.

Call GET /v1/tasks/{id} to check the status of your music generation task.

id and task_id identify the same task.

An expired or unavailable public task can return 404 async_task_not_found. If task ownership cannot be established for the current API key, the response is 403 task_not_owned.

Path Parameters

idstringpathrequired

The music generation task ID.

Response

idstring

Task ID.

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, failed, or timeout. A failed task still returns HTTP 200.

progressinteger

Optional progress value. Returned only when a real progress value is available; use status to determine completion.

Result fields depend on the operation. Music may return audio_url and audio_id; lyrics-only tasks return lyrics; separation can return multiple files in data. video_url, title, progress, and other metadata are optional. Check status for completion and read the fields actually returned.

audio_idstring

Optional source audio ID, usable with this task's ID in supported follow-up operations.

dataarray

Optional output array, including separated audio files with audio_url or url.

audio_urlstring

URL to download the audio file (when completed). A TokenLab media-result link that stays valid for 30 days.

video_urlstring

URL to the video version with visualizer (when completed and returned for the model).

image_urlstring

Cover image URL, when the model returns one.

titlestring

Generated song title.

lyricsstring

Generated or provided lyrics.

errorstring | object

Error message (when failed).

error_detailsobject

Failure details when the task failed: status, message, type, code, retryable, and param when a request field is at fault.

media_retentionobject

Saving status of the result links: days and items[] with url, kind, status, and expires_at. It can be absent; the links still work. See Data retention.

Request

curl --fail-with-body "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Response

Response (Completed)
{
  "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=…",
  "title": "Night Drive",
  "lyrics": "[Verse 1]\nDriving through the night...",
  "audio_id": "audio_abc123",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
        "kind": "audio",
        "content_type": "audio/mpeg",
        "status": "saved",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

Authorization

BearerAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

The async task ID returned by id / task_id, or embedded in poll_url

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json