Skip to content

Start Search (Advanced Search)

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

Starts an advanced Search lookup using an explicit fingerprint type and search type.

Clients should use this endpoint when they want more granular control over fingerprinting and search configuration.

Request

Field Type Required Description
fingerprint_type string or array[string] Yes Type of fingerprint/search signal to use. Multiple values may be provided when supported.
search_type string Yes Type of search to perform.
media_file file Yes Media file to fingerprint and search.

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.

media_file Info

Each search request requires a media file to be provided using the media_file field.

Endpoints that accept media files use multipart/form-data.

Supported formats generally include any media format supported by FFmpeg.

Please try to keep uploaded files under 100 MB.

Examples

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())

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}"

Response

A successful request returns one lookup_id.

{
  "lookup_id": "123456789012345678"
}