Skip to content

Start Search (Advanced Search)

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

Starts an advanced Search lookup against the Vobile Music Registry using an explicit fingerprint type and search type.

Clients should use this endpoint when they want more granular control over fingerprinting and search configuration. Queries can be initiated using a media file, a pre-generated binary fingerprint, or an ISRC.

Generating Fingerprints with the CLI

In order to generate fingerprints from audio or video files, you need to use the pexsearch CLI tool. Generating fingerprints locally avoids transmitting large media files over HTTP and speeds up API processing. For instructions on installing and running the CLI, see the SDK CLI (pexsearch) documentation.

Request

Field Type Required Description
search_type string Yes Type of search to perform (identify_music or find_matches).
fingerprint_type string or array[string] Conditional Type of fingerprint/search signal to use. Required when using media_file or isrc. Optional when using fingerprint.
media_file file Conditional Media file to fingerprint and search. Mutually exclusive with fingerprint and isrc.
fingerprint file Conditional Pre-generated binary fingerprint file to search. Mutually exclusive with media_file and isrc.
isrc string Conditional International Standard Recording Code to query directly. Mutually exclusive with media_file and fingerprint.

Info

Input Requirements:

  • Exactly one query input (media_file, fingerprint, or isrc) is required.
  • media_file, fingerprint, and isrc are mutually exclusive.

Supported fingerprint_type Values

fingerprint_type tells the system which fingerprints to use for the search.

Value Description
audio Audio fingerprint matching (used for identifying matches to assets that share the same sound recording elements)
melody Melody fingerprint matching (used for identifying matches to assets that share the same underlying melodic structure)
phonetic Phonetic/lyrics-style matching (used for identifying matches to assets that share the same underlying phonetic or lyrical structure)
classification Content classification fingerprinting (used for classifying content into music, speech and silence segments)

Multiple fingerprint types may be provided when supported by the selected workflow.

Supported search_type Values

search_type determines the type of search to perform.

Value Description
identify_music Identify the most relevant canonical assets contained within a query file. This search type is optimized for music detection and identification workflows.
find_matches Returns all matching usages identified for the provided fingerprint types. This search type is optimized for usage discovery and rights monitoring workflows.

Input Sources

  • media_file: Accepts files using multipart/form-data. Supported formats include standard media formats supported by FFmpeg. Please keep uploaded files under 100 MB.
  • fingerprint: Accepts raw binary fingerprint files generated using the SDK CLI (pexsearch).
  • isrc: Performs an identification lookup directly against the registry for the specified ISRC.

Examples

import requests

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

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

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

response.raise_for_status()

print(response.json())
import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH = "./example.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/search/start-search",
        headers=headers,
        files={
            "media_file": media_file,
        },
        data={
            "fingerprint_type": "audio",
            "search_type": "identify_music",
        },
    )

response.raise_for_status()

print(response.json())
import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

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

response = requests.post(
    "https://search.pex.com/api/v1/search/start-search",
    headers=headers,
    data={
        "fingerprint_type": "audio",
        "search_type": "identify_music",
        "isrc": "USRC12345678",
    },
)

response.raise_for_status()

print(response.json())
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
FINGERPRINT_PATH="./example.ft"

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

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

curl -X POST "https://search.pex.com/api/v1/search/start-search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "fingerprint_type=audio" \
  -F "search_type=identify_music" \
  -F "isrc=USRC12345678"

Response

A successful request returns one lookup_id.

{
  "lookup_id": "123456789012345678"
}