Ingest Asset (Custom Database)¶

Ingest Asset¶

POST https://search.pex.com/api/v1/private/ingest

Ingests a new media asset into your private Custom Database catalog. Once ingested, the asset is indexed and available for matching in private searches.

You can ingest assets by uploading media files directly or by uploading pre-generated binary fingerprints.

Generating Fingerprints with the CLI

To ingest pre-generated fingerprints without uploading raw media files over HTTP, you need to use the pexsearch CLI tool. Pre-generating fingerprints locally drastically reduces upload bandwidth and ingestion time. For detailed instructions, see the SDK CLI (pexsearch) documentation.

Request¶

Field	Type	Required	Description
`provided_id`	string	Yes	Unique identifier for the asset in your catalog (also accepted as `id`).
`media_file`	file	Conditional	Media file to fingerprint and ingest. Mutually exclusive with `fingerprint`.
`fingerprint`	file	Conditional	Pre-generated binary fingerprint file to ingest. Mutually exclusive with `media_file`.
`fingerprint_type`	string or array[string]	Conditional	Type of fingerprint to generate (`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.

Examples¶

Python (Fingerprint)Python (Media File)Bash (Fingerprint)Bash (Media File)

import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
FINGERPRINT_PATH = "./master.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/ingest",
        headers=headers,
        files={
            "fingerprint": fp_file,
        },
        data={
            "provided_id": "my-unique-asset-001",
        },
    )

response.raise_for_status()

print(response.json())

import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH = "./master.wav"

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/ingest",
        headers=headers,
        files={
            "media_file": media_file,
        },
        data={
            "provided_id": "my-unique-asset-001",
            "fingerprint_type": "audio",
        },
    )

response.raise_for_status()

print(response.json())

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

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

ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH="./master.wav"

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

Response¶

A successful ingestion returns an empty JSON object with HTTP status 200.

JSON

{}