> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.undetectable.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# AI Audio Detector API

# Authentication

Undetectable.AI uses API keys to allow access to the API. You can get your API key at the top of the page in our [developer portal](https://undetectable.ai/develop).

UD expects for the API key to be included in all API requests to the server in a request body that looks like the following:

`key: YOUR API KEY GOES HERE`

|| You must replace `YOUR API KEY GOES HERE` with your personal API key.

# AI Audio Detector

#### Detect (3-Step Process)

The AI Audio Detection workflow consists of the following steps:

* Obtain a Pre-signed Upload URL
* Upload the Audio
* Submit the Audio for Detection

##### 1. Obtain a Pre-signed Upload URL

Begin by requesting a pre-signed URL from the API. This URL allows you to securely upload your audio file to the storage server.

**Supported File Formats:** MP3, WAV, M4A, FLAC, OGG

**Note:** It is necessary to remove spaces from the audio filename when requesting a pre-signed URL.

| **${color}[#0093ee](GET) ** `https://ai-audio-detect.undetectable.ai/get-presigned-url?file_name=example.mp3`

#####  Example Request

```
curl -X GET 'https://ai-audio-detect.undetectable.ai/get-presigned-url?file_name=example.mp3' \
--header 'apikey: YOUR API KEY GOES HERE'
```

#####  Example Response

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

##### 2. Upload the Audio

Use the provided `presigned_url` to upload your audio via a `PUT` request. Ensure the correct content type is set according to your audio format.

#####  Example Request

```
curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT -  mp3, wav, m4a, flac, ogg>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment
```
**Note:** It is necessary to remove spaces from the audio filename when uploading the audio.

Ensure that the file format remains consistent during the upload process. A successful upload will return a status code of `200`.

**File Size Limits:**
* Minimum file size: 1KB
* Maximum file size: 10MB

##### 3. Submit Audio for AI Detection

After uploading, submit the audio for AI detection by referencing the `file_path` from the previous step.

| **${color}[#0093ee](POST) ** `https://ai-audio-detect.undetectable.ai/detect`

#### Example Request

```
curl -X 'POST' \
  'https://ai-audio-detect.undetectable.ai/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'
```
The `FILE_PATH` refers to the path obtained from the response in the initial step, "Obtain a Pre-signed Upload URL".

**Optional Parameters:**
* `analyzeUpToSeconds`: Analyze up to N seconds from the beginning
* `document_type`: Type of document (default: `Audio`)
* `email`: Optional email for processing

#### Example Response

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

The response includes a unique ID for tracking the detection status.
---

#### Query Detection Status and Results

To check the status and retrieve the results, use the `/query` endpoint with the ID.

| **${color}[#0093ee](POST) ** `https://ai-audio-detect.undetectable.ai/query`

#### Example Request

```
curl -X 'POST' \
  'https://ai-audio-detect.undetectable.ai/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "ID-GOES-HERE"
}'
```

#### Example Response

```
{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "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

* **is_valid**: Indicates if the audio file is valid (true/false)
* **message**: Processing message
* **original_duration**: Duration in seconds of the original audio
* **is_truncated**: Whether the audio was truncated for analysis
* **truncated_duration**:  Duration analyzed if truncated
* **mean_ai_prob**: Overall AI probability score
* **individual_chunks_ai_prob**: Per-chunk AI probability scores

The `status` field will be one of:
* `pending`: Processing is queued
* `analyzing`: AI detection is in progress
* `done`: Results are available
* `failed`: Processing failed

---

#### Check User Credits

This endpoint accepts the users apikey via the header. And returns users credit details.

| **${color}[#0093ee](GET) ** `https://ai-audio-detect.undetectable.ai/check-user-credits`

#### Example Request

```
curl -X 'GET' \
  'https://ai-audio-detect.undetectable.ai/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
```

#### Example Response

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

---

#### Health Check

Check the health status of the API server.

| **${color}[#0093ee](GET) ** `https://ai-audio-detect.undetectable.ai/health`

#### Example Request

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

#### Example Response

```
{
    "status": "healthy"
}
```
---

# Errors

|| Most errors will be from incorrect parameters being sent to the API. Double check the parameters of each API call to make sure it's properly formatted, and try running the provided example code.

The generic error codes we use conform to the REST standard:

| Error Code | Meaning |
| ---- |
| 400 | Bad Request -- Your request is invalid. |
| 403 | Forbidden -- The API key is invalid, or there aren't sufficient credits (0.1 per word). |
| 404 | Not Found -- The specified resource doesn't exist. |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't JSON. |
| 410 | Gone -- The resource at this endpoint has been removed. |
| 422 | Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters. |
| 429 | Too Many Requests -- You're sending too many requests! Slow it down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |

# Common Issues and Solutions

## Authentication Issues

### "User verification failed" (403)
* **Cause**: Invalid or expired API key
* **Solution**:

1. Verify your API key is correct
2. Check if your API key is active in your account
3. Try regenerating your API key

### "Not enough credits" (403)
* **Cause**: Insufficient credits for audio processing
* **Solution**:

1. Check your remaining credits using `/check-user-credits`
2. Purchase additional credits if needed

## Input Validation Issues

### "Input URL cannot be empty" (400)
* **Cause**: Empty or invalid URL submitted
* **Solution**:

1. Ensure your url input is not empty
2. Remove any leading/trailing whitespace in audio names
3. Check if url encoding is correct

### "Input email is empty" (400)
* **Cause**: Missing email for URL processing
* **Solution**:

1. Provide a valid email address when submitting URLs
2. Check email format is correct

### "Unsupported audio type" (400)
* **Cause**: File format not supported
* **Solution**:

1. Convert audio to supported format (mp3, m4a, wav, flac, ogg)
2. Check file extension is correct

### "File size is too small" (400)
* **Cause**: Audio file is below minimum size requirement
* **Solution**:

1. Use a larger audio file (minimum 1KB)
2. Check if audio was corrupted during upload

### "File size exceeds limit" (400)
* **Cause**: Audio file is too large
* **Solution**:

1. Compress or resize audio (maximum 10MB)
2. Use a different audio format

### "Invalid file type" (400)
* **Cause**: File type validation failed
* **Solution**:

1. Ensure file is a valid audio format
2. Check file is not corrupted
3. Verify MIME type matches file extension

## Processing Issues

### Audio Status "failed"
* **Cause**: Processing failed for various reasons
* **Solution**:

1. Verify URL is in a supported format
2. Check audio file is valid and not corrupted
3. Ensure audio meets size requirements
4. Contact support if issue persists

### "User not found"
* **Cause**: Invalid user ID
* **Solution**:

1. Verify user ID is correct
2. Ensure user account is active
3. Re-authenticate if needed

### "File metadata could not be fetched" (500)
* **Cause**: Unable to access uploaded file
* **Solution**:

1. Verify file was uploaded successfully
2. Check file URL is accessible
3. Try re-uploading the file

---