Status Lifecycle

Every music generation job moves through a defined set of status values. Understanding the lifecycle lets you write polling logic that reacts correctly to each state and extracts the right fields when a job finishes. This page describes each status, specifies which fields are available at each stage, and provides a complete reference for the result object returned when generation completes.

running
completed
failed

The job has been accepted and generation is in progress. The Whisul backend is actively processing your prompt.What to expect:

status is "running"
result is null
error is null
finished_at is not present
started_at is populated

What to do: Continue polling GET /jobs/{job_id} at a reasonable interval until status changes. See the polling guide for recommended intervals.

{
  "status": "running",
  "prompt": "a trap song",
  "result": null,
  "error": null,
  "started_at": "2026-02-17 15:39:34"
}

Generation succeeded. The song, cover art, and metadata are ready.What to expect:

status is "completed"
result is a populated object containing the song URL, cover art URL, BPM, duration, title, and tags
error is null
Both started_at and finished_at are present

What to do: Read the fields from the result object. Use song_url to access the audio file and image_url to access the cover artwork.

{
  "status": "completed",
  "prompt": "a trap song",
  "result": {
    "title": "Midnight Grid",
    "bpm": 140,
    "duration": "2:47",
    "song_url": "https://cdn.whisul.com/audio/81fa5ff7.mp3",
    "image_url": "https://cdn.whisul.com/covers/81fa5ff7.jpg",
    "tags": "trap, dark, 808s, synth, bass"
  },
  "error": null,
  "started_at": "2026-02-17 15:39:34",
  "finished_at": "2026-02-17 15:41:58"
}

Generation did not complete successfully. The job terminated with an error.What to expect:

status is "failed"
result is null
error may contain a message describing what went wrong
Both started_at and finished_at are present

What to do: Check the error field for details. You can submit a new job with POST /compose. If failures persist for the same prompt, try rephrasing it or contact Whisul support.

Timestamp fields

Both endpoints return timing information for the job.

Field	Type	When present	Description
`started_at`	string	Always	The time the job began processing. Format: `YYYY-MM-DD HH:MM:SS` (UTC).
`finished_at`	string	`completed` or `failed` only	The time the job finished. Not present while the job is `running`.

Result object fields

The result object is only present when status is "completed". For all other statuses, result is null.

Field	Type	Description
`title`	string	The AI-generated title for the song.
`bpm`	number	The tempo of the generated track in beats per minute.
`duration`	string	The length of the song in `m:ss` format — for example, `"2:47"`.
`song_url`	string	A URL to the generated audio file.
`image_url`	string	A URL to the AI-generated cover artwork for the song.
`tags`	string	A comma-separated string of descriptive tags characterizing the song’s style, genre, and instrumentation — for example, `"trap, dark, 808s, synth, bass"`.

result fields are only guaranteed to be populated when status is "completed". Do not attempt to read result fields before confirming the status value.

Endpoints

Reference

Status Lifecycle