API Reference

Here you can find all the methods and properties of our API.

All requests to the Music AI API must be authenticated using an API key. The API key should be included in the Authorization header of each request. For more information about authentication, please refer to the Authentication documentation.

Summary

File upload

GET /upload Get a signed URL to upload a file to our temporary server.

Jobs

GET /job/:id Get a job by its ID.

GET /job/:id/status Get the status of a job by its ID.

GET /job Get all jobs.

POST /job Create a new job.

DELETE /job/:id Delete a job by its ID.

Workflows

GET /workflow Get all workflows.

Applications

GET /application Get the current application (API key).

File Upload

Prepare Upload `GET /upload`

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

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

Response Fields

Field	Type	Description
`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 Codes

Code	Description
`200`	Success
`401`	Missing or invalid API key

Response Example

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

Jobs

A job represents a single processing task submitted to our AI pipeline. When you upload audio and request processing (like stem separation or audio enhancement), a job is created to handle that work asynchronously.

Each job contains your input parameters, tracks its progress, and stores the final results. Jobs are tied to your API key and can include custom metadata for organization.

Status

The status represents the job current state:

Status	Description
`QUEUED`	Awaiting to start
`STARTED`	Processing has started
`SUCCEEDED`	Processing has completed and the results are ready
`FAILED`	An error occurred during processing

Failure

When a job fails, it has a status of FAILED and an error object with the error reason.

Error fields:

Field	Type	Description
`code`	`string`	Error code
`title`	`string`	Summary of the error
`message`	`string`	Detailed explanation of the error occurrence

Error codes:

Code	Title	Possible reason
`BAD_INPUT`	Invalid input	The input is invalid. Likely, the file was not uploaded or not completely uploaded; it is corrupted; it has an invalid format; or it doesn't meet requirements for the workflow.
`TIMEOUT`	Timeout	Timeout reading the input file. If using a storage other than Music AI's, check if the server is reachable and the file is still available.
`INTERNAL_ERROR`	Internal error	Our server encountered and error while running the job. Pleas try again. If the problem persists, contact support providing the job ID and parameters.

Get Job Information `GET /job/:id`

Retrieves information about a specific job by its ID.

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

Please note that this will only work for jobs that were created with the same API key being used on the request.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the job to retrieve

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier for the job
`app`	`string`	Name of the application that created this job
`name`	`string`	Human-readable name for the job
`batchName`	`string \| null`	Optional batch identifier if job was created as part of a batch
`metadata`	`object`	Custom metadata provided when creating the job
`workflow`	`string`	Name of the workflow used for processing
`workflowParams`	`object`	Input parameters provided when creating the job
`status`	`string`	Current job status (`QUEUED`, `STARTED`, `SUCCEEDED`, `FAILED`)
`result`	`object \| null`	Processing results (URLs to output files) when status is `SUCCEEDED`
`error`	`object \| null`	Error details if the job failed, null otherwise
`error.code`	`string`	Error code
`error.title`	`string`	Summary of the error
`error.message`	`string`	Detailed explanation of the error occurrence
`createdAt`	`string`	ISO timestamp when job was created
`startedAt`	`string \| null`	ISO timestamp when processing started
`completedAt`	`string \| null`	ISO timestamp when processing completed

Response Codes

Status Code	Description
`200`	Job successfully retrieved
`400`	Invalid job ID format
`401`	Missing or invalid API key
`404`	Job not found

Response Example

{
  "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"
}

Get Job Status `GET /job/:id/status`

Get the current status of a job by its ID.

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

Please note that this will only work for jobs that were created with the same API key being used on the request.

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier for the job
`status`	`string`	Current job status (`QUEUED`, `STARTED`, `SUCCEEDED`, `FAILED`)

Response Codes

Status Code	Description
`200`	Job status successfully retrieved
`400`	Invalid job ID format
`401`	Missing or invalid API key
`404`	Job not found

Response Example

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

Get Jobs List `GET /job`

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

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

Please note that this will only work for jobs that were created with the same API key being used on the request.

Parameters

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

Response Fields

Field	Type	Description
`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 Codes

Status Code	Description
`200`	Jobs successfully retrieved
`400`	Invalid parameters
`401`	Missing or invalid API key

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"
  }
]

Create Job `POST /job`

Creates a new job to be processed by the specified workflow.

The job will be processed asynchronously. You can check its status using the GET /job/:id endpoint.

The metadata field is optional and can be used to store arbitrary key-value pairs. This is useful for tracking jobs in your application.

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,
    }
  }'

Parameters

Field	Required	Type	Description
`name`	✔︎	`string`	Arbitrary job name.
`workflow`	✔︎	`string`	Workflow slug. It can be found in the workflow metadata.
`params`	✔︎	`object`	Workflow parameters. It must match the workflow's input schema.
`metadata`		Key-value pairs, where each key is a string and each value can be a `string`, `number`, or `boolean`.	Optional metadata for job identification.

Response Fields

Field	Type	Description
`id`	`string`	ID of the new job

Response Codes

Status Code	Description
200	Job created successfully
400	Invalid fields
401	Missing or invalid API key
404	Workflow not found
422	The workflow contains errors or invalid workflow parameters were given

Response Example

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

Delete Job `DELETE /job/:id`

Deletes a job by its ID. This operation is irreversible.

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

Please note that this will only work for jobs that were created with the same API key being used on the request.

Parameters

Field	Type	Description
`id`	`string`	Job ID

Response Fields

Field	Type	Description
`id`	`string`	ID of the deleted job

Response Codes

Status Code	Description
200	Job deleted successfully
401	Missing or invalid API key
404	Job not found

Response Example

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

Workflows

Workflows define how a processing task will be executed.

When creating a job, you specify which workflow to use along with its parameters. Music AI then uses the workflow to processes - whether that's transcription, beat detection, stem separation, or any other supported processing task.

Get Workflow List `GET /workflow`

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

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

Parameters

Parameter	Description	Example
`page`	Page number (defaults to 0)	`?page=1`
`size`	Page size (defaults to 100)	`?size=20`

Response Fields

Field	Type	Description
`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"
    }
  ]
}

Applications (API Keys)

An application represents a client that can interact with the Music AI API. Each application has a unique API key that is used to authenticate requests. Applications can create jobs, manage workflows, and access other API resources.

Applications are created through the Music AI dashboard. Each application has its own set of jobs, ensuring data isolation between different clients.

When making API requests, the application's API key must be included in the Authorization header. This key is used to identify the application and ensure that it only has access to its own resources.

Get Application `GET /application`

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

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

Response Fields

Field	Type	Description
`id`	`string`	Unique identifier for the application
`name`	`string`	Human-readable name of the application

Response Codes

Status Code	Description
`200`	Application successfully retrieved
`401`	Missing or invalid API key

Response Example

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

Summary

File Upload

Prepare Upload GET /upload

Response Fields

Response Codes

Response Example

Jobs

Status

Failure

Get Job Information GET /job/:id

Parameters

Response Fields

Response Codes

Response Example

Get Job Status GET /job/:id/status

Response Fields

Response Codes

Response Example

Get Jobs List GET /job

Parameters

Response Fields

Response Codes

Response Example

Create Job POST /job

Parameters

Response Fields

Response Codes

Response Example

Delete Job DELETE /job/:id

Parameters

Response Fields

Response Codes

Response Example

Workflows

Get Workflow List GET /workflow

Parameters

Response Fields

Response Example

Applications (API Keys)

Get Application GET /application

Response Fields

Response Codes

Response Example

Prepare Upload `GET /upload`

Get Job Information `GET /job/:id`

Get Job Status `GET /job/:id/status`

Get Jobs List `GET /job`

Create Job `POST /job`

Delete Job `DELETE /job/:id`

Get Workflow List `GET /workflow`

Get Application `GET /application`