Skip to content

Start Search (Custom Database)

POST https://search.pex.com/api/v1/private/start-search

Starts an asynchronous search against your private catalog in the Custom Database.

You can query your catalog using either a media file or a pre-generated fingerprint file.

Generating Fingerprints with the CLI

In order to generate fingerprints from audio or video files, you need to use the pexsearch CLI tool. Pre-generating fingerprints locally reduces network bandwidth and speeds up API requests. Learn how to generate fingerprints in the SDK CLI (pexsearch) documentation.

Request

Field Type Required Description
media_file file Conditional Media file to fingerprint and search. Mutually exclusive with fingerprint.
fingerprint file Conditional Pre-generated binary fingerprint file to search. Mutually exclusive with media_file.
fingerprint_type string or array[string] Conditional Type of fingerprint/search signal to use (audio, melody, phonetic, classification). Required when providing media_file. Optional when providing fingerprint.

Info

Input Requirements:

  • Exactly one of media_file or fingerprint is required.
  • media_file and fingerprint are mutually exclusive.
  • Note that isrc is not supported for private searches.

Supported fingerprint_type Values

Value Description
audio Audio fingerprint matching (exact audio recordings)
melody Melody fingerprint matching (cover songs and melodic variations)
phonetic Phonetic/lyrics-style matching
classification Content classification (music, speech, and silence segments)

Examples

import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
FINGERPRINT_PATH = "./query.ft"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}

with open(FINGERPRINT_PATH, "rb") as fp_file:
    response = requests.post(
        "https://search.pex.com/api/v1/private/start-search",
        headers=headers,
        files={
            "fingerprint": fp_file,
        },
    )

response.raise_for_status()

print(response.json())

import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH = "./query.mp3"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}

with open(MEDIA_FILE_PATH, "rb") as media_file:
    response = requests.post(
        "https://search.pex.com/api/v1/private/start-search",
        headers=headers,
        files={
            "media_file": media_file,
        },
        data={
            "fingerprint_type": "audio",
        },
    )

response.raise_for_status()

print(response.json())

ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
FINGERPRINT_PATH="./query.ft"

curl -X POST "https://search.pex.com/api/v1/private/start-search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "fingerprint=@${FINGERPRINT_PATH}"

ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH="./query.mp3"

curl -X POST "https://search.pex.com/api/v1/private/start-search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "fingerprint_type=audio" \
  -F "media_file=@${MEDIA_FILE_PATH}"

Response

A successful request returns a lookup_id used to check for search results.

{
  "lookup_id": "123456789012345678"
}