> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurigin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Audio

> Detect AI-generated audio with real-time deepfake analysis

## Overview

The `/predict` endpoint analyzes audio files for AI-generated content (deepfakes, voice cloning, text-to-speech). Returns results in real-time for small files.

<Note>
  **File Size Limits:** For very large files (100MB+), use pre-signed S3 URLs for asynchronous processing.
</Note>

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your API key for authentication
</ParamField>

## Request Parameters

<ParamField body="file" type="file" required>
  Audio or video file to analyze

  **Supported formats:** WAV, MP3, AAC, FLAC, OGG, M4A, MP4, MOV, AVI, MKV

  **Max size:** 5 MB (recommended for fastest processing)
</ParamField>

<ParamField body="device" type="string" required>
  Device type making the request

  **Options:** `macos`, `windows`, `web_app`, `api`
</ParamField>

<ParamField body="prediction_id" type="string">
  Custom prediction ID for tracking (auto-generated if not provided)

  **Format:** `pred_` followed by 12 hex characters

  **Example:** `pred_9b6ff057a7f7`
</ParamField>

<ParamField body="model" type="string" default="stable">
  Model version to use

  **Options:**

  * `stable` - Production model (recommended)
  * `stable-latest` - Latest stable release
  * `dev-v4` - Development model (testing only)
</ParamField>

## Response

<ResponseField name="prediction_id" type="string" required>
  Unique identifier for this prediction
</ResponseField>

<ResponseField name="global" type="object" required>
  Overall prediction for the entire audio file

  <Expandable title="properties">
    <ResponseField name="confidence" type="number">
      Confidence score from 0.0 (uncertain) to 1.0 (very confident)

      Calculated as `abs(probability - 0.5) * 2`
    </ResponseField>

    <ResponseField name="result" type="string">
      Classification result:

      * `"bonafide"` - Authentic human voice
      * `"spoofed"` - AI-generated audio
      * `"partially_spoofed"` - Mixed content
      * `null` - Unable to determine (see `reason`)
    </ResponseField>

    <ResponseField name="reason" type="string">
      Explanation when `result` is `null`

      Examples: "Audio quality too poor", "All chunks in uncertain range"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="segments" type="array" required>
  Per-segment analysis (one per `chunk_duration`)

  <Expandable title="segment object">
    <ResponseField name="index" type="number">
      Zero-based segment index
    </ResponseField>

    <ResponseField name="start" type="number">
      Segment start time in seconds
    </ResponseField>

    <ResponseField name="end" type="number">
      Segment end time in seconds
    </ResponseField>

    <ResponseField name="confidence" type="number">
      Segment-level confidence (0.0-1.0)
    </ResponseField>

    <ResponseField name="result" type="string">
      `"bonafide"` or `"spoofed"`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string" required>
  Model version used for prediction
</ResponseField>

<ResponseField name="processing_time" type="number" required>
  Time taken to process in seconds
</ResponseField>

<ResponseField name="audio_duration" type="number" required>
  Total audio file duration in seconds
</ResponseField>

<ResponseField name="warnings" type="array">
  List of warnings (e.g., partial chunk failures, quality issues)
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.aurigin.ai/v1/predict" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -F "file=@suspicious_voice.wav" \
    -F "device=api" \
    -F "model=stable"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.aurigin.ai/v1/predict"
  headers = {"X-Api-Key": "YOUR_API_KEY"}

  files = {"file": open("suspicious_voice.wav", "rb")}
  data = {
      "device": "api",
      "model": "stable"

  }

  response = requests.post(url, headers=headers, files=files, data=data)
  result = response.json()

  print(f"Result: {result['global']['result']}")
  print(f"Confidence: {result['global']['confidence']:.2%}")
  ```

  ```javascript JavaScript theme={null}
  const FormData = require('form-data');
  const fs = require('fs');
  const axios = require('axios');

  const form = new FormData();
  form.append('file', fs.createReadStream('suspicious_voice.wav'));
  form.append('device', 'api');
  form.append('model', 'stable');

  const response = await axios.post(
    'https://api.aurigin.ai/v1/predict',
    form,
    {
      headers: {
        'X-Api-Key': 'YOUR_API_KEY',
        ...form.getHeaders()
      }
    }
  );

  console.log(`Result: ${response.data.global.result}`);
  console.log(`Confidence: ${response.data.global.confidence}`);
  ```
</CodeGroup>

## Example Response

```json 200 - Spoofed Audio Detected theme={null}
{
  "prediction_id": "pred_9b6ff057a7f7",
  "global": {
    "confidence": 0.95,
    "result": "spoofed",
    "reason": null
  },
  "segments": [
    {
      "index": 0,
      "start": 0.0,
      "end": 5.0,
      "confidence": 0.96,
      "result": "spoofed"
    },
    {
      "index": 1,
      "start": 5.0,
      "end": 10.0,
      "confidence": 0.94,
      "result": "spoofed"
    }
  ],
  "model": "stable-latest",
  "processing_time": 1.23,
  "audio_duration": 10.0,
  "warnings": []
}
```

```json 200 - Authentic Audio theme={null}
{
  "prediction_id": "pred_abc123def456",
  "global": {
    "confidence": 0.92,
    "result": "bonafide",
    "reason": null
  },
  "segments": [
    {
      "index": 0,
      "start": 0.0,
      "end": 5.0,
      "confidence": 0.91,
      "result": "bonafide"
    },
    {
      "index": 1,
      "start": 5.0,
      "end": 8.5,
      "confidence": 0.93,
      "result": "bonafide"
    }
  ],
  "model": "stable-latest",
  "processing_time": 0.87,
  "audio_duration": 8.5,
  "warnings": []
}
```

```json 400 - Validation Error theme={null}
{
  "error": "validation_error",
  "message": "Unsupported audio format",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

```json 401 - Unauthorized theme={null}
{
  "error": "unauthorized",
  "message": "Invalid or inactive API key",
  "correlation_id": "8b738992-c4eb-4f19-870a-900e6830d147"
}
```

```json 413 - File Too Large theme={null}
{
  "error": "payload_too_large",
  "message": "Request body exceeds maximum allowed size of 5MB",
  "correlation_id": "7f629881-a3db-5e28-761b-811f7940c258"
}
```

## Error Codes

| Code | Description         | Solution                                   |
| ---- | ------------------- | ------------------------------------------ |
| 400  | Validation error    | Check file format, duration, parameters    |
| 401  | Unauthorized        | Verify API key is valid and active         |
| 413  | File too large      | Reduce file size or use pre-signed S3 URLs |
| 422  | Unsupported format  | Convert to supported audio format          |
| 500  | Processing failed   | Retry or contact support if persists       |
| 503  | Service unavailable | Retry with exponential backoff             |

## Confidence Score Interpretation

The `confidence` score indicates how certain the model is about its prediction:

| Confidence    | Interpretation | Action                       |
| ------------- | -------------- | ---------------------------- |
| **0.9 - 1.0** | Very confident | Trust the result             |
| **0.7 - 0.9** | Confident      | Generally reliable           |
| **0.4 - 0.7** | Moderate       | Review segments individually |
| **0.0 - 0.4** | Low confidence | Manual review recommended    |

<Tip>
  For high-security applications, set a threshold of **0.85+** before taking automated actions.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Optimize Performance">
    * Use WAV or FLAC for best accuracy
    * Keep files under 5MB for fastest processing with this endpoint
  </Accordion>

  <Accordion title="Handle Partial Results">
    Check the `warnings` array for partial failures:

    ```json theme={null}
    "warnings": ["3 of 10 segments skipped due to quality issues"]
    ```

    If warnings exist, review individual segments for confidence.
  </Accordion>

  <Accordion title="Retry Logic">
    Implement exponential backoff for transient errors:

    ```python theme={null}
    import time
    from requests.adapters import HTTPAdapter
    from requests.packages.urllib3.util.retry import Retry

    session = requests.Session()
    retry = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[500, 502, 503, 504]
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount('https://', adapter)
    ```
  </Accordion>

  <Accordion title="Monitor Performance">
    Track `processing_time` to identify slow requests:

    * **\< 2s**: Excellent
    * **2-5s**: Good
    * **5-10s**: Acceptable for large files
    * **> 10s**: Consider async processing
  </Accordion>
</AccordionGroup>

## Rate Limits

| Plan         | Requests/Minute | Concurrent |
| ------------ | --------------- | ---------- |
| Free         | 10              | 2          |
| Starter      | 60              | 5          |
| Professional | 300             | 20         |
| Enterprise   | Custom          | Custom     |

<Info>
  Upgrade your plan at [app.aurigin.ai/billing](https://app.aurigin.ai/billing) for higher limits.
</Info>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Pre-Signed URLs" icon="link" href="/api-reference/prediction/presigned">
    Asynchronous processing for large files (100MB+)
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /predict
openapi: 3.0.3
info:
  title: Aurigin API v0
  version: 0.1.0
  description: Legacy Aurigin API for audio deepfake detection (chunk-based responses)
servers:
  - url: https://api.aurigin.ai/v0
security: []
tags:
  - name: v0
    description: Endpoints that analyze audio to determine if it is AI generated or real.
  - name: Async Predictions
    description: Endpoints that handle asynchronous prediction workflows.
paths:
  /predict:
    post:
      tags:
        - v0
      summary: AI-voice detection
      description: >-
        Analyze audio to determine if it is AI generated or real.


        You can send audio data in two ways: (1) multipart/form-data with a
        direct file upload, or (2) application/json with a presigned URL.


        The API processes audio files in 5-second chunks and returns one
        prediction per chunk.

        - Minimum duration: 3 seconds (1 chunk)

        - Maximum file size: 4MB

        - Chunk size: 5 seconds each

        - Output: One prediction per 5-second chunk


        Supported formats: WAV, MP3, M4A, FLAC, OGG.


        Error codes:

        - 400 Invalid input or file too large

        - 403 Authentication failed (check x-api-key)

        - 500 Internal error or upstream unavailability.
      operationId: predictV0
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                user_id:
                  type: string
                  description: Optional user identifier
              required:
                - file
            example:
              file: (binary audio file)
              user_id: speaker_123
          application/json:
            schema:
              $ref: '#/components/schemas/PredictRequest'
            example:
              presigned_url: https://example.com/presigned.wav
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictResponse'
              example:
                predictions:
                  - fake
                  - fake
                  - real
                global_probability:
                  - 0.9584
                  - 0.9585
                  - 0.9123
                error:
                  - null
                  - null
                  - null
                model: apollo-4-2025-10-20
                processing_time: 1.350719928741455
                audio_duration: 69.91
        '400':
          description: Invalid input or file too large (4MB max)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: validation_error
                message: Audio file too large (max 4MB)
                status: 400
                correlation_id: d3a1cb06-23a3-4f8a-a955-7ed2df41b5b7
        '403':
          description: Authentication failed (check x-api-key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid x-api-key header
                status: 403
                correlation_id: 12b52e74-7a57-4d85-aa2b-7b9158f09ef9
        '500':
          description: Internal error or upstream unavailability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: internal_error
                message: Upstream model timed out
                status: 500
                correlation_id: f906f85c-4b63-4f25-a93d-392d8fd521fb
      security:
        - api_key: []
components:
  schemas:
    PredictRequest:
      type: object
      properties:
        user_id:
          type: string
          description: Optional user identifier
        presigned_url:
          type: string
          description: Presigned URL to the audio file
      required:
        - presigned_url
    PredictResponse:
      type: object
      properties:
        error:
          type: array
          items:
            type: string
            nullable: true
          description: >-
            Error messages for each 5-second chunk (null if successful). Aligns
            1:1 with the predictions array.
        global_probability:
          type: array
          items:
            type: number
            format: float
          description: >-
            Confidence scores (0.0-1.0) for each prediction, one per 5-second
            chunk. Aligns 1:1 with the predictions array.
        predictions:
          type: array
          items:
            type: string
            enum:
              - fake
              - real
          description: >-
            AI detection results for each 5-second chunk of the audio. Array
            length equals the number of 5-second chunks in the audio file.
      example:
        error:
          - null
          - null
          - null
        global_probability:
          - 0.9584
          - 0.9585
          - 0.9123
        predictions:
          - fake
          - fake
          - real
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error identifier
        message:
          type: string
          description: Human-readable error message
        status:
          type: integer
          description: HTTP status code associated with the error
          example: 400
        correlation_id:
          type: string
          description: Unique identifier for tracing failed requests
      required:
        - error
        - message
      example:
        error: validation_error
        message: Audio file too large (max 4MB)
        status: 400
        correlation_id: be7a2d19-5ef9-4472-9a21-7b90c0c8573c
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````