POST /generate

The POST /generate endpoint accepts a text prompt describing the music you want and enqueues a generation job. Because music generation is asynchronous, the response does not include the finished song — it returns a job_id and a poll_url you use to check progress. When the job completes, the result contains a song_url, cover art, BPM, duration, and descriptive tags. Base URL: https://whisul.com/api

Request

POST /generate

Authentication

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

Authorization: Bearer <your_api_key>

Request body

Send a JSON body with the following field:

string

required

A plain-language description of the song you want to generate. Describe the genre, mood, instruments, tempo, or any other characteristics — for example, "an upbeat trap beat with 808s and a dark synth melody".

Example request

curl --request POST \
  --url https://whisul.com/api/generate \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"prompt": "an upbeat trap beat with 808s and a dark synth melody"}'

Response

202 Accepted

The request was accepted and the generation job is queued. The response body contains the job identifier and a polling URL.

{
  "message": "Composition task received.",
  "job_id": "81fa5ff7-6197-4c24-8062-c0ff8b62d58d",
  "poll_url": "/jobs/81fa5ff7-6197-4c24-8062-c0ff8b62d58d"
}

string

A human-readable confirmation that the task was received.

string

The unique identifier for this generation job. Store this value — you need it to poll for status and retrieve the result.

string

The relative path to the job status endpoint for this job. Append this to the base URL to construct the full polling URL: https://whisul.com/api + poll_url.

Error codes

Status	Meaning	What to do
`400 Bad Request`	The request body is missing or invalid — for example, the `prompt` field is absent or empty.	Check your request body and ensure `prompt` is a non-empty string.
`401 Unauthorized`	The `Authorization` header is missing or the API key is invalid.	Verify your API key and confirm the header is formatted as `Bearer <your_api_key>`.
`429 Too Many Requests`	You have exceeded your rate limit.	Wait before retrying. See the error codes reference for retry guidance.

After you receive a job_id, use GET /jobs/{job_id} to poll for the result. See the polling guide for recommended polling intervals and best practices.

Endpoints

Reference

Request

Authentication

Request body

Example request

Response

202 Accepted

Error codes

​Request

​Authentication

​Request body

​Example request

​Response

​202 Accepted

​Error codes

Request

Authentication

Request body

Example request

Response

202 Accepted

Error codes