Music AI

https://music.ai/docs/
Admin
Music AI is an audio intelligence platform that provides APIs and a no-code dashboard for...
Tokens:25,475
Snippets:240
Trust Score:9.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Response Example for GET /upload

Source: https://music.ai/docs/api/reference

Example JSON response containing temporary upload and download URLs.

```json
{
  "uploadUrl": "https://storage.googleapis.com/moises/939b7898b3ef?(...)X96cb5",
  "downloadUrl": "https://storage.googleapis.com/moises/939b7898b3ef?(...)SSScb5"
}

```

--------------------------------

### Get Application - Response Example

Source: https://music.ai/docs/api/reference

Example JSON response from the GET /application endpoint, showing the application's id and name.

```json
{
  "id": "80b069ab-8410-4cc9-9bfa-1282b97dc1df",
  "name": "Default Application"
}

```

--------------------------------

### Install @music.ai/sdk via npm

Source: https://music.ai/docs/sdk/nodejs

Install the SDK package using npm.

```bash
npm i @music.ai/sdk --save
```

--------------------------------

### Sections JSON format example

Source: https://music.ai/docs/api/file-formats

Example JSON structure for sections with start, end, and section properties.

```json
{
  "start": 0,
  "end": 10,
  "section": "Verse"
}
```

--------------------------------

### Install musicai-sdk via pip

Source: https://music.ai/docs/sdk/python

Installs the musicai-sdk package from PyPI.

```bash
pip install musicai_sdk
```

--------------------------------

### Chords JSON format example

Source: https://music.ai/docs/api/file-formats

Example JSON structure for chords with start, end, and chord properties.

```json
{
  "start": 0,
  "end": 10,
  "chord": "C"
}
```

--------------------------------

### Get job example

Source: https://music.ai/docs/sdk/python

Example call to get_job with a job ID.

```python
job = music_ai.get_job("your-job-id")
```

--------------------------------

### Add job example

Source: https://music.ai/docs/sdk/python

Example of adding a job for the music-ai/isolate-drums workflow with an input URL.

```python
song_url = "https://your-website.com/song.mp3"
job_id = music_ai.add_job("job-1", "music-ai/isolate-drums", {
    "inputUrl": song_url,
})
```

--------------------------------

### Install CLI

Source: https://music.ai/docs/clients/cli

Install the Music AI CLI globally using npm.

```APIDOC
## Install CLI

### Description
Install the Music AI CLI globally on your computer.

### Command
```
npm install -g @music.ai/cli
```

```

--------------------------------

### Upload file example

Source: https://music.ai/docs/sdk/python

Example call to upload_file with a file path.

```python
song_url = music_ai.upload_file(file_path)
```

--------------------------------

### Get Jobs List Response Example

Source: https://music.ai/docs/api/reference

Example JSON response for the job list endpoint, showing an array of job objects with success and failure statuses.

```json
[
  {
    "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
    "app": "Your app name",
    "workflow": "Your workflow name",
    "status": "SUCCEEDED",
    "error": null,
    "batchName": null,
    "workflowParams": {
      "inputUrl": "https://your-server.com/audio-input.m4a"
    },
    "metadata": {},
    "result": {
      "vocals": "https://cdn.music.ai/something/vocals.wav",
      "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
    },
    "name": "My job 123",
    "createdAt": "2022-12-07T19:21:42.170Z",
    "startedAt": "2022-12-07T19:21:42.307Z",
    "completedAt": "2022-12-07T19:22:00.325Z"
  },
  {
    "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
    "app": "Your app name",
    "workflow": "your-workflow-slug",
    "status": "FAILED",
    "error": {
      "code": "BAD_INPUT",
      "title": "Invalid input",
      "message": "File not found."
    },
    "batchName": null,
    "workflowParams": {
      "inputUrl": "https://your-server.com/audio-input.m4a"
    },
    "metadata": {},
    "result": {
      "vocals": "https://cdn.music.ai/something/vocals.wav",
      "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
    },
    "name": "My job 123",
    "createdAt": "2022-12-07T19:21:42.170Z",
    "startedAt": "2022-12-07T19:21:42.307Z",
    "completedAt": "2022-12-07T19:22:00.325Z"
  }
]

```

--------------------------------

### uploadFile example

Source: https://music.ai/docs/sdk/nodejs

Example call to uploadFile, returning a file URL.

```typescript
const fileUrl = await musicAi.uploadFile(fileLocation)
```

--------------------------------

### Install CLI globally with npm

Source: https://music.ai/docs/clients/cli

Install the @music.ai/cli package globally using npm.

```bash
npm install -g @music.ai/cli

```

--------------------------------

### downloadJobResults output example

Source: https://music.ai/docs/sdk/nodejs

Example content of the workflow.result.json file created by downloadJobResults, showing relative paths for file outputs and values for non-file outputs.

```json
// workflow.result.json
{
  "vocals": "./vocals.wav",
  "bpm": "64"
}
```

--------------------------------

### Get Workflow List - Response Example

Source: https://music.ai/docs/api/reference

Example JSON response for the workflow list endpoint, showing an array of workflow objects with fields like id, name, slug, description, createdAt, and updatedAt.

```json
{
  "workflows": [
    {
      "id": "3a82e3b2-9de6-4979-986d-78805dd2152b",
      "name": "Your workflow name",
      "slug": "your-workflow-slug",
      "description": "",
      "createdAt": "2024-12-16T18:31:36.102Z",
      "updatedAt": "2024-12-16T18:32:34.723Z"
    },
    {
      "id": "2362a51f-e9f9-4472-bbd2-c40a0cc83ae2",
      "name": "Extract Beat map and BPM",
      "slug": "untitled-workflow-e78c2e",
      "description": "Transcribe song BPM and beats with AI for precise rhythm analysis.",
      "createdAt": "2024-12-13T15:11:42.022Z",
      "updatedAt": "2024-12-13T15:11:45.932Z"
    }
  ]
}

```

--------------------------------

### addJob example with music-ai/isolate-drums

Source: https://music.ai/docs/sdk/nodejs

Example of adding a job using the music-ai/isolate-drums workflow with an input URL.

```typescript
const songUrl = "https://your-website.com/song.mp3"
const jobId = await musicAi.addJob("job-1", "music-ai/isolate-drums", {
  inputUrl: songUrl,
})
```

--------------------------------

### GET /job/:id - Response example

Source: https://music.ai/docs/api/reference

Example JSON response for a successful job retrieval. Shows fields like id, status, result, and timestamps.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
  "app": "Your app name",
  "workflow": "your-workflow-slug",
  "status": "SUCCEEDED",
  "batchName": null,
  "workflowParams": {
    "inputUrl": "https://your-server.com/audio-input.m4a"
  },
  "metadata": {},
  "result": {
    "vocals": "https://cdn.music.ai/something/vocals.wav",
    "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
  },
  "name": "My job 123",
  "createdAt": "2022-12-07T19:21:42.170Z",
  "startedAt": "2022-12-07T19:21:42.307Z",
  "completedAt": "2022-12-07T19:22:00.325Z"
}

```

--------------------------------

### Beats JSON format example

Source: https://music.ai/docs/api/file-formats

Example JSON structure for beats with start, end, and bpm properties.

```json
{
  "start": 0,
  "end": 10,
  "bpm": 120
}
```

--------------------------------

### Subtitles JSON format example

Source: https://music.ai/docs/api/file-formats

Example JSON structure for subtitles with start, end, and text properties.

```json
{
  "start": 0,
  "end": 10,
  "text": "Hello world"
}
```

--------------------------------

### Quick start: create, wait, download, and delete a job

Source: https://music.ai/docs/sdk/python

Shows the full workflow: upload a file, add a job for the music-ai/generate-chords workflow, wait for completion, download results if succeeded, and delete the job. Requires an API key.

```python
from musicai_sdk import MusicAiClient


music_ai = MusicAiClient(api_key="your-api-key")

song_url = music_ai.upload_file("./song.mp3")

job_id = music_ai.add_job(
    "My first job",
    "music-ai/generate-chords",
    {
        "inputUrl": song_url,
    },
)["id"]

job = music_ai.wait_for_job_completion(job_id)

if job["status"] == "SUCCEEDED":
    files = music_ai.download_job_results(job, "./chords")
    print("Result:", files)
else:
    print("Job failed!")

music_ai.delete_job(job_id)
```

--------------------------------

### Quick start: create job, wait, process, delete

Source: https://music.ai/docs/sdk/nodejs

Shows the full workflow: upload a file, add a job for the music-ai/generate-chords workflow, wait for completion, download results if succeeded, and delete the job. Requires an API key from the Music.AI dashboard.

```typescript
import MusicAi from "@music.ai/sdk"

const musicAi = new MusicAi({ apiKey: process.env.MUSIC_AI_API_KEY })

const songUrl = await musicAi.uploadFile("./song.mp3")

const jobId = await musicAi.addJob({
  name: "My first job",
  workflow: "music-ai/generate-chords",
  params: {
    inputUrl: songUrl,
  }
})

const job = await musicAi.waitForJobCompletion(jobId)

if (job.status === "SUCCEEDED") {
  const files = await musicAi.downloadJobResults(job, "./chords")
  console.log("Result:", files)
} else {
  console.log("Job failed!")
}

await musicAi.deleteJob(jobId)
```

--------------------------------

### downloadJobResults usage examples

Source: https://music.ai/docs/sdk/nodejs

Two examples of calling downloadJobResults: one with a job id and one with a job object obtained from waitForJobCompletion.

```typescript
const resultPaths = await musicAi.downloadJobResults(/* jobId */, "./stems")
```

```typescript
const job = await musicAi.waitForJobCompletion(/* jobId */)
const resultPaths = await musicAi.downloadJobResults(job, "./stems")
```

--------------------------------

### getJob usage example

Source: https://music.ai/docs/sdk/nodejs

Example of calling getJob with a job id.

```typescript
const job = await musicAi.getJob(/* jobId */)
```

--------------------------------

### Response Example for Create Job

Source: https://music.ai/docs/api/reference

Shows the response body for a successful job creation. Contains the id of the new job.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28"
}
```

--------------------------------

### Generic JSON format example

Source: https://music.ai/docs/api/file-formats

Example JSON structure for generic JSON with any properties, documented by the module.

```json
{
  "propertyA": 0,
  "propertyB": 10,
  "data": {
    "key": "value"
  }
}
```

--------------------------------

### Job object example

Source: https://music.ai/docs/sdk/python

Example JSON representation of a job returned by get_job, showing fields like id, app, workflow, status, result, and timestamps.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
  "app": "Your app name",
  "workflow": {
    "id": "2ae5eea3-63dd-445e-9a3f-ff0473e82fd2",
    "name": "Stems Isolations - Vocals & accompaniments"
  },
  "status": "SUCCEEDED",
  "error": null,
  "batchName": null,
  "workflowParams": {
    "inputUrl": "https://your-server.com/audio-input.m4a"
  },
  "metadata": {},
  "result": {
    "vocals": "https://cdn.music.ai/something/vocals.wav",
    "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
  },
  "name": "My job 123",
  "createdAt": "2022-12-07T19:21:42.170Z",
  "startedAt": "2022-12-07T19:21:42.307Z",
  "completedAt": "2022-12-07T19:22:00.325Z"
}
```

--------------------------------

### GET /application

Source: https://music.ai/docs/api/reference

Get the current application (API key). This endpoint returns information about the authenticated application.

```APIDOC
## GET /application

### Description
Get the current application (API key).

### Method
GET

### Endpoint
/application

### Response
#### Success Response (200)
Returns application details.

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### listJobs usage examples

Source: https://music.ai/docs/sdk/nodejs

Two examples of calling listJobs: one without filters and one with filters for status and workflow.

```typescript
const jobs = await musicAi.listJobs()
```

```typescript
const jobs = await musicAi.listJobs({
  status: ["FAILED"],
  workflow: ["workflow-a", "workflow-b"],
})
```

--------------------------------

### Add job with custom storage

Source: https://music.ai/docs/sdk/python

Shows how to use the copy_results_to option to store outputs in your own storage. The example uses the music-ai/isolate-drums workflow, which has 3 outputs (Kick drum, Snare drum, Other). Only the first two are provided; the third is stored in Music AI's storage.

```python
job_id = music_ai.add_job(
    "job-1",
    "music-ai/isolate-drums",
    {
        "inputUrl": song_url,
    },
    copy_results_to={
        "Kick drum": "https://example.com/my-upload-url-1",
        "Snare drum": "https://example.com/my-upload-url-2"
    }
)
```

--------------------------------

### GET /workflow

Source: https://music.ai/docs/api/reference

Get all workflows. This endpoint returns a list of available workflows.

```APIDOC
## GET /workflow

### Description
Get all workflows.

### Method
GET

### Endpoint
/workflow

### Response
#### Success Response (200)
Returns a list of workflows.

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### Request signed URLs with GET /v1/upload

Source: https://music.ai/docs/api/file-upload

Requests an uploadUrl and downloadUrl from the temporary upload server. Replace your-api-key-here with your actual API key. The response contains the URLs needed for the subsequent upload and use steps.

```bash
curl --request GET \
	--url https://api.music.ai/v1/upload \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### waitForJobCompletion usage example

Source: https://music.ai/docs/sdk/nodejs

Example of calling waitForJobCompletion and checking the job status to log success or failure.

```typescript
const job = await musicAi.waitForJobCompletion(/* jobId */)

if (job.status === "SUCCEEDED") {
  console.log("Job succeeded!")
} else {
  console.log("Job failed!")
}
```

--------------------------------

### getJob success response example

Source: https://music.ai/docs/sdk/nodejs

Example JSON response for a successful job retrieval, showing the job object with status SUCCEEDED and result URLs.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
  "app": "Your app name",
  "name": "My job 123",
  "batchName": null,
  "metadata": {},
  "workflow": "music-ai/generate-chords",
  "workflowParams": {
    "inputUrl": "https://your-server.com/audio-input.m4a"
  },
  "status": "SUCCEEDED",
  "result": {
    "vocals": "https://cdn.music.ai/example/vocals.wav",
    "accompaniments": "https://cdn.music.ai/example/accompaniments.wav"
  },
  "error": null,
  "createdAt": "2022-12-07T19:21:42.170Z",
  "startedAt": "2022-12-07T19:21:42.307Z",
  "completedAt": "2022-12-07T19:22:00.325Z"
}
```

--------------------------------

### Delete Job - Response Example

Source: https://music.ai/docs/api/reference

Example JSON response for a successful job deletion, containing the ID of the deleted job.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28"
}

```

--------------------------------

### getJob failure response example

Source: https://music.ai/docs/sdk/nodejs

Example JSON response for a failed job, showing status FAILED and an error object with code, title, and message.

```json
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
  "app": "Your app name",
  "name": "My job 123",
  "batchName": null,
  "metadata": {},
  "workflow": "music-ai/generate-chords",
  "workflowParams": {
    "inputUrl": "https://your-server.com/audio-input.m4a"
  },
  "status": "SUCCEEDED",
  "result": {
    "vocals": "https://cdn.music.ai/example/vocals.wav",
    "accompaniments": "https://cdn.music.ai/example/accompaniments.wav"
  },
  "error": {
    "code": "BAD_INPUT",
    "title": "Invalid input",
    "message": "File not found."
  },
  "createdAt": "2022-12-07T19:21:42.170Z",
  "startedAt": "2022-12-07T19:21:42.307Z",
  "completedAt": "2022-12-07T19:22:00.325Z"
}
```

--------------------------------

### GET /job

Source: https://music.ai/docs/api/reference

Get all jobs. This endpoint returns a list of all jobs associated with the authenticated application.

```APIDOC
## GET /job

### Description
Get all jobs.

### Method
GET

### Endpoint
/job

### Response
#### Success Response (200)
Returns a list of jobs.

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### addJob with custom storage (copyResultsTo)

Source: https://music.ai/docs/sdk/nodejs

Shows how to store outputs in your own storage by providing upload URLs for each workflow output. The example uses the music-ai/isolate-drums workflow, which has three outputs: Kick drum, Snare drum, and Other. If a URL is not provided for an output, it is stored in Music AI's storage.

```typescript
await musicAi.addJob({
  name: "job-1",
  workflow: "music-ai/isolate-drums",
  params: {
    inputUrl: songUrl,
  },
  copyResultsTo: {
    "Kick drum": "https://example.com/my-upload-url-1",
    "Snare drum": "https://example.com/my-upload-url-2"
  }
)
```

--------------------------------

### Wait for job completion

Source: https://music.ai/docs/sdk/python

Shows the wait_for_job_completion function signature and an example that waits for a job and prints the result.

```python
def wait_for_job_completion(job_id: str) -> Job

```

```python
job = music_ai.wait_for_job_completion("your-job-id")

if job["status"] == "SUCCEEDED":
    print("Job succeeded!")
else:
    print("Job failed!")

```

--------------------------------

### Download all job results

Source: https://music.ai/docs/sdk/python

Shows the download_job_results function signature and examples of downloading results by job ID or job object. Also shows the resulting workflow.results.json file.

```python
def download_job_results(job_id_or_job_data: Union[str, Job], output_folder: str) -> List[str]

```

```python
result_paths = music_ai.download_job_results("your-job-id", "./results")

```

```python
job = music_ai.wait_for_job_completion("your-job-id")
result_paths = music_ai.download_job_results(job, "./results")

```

```json
// workflow.result.json

{
  "vocals": "./vocals.wav",
  "bpm": "64"
}

```

--------------------------------

### Get job info

Source: https://music.ai/docs/clients/cli

Retrieve information about a job using the 'musicai job info' command.

```bash
musicai job info <jobId>

```

--------------------------------

### Job status response

Source: https://music.ai/docs/getting-started/quick-start

Example response showing a completed job with status SUCCEEDED and result URLs for vocals and accompaniments.

```json
{
  "id": "27803abe-ec15-4f74-9e8a-18a99627e9b0",
  "app": "Your app name",
  "workflow": "music-ai/stems-vocals-accompaniment",
  "status": "SUCCEEDED",
  "batchName": null,
  "workflowParams": {
    "inputUrl": "https://your-server.com/audio-input.m4a"
  },
  "metadata": {},
  "result": {
    "vocals": "https://cdn.music.ai/something/vocals.wav",
    "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
  },
  "name": "My job 123",
  "createdAt": "2022-12-07T19:21:42.170Z",
  "startedAt": "2022-12-07T19:21:42.307Z",
  "completedAt": "2022-12-07T19:22:00.325Z"
}

```

--------------------------------

### GET /application

Source: https://music.ai/docs/api/reference

Retrieves information about the current application identified by the API key. The response includes the application's unique ID and name.

```APIDOC
## GET /application

### Description
Check the information about the current used application (API key).

### Method
GET

### Endpoint
https://api.music.ai/v1/application

### Parameters
#### Headers
- **Authorization** (string) - Required - The API key for the application.

### Request Example
```
curl --request GET \
	--url https://api.music.ai/v1/application \
	--header 'Authorization: your-api-key-here'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the application
- **name** (string) - Human-readable name of the application

#### Response Example
```
{
  "id": "80b069ab-8410-4cc9-9bfa-1282b97dc1df",
  "name": "Default Application"
}
```

#### Error Responses
- **401** - Missing or invalid API key
```

--------------------------------

### GET /workflow

Source: https://music.ai/docs/api/reference

Paginated workflow listing endpoint. The result is sorted by creation date.

```APIDOC
## GET /workflow

### Description
Paginated workflow listing endpoint. The result is sorted by creation date.

### Method
GET

### Endpoint
https://api.music.ai/v1/workflow

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (defaults to 0)
- **size** (integer) - Optional - Page size (defaults to 100)

### Request Example
```
curl --request GET \
	--url https://api.music.ai/v1/workflow?page=0&size=20 \
	--header 'Authorization: your-api-key-here'
```

### Response
#### Success Response (200)
- **workflows** (array) - Array of workflow objects
- **workflows[].id** (string) - Unique identifier for the workflow
- **workflows[].name** (string) - Human-readable name of the workflow
- **workflows[].slug** (string) - URL-friendly identifier used when creating jobs
- **workflows[].description** (string) - Description of what this workflow does
- **workflows[].createdAt** (string) - ISO timestamp when workflow was created
- **workflows[].updatedAt** (string) - ISO timestamp when workflow was last modified

#### Response Example
```
{
  "workflows": [
    {
      "id": "3a82e3b2-9de6-4979-986d-78805dd2152b",
      "name": "Your workflow name",
      "slug": "your-workflow-slug",
      "description": "",
      "createdAt": "2024-12-16T18:31:36.102Z",
      "updatedAt": "2024-12-16T18:32:34.723Z"
    },
    {
      "id": "2362a51f-e9f9-4472-bbd2-c40a0cc83ae2",
      "name": "Extract Beat map and BPM",
      "slug": "untitled-workflow-e78c2e",
      "description": "Transcribe song BPM and beats with AI for precise rhythm analysis.",
      "createdAt": "2024-12-13T15:11:42.022Z",
      "updatedAt": "2024-12-13T15:11:45.932Z"
    }
  ]
}
```
```

--------------------------------

### GET /upload

Source: https://music.ai/docs/api/reference

Retrieves a signed URL to upload a file to the temporary server. Use the returned uploadUrl to upload the file and downloadUrl to retrieve it after upload.

```APIDOC
## GET /upload

### Description
Retrieves a signed URL to upload a file to our temporary server. For more information about uploading inputs, please refer to the Uploads documentation.

### Method
GET

### Endpoint
https://api.music.ai/v1/upload

### Parameters
#### Headers
- **Authorization** (string) - Required - API key for authentication.

### Request Example
```
curl --request GET \
	--url https://api.music.ai/v1/upload \
	--header 'Authorization: your-api-key-here'
```

### Response
#### Success Response (200)
- **uploadUrl** (string) - URL to upload the file to. This URL is temporary.
- **downloadUrl** (string) - URL to download the file from after it has been uploaded. This URL is temporary.

#### Response Example
```
{
  "uploadUrl": "https://storage.googleapis.com/moises/939b7898b3ef?(...)X96cb5",
  "downloadUrl": "https://storage.googleapis.com/moises/939b7898b3ef?(...)SSScb5"
}
```

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### Get Workflow List - curl request

Source: https://music.ai/docs/api/reference

Sends a GET request to /workflow with optional pagination parameters (page, size). Returns a paginated list of workflows sorted by creation date.

```bash
curl --request GET \
	--url https://api.music.ai/v1/workflow?page=0&size=20 \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### Get Jobs List with curl

Source: https://music.ai/docs/api/reference

Use this curl command to list jobs with pagination. The result is sorted by creation date. The job must have been created with the same API key used in the request.

```bash
curl --request GET \
	--url https://api.music.ai/v1/job?page=0&size=20 \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### Job result JSON with custom storage

Source: https://music.ai/docs/sdk/python

Example JSON response for a job created with custom storage. Outputs directed to custom storage are marked as '[custom storage]' and no download URLs are provided for them.

```json
{
  // ...
  "result": {
    "Kick drum": "[custom storage]",
    "Snare drum": "[custom storage]",
    "Other": "https://cdn.music.ai/example/vocals.wav"
  }
}
```

--------------------------------

### GET /job

Source: https://music.ai/docs/api/reference

Paginated job listing endpoint. The result is sorted by creation date. Supports filtering by status, workflow, and batch name, with pagination parameters.

```APIDOC
## GET /job

### Description
Paginated job listing endpoint. The result is sorted by creation date. This will only work for jobs that were created with the same API key being used on the request.

### Method
GET

### Endpoint
https://api.music.ai/v1/job

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filters by one or more statuses. Possible values: `QUEUED`, `STARTED`, `SUCCEEDED`, and `FAILED`. Example: `?status=QUEUED&status=STARTED`
- **workflow** (string) - Optional - Filters by workflows given their slugs. Example: `?workflow=audio-encoder&workflow=stem-separation`
- **batchName** (string) - Optional - Filters by batch name. Example: `?batchName=my-batch`
- **page** (integer) - Optional - Page number (defaults to 0). Example: `?page=1`
- **size** (integer) - Optional - Page size (defaults to 100). Example: `?size=20`

### Request Example
```
curl --request GET \
	--url https://api.music.ai/v1/job?page=0&size=20 \
	--header 'Authorization: your-api-key-here'
```

### Response
#### Success Response (200)
- **jobs** (array) - Array of job objects
- **jobs[].id** (string) - Unique identifier for the job
- **jobs[].app** (string) - Name of the application that created the job
- **jobs[].name** (string) - Human-readable name of the job
- **jobs[].batchName** (string | null) - Name of the batch if the job is part of one
- **jobs[].metadata** (object) - Additional metadata associated with the job
- **jobs[].workflow** (string) - Name of the workflow used
- **jobs[].workflowParams** (object) - Parameters passed to the workflow
- **jobs[].status** (string) - Current job status (`QUEUED`, `STARTED`, `SUCCEEDED`, `FAILED`)
- **jobs[].result** (object) - Job results (varies by workflow)
- **jobs[].error** (JobError | null) - Error details if the job failed, null otherwise
- **jobs[].error.code** (string) - Error code
- **jobs[].error.title** (string) - Summary of the error
- **jobs[].error.message** (string) - Detailed explanation of the error occurrence
- **jobs[].createdAt** (string) - ISO timestamp when the job was created
- **jobs[].startedAt** (string) - ISO timestamp when the job started processing
- **jobs[].completedAt** (string) - ISO timestamp when the job completed

#### Response Example
```
[
  {
    "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
    "app": "Your app name",
    "workflow": "Your workflow name",
    "status": "SUCCEEDED",
    "error": null,
    "batchName": null,
    "workflowParams": {
      "inputUrl": "https://your-server.com/audio-input.m4a"
    },
    "metadata": {},
    "result": {
      "vocals": "https://cdn.music.ai/something/vocals.wav",
      "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
    },
    "name": "My job 123",
    "createdAt": "2022-12-07T19:21:42.170Z",
    "startedAt": "2022-12-07T19:21:42.307Z",
    "completedAt": "2022-12-07T19:22:00.325Z"
  },
  {
    "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
    "app": "Your app name",
    "workflow": "your-workflow-slug",
    "status": "FAILED",
    "error": {
      "code": "BAD_INPUT",
      "title": "Invalid input",
      "message": "File not found."
    },
    "batchName": null,
    "workflowParams": {
      "inputUrl": "https://your-server.com/audio-input.m4a"
    },
    "metadata": {},
    "result": {
      "vocals": "https://cdn.music.ai/something/vocals.wav",
      "accompaniments": "https://cdn.music.ai/something/accompaniments.wav"
    },
    "name": "My job 123",
    "createdAt": "2022-12-07T19:21:42.170Z",
    "startedAt": "2022-12-07T19:21:42.307Z",
    "completedAt": "2022-12-07T19:22:00.325Z"
  }
]
```

### Response Codes
- **200** - Jobs successfully retrieved
- **400** - Invalid parameters
- **401** - Missing or invalid API key
```

--------------------------------

### List jobs with optional filters

Source: https://music.ai/docs/sdk/python

Defines the Filters TypedDict and the list_jobs function signature. The example shows calling list_jobs without filters and with filters for status and workflow.

```python
Status = Literal["QUEUED", "STARTED", "SUCCEEDED", "FAILED"]

class Filters(TypedDict, total=False):
    status: Optional[List[Status]]
    workflow: Optional[List[str]]

def list_jobs(filters: Optional[Filters] = None) -> List[Job]

```

```python
jobs = music_ai.list_jobs()

```

```python
filters = {
    "status": ["SUCCEEDED", "FAILED"],
    "workflow": ["workflow-a", "workflow-b"]
}
jobs = music_ai.list_jobs(filters=filters)

```

--------------------------------

### Use downloadUrl with POST /v1/job

Source: https://music.ai/docs/api/file-upload

Creates a job using the downloadUrl as the input file. Replace your-api-key-here, workflow ID, and the inputUrl with your actual values. The downloadUrl is the one received from the first step.

```bash
curl --request POST \
	--url https://api.music.ai/v1/job \
	--header 'Authorization: your-api-key-here' \
	--header 'Content-Type: application/json' \
	--data '{
		"name": "My job 123",
		"workflow": "my-workflow-id",
		"params": {
			"inputUrl": "https://storage.googleapis.com/download/something"
		}
	}'

```

--------------------------------

### GET /job/:id/status

Source: https://music.ai/docs/api/reference

Get the status of a job by its ID. Use this endpoint to check the current state of a job.

```APIDOC
## GET /job/:id/status

### Description
Get the status of a job by its ID.

### Method
GET

### Endpoint
/job/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job whose status to retrieve.

### Response
#### Success Response (200)
Returns the job status.

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### Add a job

Source: https://music.ai/docs/clients/cli

Add a new job using the 'musicai job add' command.

```bash
musicai job add <name> <workflow> <inputFile>

```

--------------------------------

### GET /job/:id

Source: https://music.ai/docs/api/reference

Get a job by its ID. This endpoint allows you to retrieve details of a specific job using its unique identifier.

```APIDOC
## GET /job/:id

### Description
Get a job by its ID.

### Method
GET

### Endpoint
/job/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job to retrieve.

### Response
#### Success Response (200)
Returns the job details.

#### Response Codes
- **200** - Success
- **401** - Missing or invalid API key
```

--------------------------------

### List jobs

Source: https://music.ai/docs/clients/cli

List all jobs using the 'musicai job list' command.

```bash
musicai job list

```

--------------------------------

### Set API key environment variable

Source: https://music.ai/docs/clients/cli

Set the MUSIC_AI_API_KEY environment variable to authenticate with the CLI.

```bash
export MUSIC_AI_API_KEY=your-api-key

```

--------------------------------

### Create a job with curl POST

Source: https://music.ai/docs/getting-started/quick-start

Submits a job to the Music AI API using the music-ai/stems-vocals-accompaniment workflow. Requires a publicly accessible input URL and an API key. The response contains the job id.

```bash
curl --request POST \
	--url https://api.music.ai/v1/job \
	--header 'Authorization: your-api-key-here' \
	--header 'Content-Type: application/json' \
	--data '{
  "name": "My job 123",
  "workflow": "music-ai/stems-vocals-accompaniment",
  "params": {
    "inputUrl": "https://music.ai/demo.ogg"
  }
}'

```

--------------------------------

### Authenticate

Source: https://music.ai/docs/clients/cli

Set the MUSIC_AI_API_KEY environment variable to authenticate with the Music AI platform.

```APIDOC
## Authenticate

### Description
Set the MUSIC_AI_API_KEY environment variable to authenticate with the Music AI platform.

### Command
```
export MUSIC_AI_API_KEY=your-api-key
```

```

--------------------------------

### GET /job/:id - curl request

Source: https://music.ai/docs/api/reference

Sends a GET request to retrieve job information. Requires an API key. Only works for jobs created with the same API key.

```bash
curl --request GET \
	--url https://api.music.ai/v1/job/:id \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### Get job method signature

Source: https://music.ai/docs/sdk/python

Defines the get_job method that retrieves job information by its ID.

```python
def get_job(job_id: str) -> Job
```

--------------------------------

### Process a local folder

Source: https://music.ai/docs/clients/cli

Process all files in a folder using the 'musicai process folder' command. Optionally use --watch to continuously process new files added to the input folder.

```bash
musicai process folder <workflow> <inputFolder> <outputFolder> [--watch]

```

--------------------------------

### GET /job/:id/status

Source: https://music.ai/docs/api/reference

Retrieves the current status of a job by its ID. Only works for jobs created with the same API key used in the request.

```APIDOC
## GET /job/:id/status

### Description
Get the current status of a job by its ID. This will only work for jobs that were created with the same API key being used on the request.

### Method
GET

### Endpoint
https://api.music.ai/v1/job/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier for the job

### Request Example
```
curl --request GET \
	--url https://api.music.ai/v1/job/:id/status \
	--header 'Authorization: your-api-key-here'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the job
- **status** (string) - Current job status (`QUEUED`, `STARTED`, `SUCCEEDED`, `FAILED`)

#### Response Example
```
{
  "id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
  "status": "SUCCEEDED"
}
```

### Response Codes
- **200** - Job status successfully retrieved
- **400** - Invalid job ID format
- **401** - Missing or invalid API key
- **404** - Job not found
```

--------------------------------

### downloadJobResults(job: Job, destination: string): Promise<string[]>

Source: https://music.ai/docs/sdk/nodejs

Downloads the results of a completed job to a local directory and returns the list of downloaded file paths.

```APIDOC
## downloadJobResults(job: Job, destination: string): Promise<string[]>

### Description
Downloads the results of a completed job to a local directory and returns the list of downloaded file paths.

### Method
downloadJobResults

### Parameters
- **job** (Job) - Required - The job object containing the result URLs.
- **destination** (string) - Required - The local directory path where the results will be saved.

### Returns
- **Promise<string[]>** - A promise that resolves to an array of file paths of the downloaded results.

### Example

const files = await musicAi.downloadJobResults(job, "./chords")

```

--------------------------------

### Get Job Status with curl

Source: https://music.ai/docs/api/reference

Use this curl command to retrieve the status of a job by its ID. The job must have been created with the same API key used in the request.

```bash
curl --request GET \
	--url https://api.music.ai/v1/job/:id/status \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### Create Job with curl

Source: https://music.ai/docs/api/reference

Sends a POST request to create a job. Requires an API key and a workflow slug. The params object must match the workflow's input schema. The metadata field is optional and can store key-value pairs with string, number, or boolean values.

```bash
curl --request POST \
	--url https://api.music.ai/v1/job \
	--header 'Authorization: your-api-key-here' \
	--header 'Content-Type: application/json' \
	--data '{
    "name": "My job 123",
    "workflow": "my-workflow-id",
    "params": {
      "inputUrl": "https://music.ai/demo.ogg"
    },
    "metadata": {
      "user": 123,
    }
  }'
```

--------------------------------

### Retrieve job results with curl GET

Source: https://music.ai/docs/getting-started/quick-start

Checks the status and results of a job using its id. The response indicates whether the job is still processing or has completed.

```bash
curl --request GET \
	--url https://api.music.ai/v1/job/27803abe-ec15-4f74-9e8a-18a99627e9b0 \
	--header 'Authorization: your-api-key-here'

```

--------------------------------

### Process a single local file

Source: https://music.ai/docs/clients/cli

Process a single local file using the 'musicai process file' command. This creates a job, waits for completion, downloads results to the output folder, and deletes the job.

```bash
musicai process file <workflow> <fileLocation> <outputFolder>

```

--------------------------------

### downloadJobResults(jobIdOrJobData: string | Job, outputFolder: string): Promise<{ [key: string]: string }>

Source: https://music.ai/docs/sdk/nodejs

Downloads all job results to a local folder. Also creates a workflow.result.json file containing the result in JSON format.

```APIDOC
## downloadJobResults(jobIdOrJobData: string | Job, outputFolder: string): Promise<{ [key: string]: string }>

### Description
Download all the job results to a local folder. This function also creates a file called `workflow.result.json` containing the result in the JSON format. When an output is a file, that field will contain the relative path to the file.

### Method
SDK Method

### Signature
`function downloadJobResults(jobIdOrJobData: string | Job, outputFolder: string): Promise<{ [key: string]: string }>`

### Parameters
- **jobIdOrJobData** (string | Job) - Required - The job ID or the job object.
- **outputFolder** (string) - Required - The local folder path where results will be saved.

### Request Example
js
const resultPaths = await musicAi.downloadJobResults(/* jobId */, "./stems")


Or, if you already have the job object...
js
const job = await musicAi.waitForJobCompletion(/* jobId */)
const resultPaths = await musicAi.downloadJobResults(job, "./stems")


### Response
Returns a Promise that resolves to an object mapping output names to file paths or values. For example, if the workflow has two outputs, vocals in WAVE format and bpm, two files will be created at the given folder: `vocals.wav` and `workflow.result.json`.

#### Response Example
json
// workflow.result.json
{
  "vocals": "./vocals.wav",
  "bpm": "64"
}

```
Tokens:
Raw