Start Search (Advanced Search)

Start 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

Python

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

Bash

Response

A successful request returns one lookup_id.

JSON

{
  "lookup_id": "123456789012345678"
}