api-spec.md

Beatoven.ai Track Composition API

Base URL: https://public-api.beatoven.ai

Authentication

Beatoven.ai API uses an API token based authentication (using Bearer authentication method). With each request, you need to include your API token as a bearer token in the Authorization request header. For example, if your API token is qIN5iSz0CrGcFi0Ic8pGH3k9_iq6BSpC, then include the following header in each API request -

Authorization: Bearer qIN5iSz0CrGcFi0Ic8pGH3k9_iq6BSpC

Other headers

All POST endpoints accept a json body, so please include content-type: application/json in your requests.

You can find our older/ soon to be deprecated API spec here.

Composing a track

You can use the compose API with prompt to compose the track.

Request

Endpoint

POST /api/v1/tracks/compose

Payload

{
   "prompt": {
      "text": "30 seconds peaceful lo-fi chill hop track"
   },
   "format": "wav", // optional
   "looping": false // optional
}

Description

• prompt: The prompt for the track.
• format: format of the generated assets. Can be chosen as mp3, aac and wav. Default is wav
• looping: control the extent of looping in the track. Set true for higher amount of looping. The default value is false

Response

If the composition request succeeds, an asynchronous process will begin and you'll be delivered a task ID in the success response.

Example:

{
   "status": "started",
   "task_id": "ccb84650-7b4a-4d00-9f80-8a6427ca21aa_1"
}

Checking composition status

Once a composition task has started, you can query the progress of the task using the status request.

Request

Endpoint

GET /api/v1/tasks/<task_id>

Arguments

• task_id: Task ID returned in the response of the composition request.

Response

Example

{
   "status": "composed",
   "meta": {
      "project_id": "3ade3151-372d-4ac8-b1ef-866a67ef0875",
      "track_id": "ccb84650-7b4a-4d00-9f80-8a6427ca21aa",
      "prompt": {
         "text": "30 seconds peaceful lo-fi chill hop track"
      },
      "version": 1,
      "track_url":"<url-of-the-composed-track",
      "stems_url": {
         "bass": "<url-of-the-bass-track>",
         "chords": "<url-of-the-chords-track>",
         "melody": "<url-of-the-melody-track>",
         "percussion": "<url-of-the-percussion-track>"
      }
   }
}

Description

status: The value can be one of the following -

• composing: The task has been put in the queue
• running: The task has started running
• composed: The composition task has finished and the generated assets are available