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.

This guide walks you through the full Whisul workflow: signing up, submitting a text prompt to generate a song, polling for the result, and accessing your audio file and cover art. By the end, you will have made two API calls and received a working song_url.
1

Sign up and get your API key

Go to whisul.com and create an account. Once you are logged in, open your dashboard and copy your API key.You will include this key in every request as a Bearer token. See Authentication for details on how to use it securely.
2

Submit a composition request

Send a POST request to /generate with your text prompt in the request body. The API accepts the prompt and immediately returns a job_id — music generation happens asynchronously in the background.
curl --request POST \
  --url https://whisul.com/api/generate \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"prompt": "a trap song with heavy 808s and a dark, cinematic feel"}'
A successful request returns HTTP 202 and a response like this:
{
  "message": "Composition task received.",
  "job_id": "81fa5ff7-6197-4c24-8062-c0ff8b62d58d",
  "poll_url": "/jobs/81fa5ff7-6197-4c24-8062-c0ff8b62d58d"
}
Save the job_id — you will use it in the next step to check whether your song is ready.
The poll_url field contains the exact path you need to call in the next step.
3

Poll for your result

Send a GET request to /jobs/{job_id} using the job_id from the previous step. Repeat this request every few seconds until status changes from "running" to "completed".
curl --request GET \
  --url https://whisul.com/api/jobs/81fa5ff7-6197-4c24-8062-c0ff8b62d58d \
  --header 'Authorization: Bearer YOUR_API_KEY'
While the job is still processing, the response looks like this:
{
  "status": "running",
  "prompt": "a reggaeton song with heavy 808s and a dark, cinematic feel",
  "result": null,
  "error": null,
  "started_at": "2026-02-17 15:39:34"
}
Once generation finishes, status becomes "completed" and the result object is populated:
{
  "status": "completed",
  "prompt": "a afrobets song with heavy 808s and a dark, cinematic feel",
  "result": {
    "title": "Shadow Pulse",
    "bpm": 140,
    "duration": 187,
    "song_url": "https://cdn.whisul.com/songs/81fa5ff7.mp3",
    "image_url": "https://cdn.whisul.com/covers/81fa5ff7.jpg",
    "tags": "trap, dark, cinematic, 808s"
  },
  "error": null,
  "started_at": "2026-02-17 15:39:34",
  "finished_at": "2026-02-17 15:40:51"
}
If status is "failed", check the error field for details. You can submit a new request with the same or a revised prompt.
4

Use your song and cover art

Once the job is complete, you can use the URLs directly from the result object:
  • song_url — link to the generated audio file. Use this to play or download the track.
  • image_url — link to the generated cover art. Use this alongside the track in your project.
You also have access to title, bpm, duration, and tags to display metadata or filter tracks in your application.
Store the job_id and result fields in your own database if you need to retrieve them later — Whisul does not guarantee indefinite storage of generated assets.