Pex AI Song Detector

Pex AI Song Detector

Classify audio files as AI-generated or human-made music via the Pex AI Song Detector API. The API also identifies the AI generation platform (Suno, Udio, Mureka, Sonauto, ElevenLabs, Boomy, etc.) when possible.

Documentation: https://docs.pex.com/ai-song-detector/overview

Quick facts

• One prediction per file — submit a single song, get one result.
• Two input methods — upload a file directly, or pass a public URL.
• Auth — OAuth 2.0 Client Credentials. Token is valid for 2 hours; reuse it across requests.
• Supported formats — MP3, WAV, FLAC, AAC, M4A/MP4, OGG, WEBM, and other common audio formats.
• Duration limits — minimum 30 seconds, maximum 15 minutes.
• File size limit — 100 MB.
• Privacy — submitted audio is processed and immediately discarded; never stored or used for training.

What the user needs to provide

1. Client credentials — a CLIENT_ID and CLIENT_SECRET issued by Pex. If the user hasn't provided them, ask before proceeding.
2. Audio input — either a local file path or a publicly accessible URL to the audio.

API workflow

Step 1 — Authenticate

POST https://api.ae.pex.com/oauth2/token

• Auth: HTTP Basic Auth with CLIENT_ID / CLIENT_SECRET.
• Body: grant_type=client_credentials (form-encoded).
• Returns: JSON with access_token (valid 2 hours).

Step 2 — Submit audio

Choose the endpoint that matches the input type.

Option A — File upload:

POST https://api.ae.pex.com/v1/ai-detector/detect
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

file=@<path_to_audio_file>

Option B — URL:

POST https://api.ae.pex.com/v1/ai-detector/detect-url
Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded

url=<publicly_accessible_audio_url>

Step 3 — Interpret the response

A successful response (HTTP 200, status: "ok") returns:

Status codes (in status field)

HTTP error codes

Implementation guidance

• Reuse the access token across multiple requests; don't re-authenticate per file.
• Input quality matters — the detector is optimized for single songs. Avoid submitting DJ mixes, mashups, UGC compilations, or audio dominated by speech/silence.
• ai_score is for ranking, not thresholding — rely on the boolean is_ai for the classification decision. Score ranges can shift between model versions.
• See scripts/detect.py for simple API client CLI tool. It can process an arbitrary number of input files or urls.

Batch processing — handling rate limits and auto-scaling correctly

This is the most important section for any agent or pipeline processing multiple files. The API backend auto-scales: it spins up more workers as traffic increases and scales down during inactivity. This means initial requests at high volume will likely hit rate limits (HTTP 429) until the service scales up to meet demand. A naive implementation will fail badly here. Read this section carefully.

The naive mistake (do NOT do this)

A common broken pattern:

1. Send all N files at high concurrency.
2. Some succeed (HTTP 200), many get rate-limited (HTTP 429).
3. Discard all results and retry the entire batch at a lower rate.
4. The service sees lower traffic, scales down capacity.
5. Requests get rate-limited again at the new lower rate.
6. Repeat — the system never converges.

This fails because it re-sends already-successful requests (wasting quota and delaying new work) and the reduced traffic actually signals the backend to reduce capacity, creating a downward spiral.

The correct pattern — persist successes, retry only failures

The right approach has three rules:

1. Store every successful result immediately. When a request returns HTTP 200, persist the result (to a file, database, or in-memory dict keyed by the input identifier). That file is done — never send it again.
2. Retry only the requests that failed. After each pass, build the retry queue from only the items that got a non-200 response (429, 500, 502, 503, etc.).
3. Keep sending at a steady rate with backoff pauses. When you hit a 429, pause briefly (start at ~30 s), then continue with the remaining failed items. Do NOT reduce your target throughput — the transient 429s are the signal that makes the backend scale up. As capacity grows, fewer requests fail, and eventually you reach full throughput.

Pseudocode

results = {}          # key: file_id → value: API response
pending = all_files   # list of files still to process

while pending is not empty:
    failed = []

    for file in pending:
        response = send_request(file)

        if response.status_code == 200:
            results[file.id] = response.json()   # ✅ persist immediately
        elif response.status_code in (429, 500, 502, 503, 504):
            failed.append(file)                   # ⏳ will retry
            sleep(30)                             # back off briefly
        elif response.status_code == 401:
            refresh_token()                       # token expired, re-auth
            failed.append(file)                   # retry this file
        else:
            log_permanent_failure(file, response)  # 400, 413 etc. — won't retry

    pending = failed   # next pass: only the items that did not succeed

save(results)

Why this works

The steady stream of requests (including the ones that get 429'd) tells the backend that demand is real and sustained. The service progressively spins up more workers. Each successive pass through the retry queue encounters fewer 429s because capacity has grown. Successful results accumulate monotonically — no work is ever repeated or lost. The system converges to the maximum processing rate naturally.

Key parameters for agents building batch pipelines

Bundled resources

• scripts/detect.py - Batch CLI processor: processes a directory of audio files with correct retry-only-failures logic, result persistence.
• references/client-code-examples.md - Curl and Python code examples.