Authentication

Undetectable.AI uses API keys to authenticate access to the API. You can obtain your API key from the developer portal.

Authentication requests follow a standard convention based on the HTTP method:

• GET & Query Endpoints: Pass your API key in the request header using apikey: YOUR_API_KEY.
• POST Endpoints: Pass your API key inside the JSON request body using "key": "YOUR_API_KEY".

Example Header Authentication (GET / Query)

Bash

curl -X GET 'https://ai-audio-detect.undetectable.ai/check-user-credits' \
  -H 'apikey: YOUR_API_KEY' \
  -H 'accept: application/json'

Example Body Authentication (POST)

JSON

{
  "key": "YOUR_API_KEY",
  "url": "https://ai-audio-detector-prod.nyc3.digitaloceanspaces.com/uploads/example.mp3",
  "document_type": "Audio"
}

Supported Requirements

• Supported Formats: MP3, WAV, M4A, FLAC, OGG
• File Size Limits: Minimum 1 KB, Maximum 10 MB
• Analysis Duration: Analyzes up to 60 seconds from the beginning by default (customizable via analyzeUpToSeconds)
• Filename Formatting: File names must not contain spaces or unencoded special characters. Replace spaces with underscores (_) or hyphens (-) before requesting a pre-signed URL.
• • ❌ Incorrect: my sample voice note.mp3
  • ✅ Correct: my_sample_voice_note.mp3

Processing Modes

The API supports two distinct modes for submitting audio for detection:

1. Mode A: S3 Pre-signed Upload (Recommended) — Request a pre-signed S3 URL, upload your local file, and pass the generated file_path to the /detect endpoint.
2. Mode B: Direct Public URL — Pass any publicly accessible HTTP/HTTPS audio link directly in the "url" field of the /detect endpoint, alongside a required "email" field.

AI Audio Detector Workflow

1. Obtain a Pre-signed Upload URL

For local file uploads (Mode A), start by requesting a pre-signed upload URL.

GET [https://ai-audio-detect.undetectable.ai/get-presigned-url](https://ai-audio-detect.undetectable.ai/get-presigned-url)

Request Example

Bash

curl -X GET 'https://ai-audio-detect.undetectable.ai/get-presigned-url?file_name=my_sample_voice_note.mp3' \
  -H 'apikey: YOUR_API_KEY'

Response Example

JSON

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20261008-121955_my_sample_voice_note.mp3...",
  "file_path": "https://ai-audio-detector-prod.nyc3.digitaloceanspaces.com/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20261008-121955_my_sample_voice_note.mp3"
}

2. Upload the Audio File

Use the presigned_url returned from Step 1 to upload your audio file using an HTTP PUT request. Ensure that the Content-Type header matches your audio format.

Request Example

Bash

curl -X PUT '<PRESIGNED_URL>' \
  -H 'Content-Type: audio/mpeg' \
  -H 'x-amz-acl: private' \
  --data-binary '@my_sample_voice_note.mp3'

3. Submit Audio for AI Detection

Once uploaded (or when using a direct public URL), submit the audio location to queue the detection process.
POST [https://ai-audio-detect.undetectable.ai/detect](https://ai-audio-detect.undetectable.ai/detect)

Request Example

Bash

curl -X POST 'https://ai-audio-detect.undetectable.ai/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_API_KEY",
    "url": "https://ai-audio-detector-prod.nyc3.digitaloceanspaces.com/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20261008-121955_my_sample_voice_note.mp3",
    "document_type": "Audio",
    "analyzeUpToSeconds": 60,
    "email": "user@example.com"
  }'

Request Parameters

• key (required, string): Your API key.
• url (required, string): S3 file_path from Step 1 or a direct public HTTP/HTTPS audio URL.
• document_type (optional, string): Document type (default: "Audio").
• analyzeUpToSeconds (optional, integer): Maximum seconds to analyze from the beginning (default: 60).
• email (optional/required for Mode B, string): User email associated with direct URL processing.

Response Example

JSON

{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
  "status": "pending"
}

JSON Response Schema (/detect)

JSON

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "status": { "type": "string", "enum": ["pending", "analyzing"] }
  },
  "required": ["id", "status"]
}

Polling Query & Detection Status

Because audio analysis is performed asynchronously, you must poll the /query endpoint using the id returned from Step 3 until processing finishes.
POST [https://ai-audio-detect.undetectable.ai/query](https://ai-audio-detect.undetectable.ai/query)

Status Lifecycle

• pending: Request is queued for processing.
• analyzing: AI model is running detection analysis.
• done: Analysis completed successfully; results are available.
• failed: Analysis failed (see error logs or verify audio input).

Request Example

Bash

curl -X POST 'https://ai-audio-detect.undetectable.ai/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
  }'

Response Example (status: "done")

JSON

{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
  "status": "done",
  "result": 0.873,
  "result_details": {
    "is_valid": true,
    "message": "processed",
    "original_duration": 123.45,
    "is_truncated": true,
    "truncated_duration": 60.0,
    "mean_ai_prob": 0.873,
    "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
  }
}

Result Details Breakdown

• is_valid (boolean): Confirms if the audio file format and contents were valid.
• message (string): Execution message (e.g., "processed").
• original_duration (number): Total duration of the uploaded file in seconds.
• is_truncated (boolean): True if audio exceeded analyzeUpToSeconds and was trimmed.
• truncated_duration (number): Actual duration in seconds analyzed by the model.
• mean_ai_prob (number): Overall estimated AI probability score (0.0 to 1.0).
• individual_chunks_ai_prob (array of numbers): AI probability scores for each analyzed segment.

JSON Result Schema (/query when status: "done")

JSON

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "status": { "type": "string", "enum": ["done", "failed"] },
    "result": { "type": "number", "description": "Overall AI probability between 0.0 and 1.0" },
    "result_details": {
      "type": "object",
      "properties": {
        "is_valid": { "type": "boolean" },
        "message": { "type": "string" },
        "original_duration": { "type": "number" },
        "is_truncated": { "type": "boolean" },
        "truncated_duration": { "type": "number" },
        "mean_ai_prob": { "type": "number" },
        "individual_chunks_ai_prob": {
          "type": "array",
          "items": { "type": "number" }
        }
      },
      "required": ["is_valid", "message", "mean_ai_prob", "individual_chunks_ai_prob"]
    }
  },
  "required": ["id", "status", "result", "result_details"]
}

Utility Endpoints

Check User Credits

Retrieve account credit balance information.
GET [https://ai-audio-detect.undetectable.ai/check-user-credits](https://ai-audio-detect.undetectable.ai/check-user-credits)

Request Example

Bash

curl -X GET 'https://ai-audio-detect.undetectable.ai/check-user-credits' \
  -H 'apikey: YOUR_API_KEY' \
  -H 'accept: application/json'

Response Example

JSON

{
  "baseCredits": 10000,
  "boostCredits": 1000,
  "credits": 11000
}

Field Descriptions

• baseCredits: Recurring monthly subscription quota.
• boostCredits: One-time purchased or bonus add-on credits.
• credits: Total active credit balance available (baseCredits + boostCredits).

Health Check

Verify operational availability of the API servers.
GET [https://ai-audio-detect.undetectable.ai/health](https://ai-audio-detect.undetectable.ai/health)

Request Example

Bash

curl -X GET 'https://ai-audio-detect.undetectable.ai/health' \
  -H 'accept: application/json'

Response Example

JSON

{
  "status": "healthy"
}

Error Handling

Updated on: 08/10/2026