AI Detection API

The AI Detection API is designed to help platforms, labels, and developers distinguish AI-generated music from human music. Here are the steps to follow to complete the initial setup:

1. 1. Get in touch

   If you're looking to integrate AI detection capabilities into your platform or workflow, send us an enquiry.

2. 2. Get your API Key

   Once you're registered, you'll receive your API key — a mandatory parameter for all API calls. It's your personal identifier and should be kept secret.

3. 3. Experiment with our interactive documentation

   Open the interactive API docs to explore the endpoints, and to execute requests directly from your browser.

   https://api.soundpatrol.com/docs→

4. 4. Integrate with your product

   With your API key in hand, you can start integrating AI Detection into your platform. Our team is available to assist with your implementation and answer any technical questions.

To authenticate your API requests, you need to include your API key as a header in every call. Add the X-API-Key header to your requests like this:

curl -X POST "https://api.soundpatrol.com/v1/ai-detection" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "audio_file=@song.mp3;type=audio/mpeg"

Keep your API key secure and never share it publicly. If you believe your API key has been compromised, contact us immediately to revoke and reissue your credentials.

You can upload audio directly or submit a public HTTPS URL. URL submission is useful for server-to-server pipelines where the audio is already hosted: SoundPatrol fetches and validates the file, then returns the same pending response and request_id used by the upload flow.

curl -X POST "https://api.soundpatrol.com/v1/ai-detection/from-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://cdn.example.com/audio/track.mp3", "title": "Song", "artist": "Artist"}'

The audio_url must be publicly reachable over HTTPS and point to a supported audio file. Private, loopback, link-local, reserved, and metadata-network destinations are blocked at every redirect. Embedded URL credentials are not accepted. Each file may be at most 150 MiB and must finish downloading within 90 seconds; the result and polling contract is identical to direct upload.

Use the asynchronous batch resource when you need to submit a related bundle in one call. The API validates the complete request, records it durably, and returns 202 Accepted without waiting for the audio files to download. Each item then fetches and analyzes independently.

Each batch may contain up to 100 items, provided the complete batch fits within your remaining rate-limit allowance. Every item counts as one submission in each configured quota window. Accepted items are durably queued and processed with bounded concurrency, so the batch size does not imply that every analysis runs simultaneously. Every item has the same 150 MiB media limit and 90-second fetch deadline as single-URL submission. Source URLs are never returned by the status endpoint.

curl -X POST "https://api.soundpatrol.com/v1/ai-detection/batches/from-urls" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: release-42" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"audio_url":"https://cdn.example.com/track-01.flac","client_reference":"track-01","title":"Track 01","artist":"Artist"}]}'

Idempotency-Key is required. Replaying the same key and body returns the original batch without consuming more quota; reusing a key with a different body returns 409. Items can complete or fail independently. A terminal batch containing any failed item — including a batch where every item failed — has status "completed_with_errors".

Submit by direct upload or single URL and poll the request, or submit a URL batch and poll the batch resource:

• POST
  /v1/ai-detection

  Submit an audio file for analysis (multipart form: audio_file, plus optional title, artist, and isrc). Returns immediately with status "pending" and a request_id — detection runs asynchronously.

• POST
  /v1/ai-detection/from-url

  Submit a JSON body containing audio_url and optional metadata. SoundPatrol fetches the file and returns the same pending response as direct upload.

• GET
  /v1/ai-detection/{request_id}

  Poll for results. The status field transitions to "completed" (with a result object) or "failed". Polling is free and does not count toward your usage.

• POST
  /v1/ai-detection/batches/from-urls

  Submit 1–100 public HTTPS URLs with a required Idempotency-Key and optional unique client_reference per item. Returns 202 with a batch_id; accepted items are durably queued for bounded asynchronous processing.

• GET
  /v1/ai-detection/batches/{batch_id}

  Poll aggregate counts and item-level states/results. The response preserves request order and never echoes audio_url. Items progress independently through queued, fetching, processing, completed, or failed.

When a request completes, the result object contains the following fields:

1. 1. is_ai

   The binary AI/human verdict at the default operating point. This is the headline call; combine it with confidence_score to prioritize review.

2. 2. ai_prediction_score

   A score from 0.0 to 1.0 — higher values indicate stronger model evidence that the track is AI-generated. Use this field to tune your own operating threshold: raise it for high-precision automated actions, lower it for high-recall sweeps feeding manual review. The default threshold used to determine is_ai is 0.50.

3. 3. confidence_score

   A calibrated 0–99 confidence in the binary verdict. It is directionless — it measures how confident the model is in the call it made, not which way the call went. Use it to rank uncertain rows for human review.

4. 4. model_type

   An allowlisted public provider or family label. Recognized values include suno, udio, riffusion, mureka, ace-step, elevenlabs, sonauto, stable-audio, lyria, loudly, diff-rhythm, heartmula, mubert, musicgen, yue, boomy, rvc, musicfy, and AI Voice Clone. Internal dataset labels, human-source slices, unknown values, and experimental model names are suppressed. Provider naming and reliability are separate: treat model_type as supporting evidence, not proof of origin; is_ai is the binary verdict.

5. 5. super_class

   The AI class bucket: "generative_ai" (wholesale generation) or "vocal_ai" (voice clone / vocal synthesis). This field is empty for human results and is useful for routing enforcement workflows.

6. 6. ai_detector_model_version

   The public detector recipe that produced this result. The July 2026 release returns "advanced_ai_detection_1.1". Store it with results so repeated submissions can be compared across detector upgrades.

7. 7. ai_probability (deprecated)

   A backward-compatible alias of ai_prediction_score. It remains present during the transition, but new integrations should read ai_prediction_score.

The analysis_type request field ("simple"/"detailed") is deprecated and ignored — every request runs the full advanced detection pipeline. It remains accepted for backward compatibility. Existing /v1 fields are not renamed, removed, or given a new meaning without advance notice and an extended transition window.

This additive integration package is AI Detection API v1.2; routes remain under the stable /v1 interface. ai_detector_model_version identifies the public detector recipe used for a result. Internal checkpoint names such as MuQ v4.3 are implementation details, not API versions.

Detector improvements can change a score for the same content while preserving field meanings. Store ai_detector_model_version whenever you compare repeated submissions or audit a historical decision.

Content classification and Audio Tagger enrichment are not part of this release. They are being evaluated separately so optional metadata cannot become a latency or availability dependency for the AI/human verdict.

Rate limits are provisioned per customer as a combination of requests-per-day and requests-per-minute limits. When you exceed a window, the API responds with HTTP 429 and a Retry-After header indicating how many seconds to wait; the daily window resets at 00:00 UTC. Rejected requests do not count toward your limits.

Every item in a batch counts as one submission in every configured quota window, including burst, per-minute, daily, and monthly limits. The complete batch is rejected atomically if its item count cannot be admitted, so a per-minute limit below 100 also lowers the largest batch you can submit at that moment. An idempotent replay does not consume quota again.

Every detection response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers describing your most restrictive window, so you can track usage in real time.

Need different limits? Contact us — per-customer changes typically apply within minutes.

Prefer the highest-quality source already available. Lossy compression can affect prediction and confidence scores, so do not assume an MP3 and its WAV or FLAC source will always produce identical results. You do not need to transcode a file solely for the API.

When both full mixes and isolated stems are available, submit the full mix — detection is calibrated on complete tracks. Treat spoken-word results as candidates for review while we continue characterizing that content type.

We can't wait to see how you'll use the AI Detection API!