API reference

Analysis results

2 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

GET/v1/audio/{audioId}/analyses

List the finished analyses of a file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the analyses that are finished for one of your files: for each, its category and the stored summary. Analyses that are still running or failed are not listed (the library list shows them as pending or failed). A file with no finished analysis answers an empty list. A file that is not yours, does not exist or is in the trash is 404 not_found. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait. Success is { data } without meta.

Cost. Free of charge.

AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/analyses" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.

Response fields

Field	Type	Description
audio_id	string	Registry identifier of the file.
analyses	array<object>	The finished analyses.
analyses[].category	string	The kind of analysis, for example `rhythm` or `spectral`.
analyses[].summary	any	The stored result of that analysis. Its keys depend on the category. Left out when `include_summaries=false`.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The file does not exist, is in the trash, or is not yours.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "audio_id": "audio_3f9c1a7d2b60",
    "analyses": [
      {
        "category": "rhythm",
        "summary": {
          "tempo": {
            "bpm": 119.8
          }
        }
      }
    ]
  }
}

200 The finished analyses of the file.
401 Missing, malformed, unknown or revoked API key.
404 The file does not exist, is in the trash, or is not yours.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/{audioId}/midi

Download the MIDI file of a melody analysis

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the melody that the melody analysis found in one of your files as a standard MIDI file. The response body is the file itself (Content-Type: audio/midi) with a Content-Disposition: attachment header. Send name to choose the file name it is saved under; without it the name is the file id with .mid. A file with no melody analysis, an analysis without MIDI, or a file that is not yours is 404 midi_not_found. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait.

Cost. Free of charge. The melody analysis that creates the MIDI is billed when you run it.

AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/midi" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  --fail \
  -o output.mid

Parameters

Name	Type	Required	Description
audioIdpath	string	Required	The `audio_id` or the file id of one of your files.
namequery	string	Optional	File name to save the download under. The `.mid` extension is added when missing.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	midi_not_found	The file has no melody analysis with a MIDI export, or it is not yours.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

Binary file
Content-Type: audio/midi

200 The MIDI file. The body is binary, not JSON.
401 Missing, malformed, unknown or revoked API key.
404 The file has no melody analysis with a MIDI export, or it is not yours.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

This operation returns a stream or a file, which the response panel cannot show. Use the cURL sample.

Other error codes this operation can return: db_unavailable, invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.