GET /jobs/{job_id}

The GET /jobs/{job_id} endpoint returns the current state of a music generation job. Poll this endpoint after calling POST /generate to determine when your song is ready. While the job is running, the result field is null. When the job completes, result contains the audio URL, cover artwork, BPM, duration, and descriptive tags. Base URL: https://whisul.com/api

Request

GET /jobs/{job_id}

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

Authorization: Bearer <your_api_key>

Path parameters

string

required

The UUID of the generation job returned by POST /compose. Example: 81fa5ff7-6197-4c24-8062-c0ff8b62d58d.

Example request

curl --request GET \
  --url https://whisul.com/api/jobs/81fa5ff7-6197-4c24-8062-c0ff8b62d58d \
  --header 'Authorization: Bearer <your_api_key>'

Response

200 OK

Returned for both running and completed jobs.

Job is running

When the job is still being processed, result is null and finished_at is not present.

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

Job is completed

When generation finishes, status becomes "completed" and the result object is populated.

{
  "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"
}

Response fields

string

The current state of the job. One of running, completed, or failed. See the job status lifecycle for details.

string

The original prompt string submitted with POST /compose.

object

null while the job is running or if the job failed. Populated when status is "completed".

Show result properties

string

The AI-generated title for the song.

number

The tempo of the generated song in beats per minute.

string

The length of the song in m:ss format — for example, "2:47".

string

A URL to the generated audio file.

string

A URL to the AI-generated cover artwork for the song.

string

A comma-separated string of descriptive tags characterizing the song’s style, genre, and instrumentation.

string | null

null for running and completed jobs. May contain an error message when status is "failed".

string

The timestamp when the job began processing, in YYYY-MM-DD HH:MM:SS format (UTC).

string

The timestamp when the job finished, in YYYY-MM-DD HH:MM:SS format (UTC). Only present when status is "completed" or "failed".

Error codes

Status	Meaning	What to do
`200 OK`	The request succeeded. The job may be running or completed — check the `status` field.	Read the `status` field to determine next steps.
`404 Not Found`	No job exists with the provided `job_id`.	Confirm you are using the correct `job_id` returned by `POST /compose`.
`500 Internal Server Error`	An unexpected server-side error occurred.	Wait briefly and retry. If the issue persists, contact Whisul support.

Endpoints

Reference

Request

Authentication

Path parameters

Example request

Response

200 OK

Job is running

Job is completed

Response fields

Error codes

​Request

​Authentication

​Path parameters

​Example request

​Response

​200 OK

​Job is running

​Job is completed

​Response fields

​Error codes

Request

Authentication

Path parameters

Example request

Response

200 OK

Job is running

Job is completed

Response fields

Error codes