API reference

Similar sounds

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

Jump to an operation

POST/v1/audio/library/similar

Find files that sound like a file or a link

Free and paid accounts

API key required
Free and paid accounts
No token cost

Same search as the GET route, with the reference given in the body: send exactly one of audio_id or reference_url (the address of one of your files, as in an audio_url). The reference file needs a sound fingerprint (the embedding analysis). A file you own without one is 409 embedding_missing; a file that does not exist or is not yours is 404 audio_not_found. A reference_url that is not one of your files is 404 audio_not_found. limit is a whole number from 1 to 100 (default 20); min_score is a number from -1 to 1 (default -1, which keeps everything). The search compares only your own files and is exact, so on a large library it can take a moment. Any field the route does not know is 400 invalid_config; neither or both references is 400 invalid_reference.

Cost. Free of charge. The embedding analysis that creates a fingerprint is billed when you run it.

curl -X POST "https://api.scarleta.ai/v1/audio/library/similar" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_3f9c1a7d2b60",
    "limit": 10,
    "min_score": 0.5
  }'

Request body

Name	Type	Required	Description
audio_idbody	string	Optional	The `audio_id` or file id of the reference file. Send this or `reference_url`.
reference_urlbody	string	Optional	The address of the reference file in your library. Send this or `audio_id`.
limitbody	integer	Optional	How many results to return, 1 to 100. Defaults to 20.
min_scorebody	number	Optional	Leave out files scoring below this, -1 to 1. Defaults to -1.

Response fields

Field	Type	Description
reference_audio_id	string	The file the search compared against.
embedding_model	string	Name of the fingerprint kind that was compared. Only files with a fingerprint of the same kind can match.
results	array<object>	Your most similar files, best first. The reference itself is never listed.
results[].audio_id	string	Registry identifier of the similar file; it starts with `audio_`.
results[].original_filename	string	Name the file was uploaded under.
results[].display_name	string \| null	Name you gave the file, or null.
results[].similarity_score	number	How alike the sound is, from -1 to 1, to four decimals. Higher is closer.
results[].bpm	number \| null	Tempo of the file, or null when it has none.
results[].key_label	string \| null	Musical key of the file, for example `A minor`, or null.
results[].analyzed_categories	array<string>	Analysis categories this file has results for.
count	integer	Entries in `results`. Allowed: -9007199254740991 to 9007199254740991.
note	string	A fixed sentence on what similarity means.

Errors

Status	Code	Description
400	invalid_reference	The body is not valid JSON (`invalid_json`), has an unknown field (`invalid_config`), does not name exactly one reference (`invalid_reference`), or `limit` / `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	audio_not_found	The reference file does not exist in your library.
409	embedding_missing	The reference file has no sound fingerprint yet.
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": {
    "reference_audio_id": "audio_3f9c1a7d2b60",
    "embedding_model": "fingerprint-6144",
    "results": [
      {
        "audio_id": "audio_a81e5c40d7f2",
        "original_filename": "demo-mix-2.wav",
        "display_name": null,
        "similarity_score": 0.9312,
        "bpm": 119.8,
        "key_label": "A minor",
        "analyzed_categories": [
          "rhythm",
          "embedding"
        ]
      }
    ],
    "count": 1,
    "note": "Similarity is acoustic character (timbre/texture), not structural or temporal match."
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The closest files, best first.
400 The body is not valid JSON (`invalid_json`), has an unknown field (`invalid_config`), does not name exactly one reference (`invalid_reference`), or `limit` / `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).
401 Missing, malformed, unknown or revoked API key.
404 The reference file does not exist in your library.
409 The reference file has no sound fingerprint yet.
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_config, invalid_json, invalid_key_format, invalid_limit, invalid_min_score, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/audio/library/similar/{audio_id}

Find files that sound like one of yours

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the files in your library whose sound is closest to the file named in the path (audio_id or the file id). The reference file needs a sound fingerprint (the embedding analysis). A file you own without one is 409 embedding_missing; a file that does not exist or is not yours is 404 audio_not_found. limit is a whole number from 1 to 100 (default 20); min_score is a number from -1 to 1 (default -1, which keeps everything). The search compares only your own files and is exact, so on a large library it can take a moment. A bad limit is 400 invalid_limit, a bad min_score 400 invalid_min_score. If the database is briefly unavailable the route answers 503 db_unavailable; retry after a short wait.

Cost. Free of charge. The embedding analysis that creates a fingerprint is billed when you run it.

AUDIO_ID="YOUR_AUDIO_ID"
curl "https://api.scarleta.ai/v1/audio/library/similar/$AUDIO_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
audio_idpath	string	Required	The `audio_id` or file id of the reference file.
limitquery	integer	Optional	How many results to return, 1 to 100. Defaults to 20.
min_scorequery	number	Optional	Leave out files scoring below this, -1 to 1. Defaults to -1.

Response fields

Field	Type	Description
reference_audio_id	string	The file the search compared against.
embedding_model	string	Name of the fingerprint kind that was compared. Only files with a fingerprint of the same kind can match.
results	array<object>	Your most similar files, best first. The reference itself is never listed.
results[].audio_id	string	Registry identifier of the similar file; it starts with `audio_`.
results[].original_filename	string	Name the file was uploaded under.
results[].display_name	string \| null	Name you gave the file, or null.
results[].similarity_score	number	How alike the sound is, from -1 to 1, to four decimals. Higher is closer.
results[].bpm	number \| null	Tempo of the file, or null when it has none.
results[].key_label	string \| null	Musical key of the file, for example `A minor`, or null.
results[].analyzed_categories	array<string>	Analysis categories this file has results for.
count	integer	Entries in `results`. Allowed: -9007199254740991 to 9007199254740991.
note	string	A fixed sentence on what similarity means.

Errors

Status	Code	Description
400	invalid_limit	`limit` or `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	audio_not_found	The reference file does not exist in your library.
409	embedding_missing	The reference file has no sound fingerprint yet.
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": {
    "reference_audio_id": "audio_3f9c1a7d2b60",
    "embedding_model": "fingerprint-6144",
    "results": [
      {
        "audio_id": "audio_a81e5c40d7f2",
        "original_filename": "demo-mix-2.wav",
        "display_name": null,
        "similarity_score": 0.9312,
        "bpm": 119.8,
        "key_label": "A minor",
        "analyzed_categories": [
          "rhythm",
          "embedding"
        ]
      }
    ],
    "count": 1,
    "note": "Similarity is acoustic character (timbre/texture), not structural or temporal match."
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The closest files, best first. The list is empty when no other file has a fingerprint of the same kind.
400 `limit` or `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).
401 Missing, malformed, unknown or revoked API key.
404 The reference file does not exist in your library.
409 The reference file has no sound fingerprint yet.
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

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