Start Search (Advanced Search)¶
Start 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, orisrc) is required. media_file,fingerprint, andisrcare 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 usingmultipart/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"
}