API Documentation¶

AI Song Detector

The AI Song Detector API lets you check whether an audio file contains AI-generated music.

The submitted audio file must contain music, ideally a single song. Files may be uploaded directly or retrieved from a provided URL. Please avoid files with UGC compilations or other mixed content. See more on the Overview page.

The model produces one prediction for the entire file.

To use the API:

Request an access token via OAuth 2.0 Client Credentials.
Submit an audio file to the detection endpoint, either by uploading it directly or by providing a URL to the file. All common audio file formats are supported.
Receive a JSON result describing whether the file contains AI-generated music.

1. Authentication¶

The API uses OAuth 2.0 Client Credentials. You will need a CLIENT_ID and CLIENT_SECRET.

The generated access token must be included in every request to the detection endpoint.

The access token is valid for 2 hours. Clients should reuse the same token for multiple requests until it expires, rather than requesting a new token for each call. When the token expires, request a new one using the same client credentials.

Token Endpoint¶

POST

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

Auth: HTTP Basic Auth
Body: grant_type=client_credentials

Examples¶

PythonBash

import requests

token_url = "https://api.ae.pex.com/oauth2/token"
auth = ("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

token_resp = requests.post(token_url, data={"grant_type": "client_credentials"}, auth=auth)
token_resp.raise_for_status()
access_token = token_resp.json()["access_token"]

CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"

TOKEN_RESPONSE=$(curl -s  -u "${CLIENT_ID}:${CLIENT_SECRET}"  -d "grant_type=client_credentials"  "https://api.ae.pex.com/oauth2/token")

ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')
echo "Token: $ACCESS_TOKEN"

2. AI Song Detector Endpoints¶

Submit an audio file to the detection endpoint, either by uploading it directly (see file upload endpoint) or by providing a URL to the file (see URL endpoint).

File constraints¶

Supported formats: Most common audio formats (MP3, MP4/M4A, WAV, FLAC, AAC, OGG, WEBM, etc.).
Maximum file size: 100 MB.
Minimum duration: 30 seconds.
Maximum duration: 15 minutes.
Stereo, mono, and variable bitrates are supported.

Files shorter or longer than the limits will return too_short or too_long in the response status. Files containing a lot of silence or non-music parts may return not_enough_music.

Info

The submitted audio file, whether uploaded directly or retrieved from a URL, is processed and immediately discarded. It is never stored on our servers.

2A. AI Song Detector - File Upload Endpoint¶

This endpoint receives a file and returns AI music detector results.

POST

https://api.ae.pex.com/v1/ai-detector/detect

Requirements¶

Authorization: Bearer <access_token>
Content-Type: multipart/form-data
Body: file=@your_audio_file

Examples¶

PythonBash

import requests

url = "https://api.ae.pex.com/v1/ai-detector/detect"
headers = {"Authorization": f"Bearer {access_token}"}

with open("song.mp3", "rb") as f:
    resp = requests.post(url, headers=headers, files={"file": f})

resp.raise_for_status()
print(resp.json())

curl -s  -H "Authorization: Bearer ${ACCESS_TOKEN}"  -F "[email protected]"  "https://api.ae.pex.com/v1/ai-detector/detect"

2B. AI Song Detector - URL Endpoint¶

This endpoint receives a URL from which an audio file is retrieved and analyzed.

The URL must be publicly accessible without authentication and must allow direct file download. If the URL cannot be opened or accessed, the status not_found is returned.

POST

https://api.ae.pex.com/v1/ai-detector/detect-url

Requirements¶

Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded
Body: url=your_audio_file_url

Examples¶

PythonBash

import requests

url = "https://api.ae.pex.com/v1/ai-detector/detect-url"
headers = {"Authorization": f"Bearer {access_token}"}

resp = requests.post(url, headers=headers, data={"url": "https://server/path/song.mp3"})

resp.raise_for_status()
print(resp.json())

curl -s  -H "Authorization: Bearer ${ACCESS_TOKEN}"  -d "url=https://server/path/song.mp3"  "https://api.ae.pex.com/v1/ai-detector/detect-url"

3. Response Format¶

A successful request (HTTP 200 OK) with status ok returns a JSON object such as:

{
  "request_id": 806957142976735233,
  "status": "ok",
  "message": "ok",
  "is_ai": true,
  "ai_score": 0.9992,
  "predicted_model": "suno",
  "predicted_model_score": 0.9723
}

Response Fields¶

Field	Type	Description
`request_id`	integer	Unique ID for this request.
`status`	string	Processing status (see full list below).
`message`	string	Human-readable explanation of the status.
`is_ai`	boolean	Whether the model classifies the song as AI-generated. Present only if `status` is `ok`.
`ai_score`	float	Score [0-1] representing how strongly the model considers the audio to be AI-generated. This is not a calibrated probability and should not be used to override or post-filter the `is_ai` classification. Suitable for sorting or QA across multiple results. Score ranges may change between model releases. Present only if `status` is `ok`.
`predicted_model`	string	Name of the predicted model, e.g. "suno", "udio", etc. Present only if `status` is `ok`. May be `null` even when `is_ai` is `true`, if the detector is not sufficiently confident about the specific AI generation platform.
`predicted_model_score`	float	Score of the predicted model. Present only if `status` is `ok` and `predicted_model` is set.

4. Status Codes¶

status	Description
`ok`	Processing completed successfully. Fields `is_ai` and `ai_score` are provided.
`invalid_file`	The file is not recognized as a valid media file, is corrupted, or the container cannot be parsed.
`no_audio`	The media file is valid, but contains no extractable audio track.
`too_short`	Audio is shorter than 10 seconds.
`too_long`	Audio is longer than 15 minutes.
`not_enough_music`	Audio exists, but does not contain enough music content for reliable classification.
`not_found`	The provided URL could not be opened or the file could not be retrieved.
`error`	Other processing error.

5. HTTP Error Handling¶

The API uses standard error responses:

Status	Retriable	Explanation
200		Request processed. The response body contains a `status` field that may indicate errors (e.g., `invalid_file`, `too_short`).
400	no	Invalid request (missing file or URL, incorrect field name, etc.).
401	yes	Missing or invalid OAuth token. Retry with new token.
413	no	File too large (over 100 MB).
429	yes	Too Many Requests - retry with backoff.
500	yes	Unexpected server error. You may retry if temporary.
502	yes	Bad Gateway. The server may be overloaded - retry with backoff.
503	yes	Service temporarily overloaded - retry with backoff.

Example error response¶

{
  "status": "error",
  "message": "Service temporarily unavailable. Please retry later."
}

6. Full Example¶

This code illustrates how to use both steps (Authentication and use of AI Song Detector Endpoint), including error handling.

Python

import json
import requests
import time

CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

TOKEN_URL = "https://api.ae.pex.com/oauth2/token"
DETECT_URL = "https://api.ae.pex.com/v1/ai-detector/detect"

def get_access_token(client_id, client_secret):
    auth = (client_id, client_secret)
    resp = requests.post(TOKEN_URL, data={"grant_type": "client_credentials"}, auth=auth)
    resp.raise_for_status()
    return resp.json()["access_token"]

def detect_ai_song(access_token, file_name):
    headers = {"Authorization": f"Bearer {access_token}"}

    while True:
        # call AI Song Detector using the file upload endpoint
        with open(file_name, "rb") as f:
            resp = requests.post(DETECT_URL, headers=headers, files={"file": f})

        # Return the result
        if resp.status_code == 200:
            return resp.json()

        # Retry on some errors 
        if resp.status_code in [408, 429, 500, 502, 504, 520, 521, 522, 523, 524]:
            # Log the retryable error
            print(f"HTTP status {resp.status_code}, retrying...")

            # Sleep for 30 seconds
            time.sleep(30)

        else:
            # Raise the non-retryable error 
            resp.raise_for_status()

def main():
    # Get the access token
    access_token = get_access_token(CLIENT_ID, CLIENT_SECRET)

    # Call AI Song Detector
    song_path = "/path/to/your/song.mp3"
    result = detect_ai_song(access_token, song_path)
    # Print the result
    print(json.dumps(result, indent=2))

    # Call AI Song Detector for another song.
    # This shows that the access_token can be reused (it's valid for 2 hours)
    song_path2 = "/path/to/your/another/song2.mp3"
    result = detect_ai_song(access_token, song_path2)
    # Print the result
    print(json.dumps(result, indent=2))

if __name__ == '__main__':
    main()

7. Support¶

If you encounter problems, please contact your Vobile representative and include:

the request_id (if present),
timestamp,
HTTP status code,
the approximate file duration.