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.
Status lifecycle
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 nullerror is nullfinished_at is not presentstarted_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 tagserror 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 nullerror 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.
