Name: TriadMusic CNN-LSTM Chord Detection API
Brand: magicapi
SKU: api-magicapi-chord-detection-api-triadmusic-chord-detection-cnn-lstm
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎸 Chord Detection API (TriadMusic Chord Detection CNN-LSTM)

## Overview
Chord Detection CNN-LSTM by TriadMusic is a neural network that recognizes the chords in a piece of music. Send an `audio` file and it returns a timeline of chord segments, each with a chord label and its start and end time in seconds.

Choose the set of chord labels the model can use with `chord_vocabulary`, and set `return_lab_file` to `true` to also get a downloadable `.lab` file.

## Features
- **Chord timeline**: `chord_segments` lists every chord with `chord`, `start_time` and `end_time` (seconds).
- **No-chord detection**: stretches without a chord, such as silence at the start, are labelled `N`.
- **Chord vocabularies**: `submission` (default), `ismir2017`, `full` and `extended`.
- **Summary fields**: the output also reports `audio_duration`, `num_segments`, `num_unique_chords` and the `chord_vocabulary` used.
- **.lab file**: set `return_lab_file` to `true` to receive a downloadable `.lab` file in addition to the JSON output.
- **Common audio formats**: mp3, wav, flac and other audio files, sent as a URL.

## Use Cases
1. **Chord charts**: generate the chord progression of a recording for musicians to play along.
2. **Music learning apps**: show the current chord in time with playback.
3. **Music analysis**: compare chord progressions across tracks or find the key changes in a song.
4. **Annotation datasets**: create time-aligned chord labels, including `.lab` files, for music information retrieval work.

## Visual Examples
### Example Input
An 8-second instrumental clip: [Listen to the example input](https://blog.api.market/wp-content/uploads/2026/10/musicgen-output-b7py4df3-api-market.mp3)

```json
{
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/musicgen-output-b7py4df3-api-market.mp3",
  "return_lab_file": false,
  "chord_vocabulary": "submission"
}
```

### Example Output
```json
{
  "audio_duration": 8,
  "chord_segments": [
    { "chord": "N", "start_time": 0, "end_time": 0.023219954648526078 },
    { "chord": "C:maj", "start_time": 0.023219954648526078, "end_time": 3.575873015873016 },
    { "chord": "Bb:maj", "start_time": 3.575873015873016, "end_time": 7.732244897959184 },
    { "chord": "F:maj", "start_time": 7.732244897959184, "end_time": 8.010884353741497 }
  ],
  "chord_vocabulary": "submission",
  "num_segments": 4,
  "num_unique_chords": 4
}
```

The clip plays C major, then B flat major, then F major; the first 0.02 seconds are labelled `N` (no chord).

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `audio` | string (URL) | Yes |  |  | Audio file for chord recognition (mp3, wav, flac, etc.) |
| `chord_vocabulary` | string | No | `submission` | `submission`, `ismir2017`, `full`, `extended` | Chord vocabulary to use for recognition |
| `return_lab_file` | boolean | No | `false` |  | Return a downloadable .lab file in addition to JSON output |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0014 per API unit.
- **1 API unit = 1 request with up to 5 seconds of processing.** A request that processes for longer bills one more unit for each started 5-second block (for example, 8 seconds of processing is 2 units, $0.0028).
- **Example cost**: the example request above processed for 2.8 seconds: 1 unit, $0.0014.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/chord-detection-api-triadmusic-chord-detection-cnn-lstm`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/chord-detection-api-triadmusic-chord-detection-cnn-lstm/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "be95be0303fd42000c413aec595922499f8b946d65416f31fb0034c2daf81f19",
    "input": {
      "audio": "https://blog.api.market/wp-content/uploads/2026/10/musicgen-output-b7py4df3-api-market.mp3",
      "return_lab_file": false,
      "chord_vocabulary": "submission"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "xtn5pdw1p9rgc0d1mvpr60qwwc",
  "version": "be95be0303fd42000c413aec595922499f8b946d65416f31fb0034c2daf81f19",
  "status": "starting",
  "created_at": "2026-11-04T14:19:05.522Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/chord-detection-api-triadmusic-chord-detection-cnn-lstm/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "xtn5pdw1p9rgc0d1mvpr60qwwc",
  "status": "succeeded",
  "output": {
    "audio_duration": 8,
    "chord_segments": [
      { "chord": "N", "end_time": 0.023219954648526078, "start_time": 0 },
      { "chord": "C:maj", "end_time": 3.575873015873016, "start_time": 0.023219954648526078 },
      { "chord": "Bb:maj", "end_time": 7.732244897959184, "start_time": 3.575873015873016 },
      { "chord": "F:maj", "end_time": 8.010884353741497, "start_time": 7.732244897959184 }
    ],
    "chord_vocabulary": "submission",
    "num_segments": 4,
    "num_unique_chords": 4
  },
  "error": null,
  "created_at": "2026-11-04T14:19:05.522Z",
  "started_at": "2026-11-04T14:20:31.839Z",
  "completed_at": "2026-11-04T14:20:34.591Z"
}
```

`output` is a JSON object: `chord_segments` is the list of chords in time order, `audio_duration` is the clip length in seconds, and `num_segments` and `num_unique_chords` count the segments and distinct chords.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `audio` or a `chord_vocabulary` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why, for example an audio URL that cannot be downloaded. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/chord-detection-api-triadmusic-chord-detection-cnn-lstm";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "be95be0303fd42000c413aec595922499f8b946d65416f31fb0034c2daf81f19", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/musicgen-output-b7py4df3-api-market.mp3",
  "return_lab_file": false,
  "chord_vocabulary": "submission"
}).then((output) => {
  for (const segment of output.chord_segments) {
    console.log(`${segment.start_time.toFixed(2)}s - ${segment.end_time.toFixed(2)}s: ${segment.chord}`);
  }
});
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/chord-detection-api-triadmusic-chord-detection-cnn-lstm"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "be95be0303fd42000c413aec595922499f8b946d65416f31fb0034c2daf81f19", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "audio": "https://blog.api.market/wp-content/uploads/2026/10/musicgen-output-b7py4df3-api-market.mp3",
    "return_lab_file": False,
    "chord_vocabulary": "submission"
})
for segment in output["chord_segments"]:
    print(f"{segment['start_time']:.2f}s - {segment['end_time']:.2f}s: {segment['chord']}")
```

## FAQ
- **Which audio formats can I send?**
  - mp3, wav, flac and other common audio files, sent as a URL in `audio`.
- **What does the chord label `N` mean?**
  - No chord: a stretch where the model hears no chord, such as silence at the start of the clip.
- **Which chord vocabulary should I use?**
  - Start with the default `submission`. The other values, `ismir2017`, `full` and `extended`, change the set of chord labels the model can output.
- **Can I get a .lab file?**
  - Yes. Set `return_lab_file` to `true` and the response also includes a downloadable `.lab` file next to the JSON output.
- **What does one request cost?**
  - $0.0014 for each started 5 seconds of processing. The 8-second example processed in 2.8 seconds and cost one unit, $0.0014.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, check that the audio URL is reachable, and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page.


Recognize the chords in mp3, wav or flac audio with TriadMusic's CNN-LSTM model and get time-stamped chord segments as JSON. $0.0014 per request, pay as you go.