Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.whisul.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
​
prompt
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"
}
​
message
string
A human-readable confirmation that the task was received.
​
job_id
string
The unique identifier for this generation job. Store this value — you need it to poll for status and retrieve the result.
​
poll_url
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

StatusMeaningWhat to do
400 Bad RequestThe 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 UnauthorizedThe 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 RequestsYou 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.