> For the complete documentation index, see [llms.txt](https://neuraldefend.gitbook.io/neural-defend/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://neuraldefend.gitbook.io/neural-defend/api-info-for-audio-detection.md).

# API Info - For Audio Detection

## Neural Defend Audio Detection API Examples

**🔗 Endpoint**

```json
https://deepscan.neuraldefend.com/detect/audio
```

### Base curl Command Structure

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--form 'file=@"path/to/your/audio.mp3"'
```

### Scenario 1: Real Audio Detection (Authentic Voice)

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"authentic_voice.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Real Audio",
        "confidence": 0.9456782341234567
    }
}
```

### Scenario 2: AI-Generated Audio Detection (Deepfake Voice)

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"synthetic_voice.wav"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.9990035721566528
    }
}
```

### Scenario 3: Voice Cloning Detection (Celebrity Impersonation)

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"cloned_celebrity_voice.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.8734521098765432
    }
}
```

### Scenario 4: Text-to-Speech Detection

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"tts_generated.wav"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.9876543210987654
    }
}
```

### Scenario 5: Real-Time Voice Conversion

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"voice_converted_realtime.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.9234567890123456
    }
}
```

### Scenario 6: Borderline/Uncertain Detection

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"processed_voice.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Real Audio",
        "confidence": 0.5634521098765432
    }
}
```

### Scenario 7: High-Quality Deepfake

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"high_quality_deepfake.wav"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.7892345678901234
    }
}
```

### Scenario 8: Multiple Speaker Audio

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"conversation_multiple_speakers.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Real Audio",
        "confidence": 0.8345678901234567
    }
}
```

### Scenario 9: No Speech Content Detected

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"instrumental_music.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "No speech content detected for analysis",
        "prediction": null,
        "confidence": null
    }
}
```

### Scenario 10: Poor Audio Quality

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"low_quality_recording.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed with reduced confidence due to audio quality",
        "prediction": "Real Audio",
        "confidence": 0.4567890123456789
    }
}
```

### Scenario 11: Short Audio Duration

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"short_clip.wav"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Audio duration too short for reliable analysis",
        "prediction": "Insufficient Data",
        "confidence": null
    }
}
```

### Scenario 12: Heavily Processed Audio

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"heavily_processed.mp3"'
```

#### Sample Response:

```json
{
    "audio_analysis": {
        "message": "Analysis completed successfully",
        "prediction": "Suspected AI-Generated (or Suspected AI-Manipulated)",
        "confidence": 0.6789012345678901
    }
}
```

### Scenario 13: Corrupted Audio File

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"corrupted_audio.mp3"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "failed",
        "message": "Invalid audio file or corrupted data. Please ensure the file is a valid audio format.",
        "error_code": "INVALID_AUDIO_FORMAT",
        "filename": "corrupted_audio.mp3"
    }
}
```

### Scenario 14: Unauthorized Access (Invalid API Key)

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: invalid_key_123' \
--form 'file=@"sample_audio.mp3"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "unauthorized",
        "message": "Invalid API key or access denied.",
        "error_code": "UNAUTHORIZED_ACCESS",
        "status_code": 403
    }
}
```

### Scenario 15: File Size Limit Exceeded

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"very_large_audio.wav"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "failed",
        "message": "File size exceeds maximum limit of 50MB for audio files.",
        "error_code": "FILE_SIZE_EXCEEDED",
        "filename": "very_large_audio.wav",
        "file_size_mb": 78.9,
        "max_allowed_mb": 50
    }
}
```

### Scenario 16: Unsupported File Format

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"audio_file.wma"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "failed",
        "message": "Unsupported audio format. Please use MP3, WAV, FLAC, AAC, or OGG.",
        "error_code": "UNSUPPORTED_FORMAT",
        "filename": "audio_file.wma",
        "supported_formats": ["MP3", "WAV", "FLAC", "AAC", "OGG"]
    }
}
```

### Scenario 17: Rate Limit Exceeded

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"sample_audio.mp3"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "rate_limited",
        "message": "Rate limit exceeded. Please try again later.",
        "error_code": "RATE_LIMIT_EXCEEDED",
        "retry_after": 60,
        "current_usage": "20/20 per minute"
    }
}
```

### Scenario 18: Server Error

#### Request:

```bash
curl --location 'https://deepscan.neuraldefend.com/detect/audio' \
--header 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--form 'file=@"sample_audio.mp3"'
```

#### Sample Response:

```json
{
    "error": {
        "status": "server_error",
        "message": "Internal server error. Please try again later.",
        "error_code": "INTERNAL_SERVER_ERROR",
        "status_code": 500
    }
}
```

### API Response Codes Summary

| HTTP Code                      | Status            | Description                    |
| ------------------------------ | ----------------- | ------------------------------ |
| **200 OK**                     | ✅ Success         | Request processed successfully |
| **400 Bad Request**            | ⚠️ Invalid Input  | Malformed file or parameters   |
| **403 Forbidden**              | 🔒 Access Denied  | Invalid API key                |
| **413 Payload Too Large**      | 📁 File Too Large | File exceeds size limit        |
| **415 Unsupported Media Type** | 🎵 Invalid Format | Unsupported audio format       |
| **422 Unprocessable Entity**   | 🚫 No Speech      | No speech content detected     |
| **429 Too Many Requests**      | ⏱️ Rate Limited   | Rate limit exceeded            |
| **500 Internal Server Error**  | 🚨 Server Error   | Server-side processing error   |

### Prediction Types

#### **Authentic Audio:**

* `"Real Audio"` - Genuine human voice

#### **AI-Generated/Manipulated:**

* `"Suspected AI-Generated (or Suspected AI-Manipulated)"` - Deepfake detected

#### **Special Cases:**

* `null` - No speech detected or insufficient data
* `"Insufficient Data"` - Too short for analysis

### Confidence Score Interpretation

* **0.0 - 0.3**: High confidence AI-generated/manipulated
* **0.3 - 0.5**: Moderate confidence AI-generated/manipulated
* **0.5 - 0.7**: Moderate confidence real/authentic
* **0.7 - 1.0**: High confidence real/authentic

### Supported Audio Formats

* **MP3** - Most common format
* **WAV** - Uncompressed, highest quality
* **FLAC** - Lossless compression
* **AAC** - Advanced Audio Coding
* **OGG** - Open-source format

### File Requirements

* **Maximum Size**: 500MB
* **Recommended Duration**: 5+ seconds
* **Sample Rate**: 8kHz minimum, 44.1kHz+ recommended
* **Content**: Clear human speech required

### Best Practices

1. **Audio Quality**: Use high-quality recordings with minimal background noise
2. **Duration**: Provide at least 5 seconds of clear speech
3. **Format**: Use uncompressed formats (WAV, FLAC) for best results
4. **Error Handling**: Always check for error responses and handle rate limits
5. **Security**: Protect API keys and use HTTPS

### Common Use Cases

* **Voice Authentication** - Verify speaker identity
* **Content Moderation** - Detect synthetic audio in uploads
* **Media Verification** - Authenticate audio recordings
* **Fraud Prevention** - Identify voice cloning attacks
* **Compliance** - Ensure audio content authenticity


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://neuraldefend.gitbook.io/neural-defend/api-info-for-audio-detection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.