> ## 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.

# Generate Music

> Submit your first music generation request and retrieve a playable audio URL from the Whisul API by following this four-step guide.

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`.

<Steps>
  <Step title="Sign up and get your API key">
    Go to [whisul.com](https://whisul.com/app/login/) 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](/authentication) for details on how to use it securely.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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"}'
      ```
    </CodeGroup>

    A successful request returns HTTP `202` and a response like this:

    ```json theme={null}
    {
      "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.

    <Info>
      The `poll_url` field contains the exact path you need to call in the next step.
    </Info>
  </Step>

  <Step title="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"`.

    <CodeGroup>
      ```bash curl theme={null}
      curl --request GET \
        --url https://whisul.com/api/jobs/81fa5ff7-6197-4c24-8062-c0ff8b62d58d \
        --header 'Authorization: Bearer YOUR_API_KEY'
      ```
    </CodeGroup>

    While the job is still processing, the response looks like this:

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "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"
    }
    ```

    <Note>
      If `status` is `"failed"`, check the `error` field for details. You can submit a new request with the same or a revised prompt.
    </Note>
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>