AUDIO_INTEGRATION.md

# BitCheck Audio Verification - Backend Integration Guide

This guide provides instructions for integrating the deployed Hugging Face audio verification model into your backend services.

## Base URL

The service is deployed on Hugging Face Spaces. Use the direct API URL for requests:
`https://jaykay73-bitcheck-audio.hf.space` (replace with the exact Space URL if it differs).

## Endpoint

### `POST /verify/audio`

Analyzes an uploaded audio file and returns a trust score indicating the likelihood that the audio is AI-generated.

#### Request Headers
*   `Accept`: `application/json`
*   `Content-Type`: `multipart/form-data`

#### Request Parameters (Form Data)

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `file` | File | **Yes** | - | The audio or video file to be analyzed (e.g., `.wav`, `.mp3`, `.m4a`). |
| `max_duration_seconds` | Integer | No | `60` | Maximum duration of audio to process in seconds. |
| `strict_duration_limit` | Boolean | No | `false` | If true, rejects files longer than `max_duration_seconds`. If false, truncates them. |
| `return_features` | Boolean | No | `false` | If true, includes raw extracted audio features in the response. |
| `run_quality_analysis`| Boolean | No | `true` | If true, performs audio quality analysis (e.g., silence detection). |

#### Integration Examples

**cURL:**

```bash
curl -X POST "https://jaykay73-bitcheck-audio.hf.space/verify/audio" \
  -H "Accept: application/json" \
  -F "file=@path/to/your/audio.wav" \
  -F "return_features=false"
```

**Python (requests):**

```python
import requests

url = "https://jaykay73-bitcheck-audio.hf.space/verify/audio"
file_path = "path/to/your/audio.wav"

with open(file_path, "rb") as f:
    files = {"file": f}
    data = {"return_features": "false"}
    
    response = requests.post(url, files=files, data=data)
    
if response.status_code == 200:
    result = response.json()
    print("Trust Score:", result.get("trust", {}).get("trust_score"))
    print("Decision:", result.get("trust", {}).get("decision"))
else:
    print("Error:", response.status_code, response.text)
```

**Node.js (Axios):**

```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const url = 'https://jaykay73-bitcheck-audio.hf.space/verify/audio';
const filePath = 'path/to/your/audio.wav';

const form = new FormData();
form.append('file', fs.createReadStream(filePath));
form.append('return_features', 'false');

axios.post(url, form, {
    headers: {
        ...form.getHeaders()
    }
})
.then(response => {
    console.log('Trust Score:', response.data.trust.trust_score);
    console.log('Decision:', response.data.trust.decision);
})
.catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
});
```

#### Response Structure

The endpoint returns a detailed JSON report containing metadata, preprocessing details, quality analysis, model results, and the final trust score. 

A successful response (`200 OK`) looks like this:

```json
{
  "verification_id": "uuid-string",
  "processing_time_ms": 1234,
  "file_type": "audio",
  "file_validation": {
    "valid": true,
    "warnings": [],
    "error": null,
    "saved_path": "/path/to/file"
  },
  "audio_metadata": { 
    "duration_seconds": 5.4,
    "sample_rate": 44100
  },
  "audio_quality": { 
    "checked": true,
    "quality_risk_score": 0.1
  },
  "model_analysis": {
    "model_found": true,
    "risk_score": 0.85,
    "fake_probability": 0.85
  },
  "trust": {
    "trust_score": 15,         // 0 to 100 (0=Fake, 100=Real)
    "decision": "reject",      // "accept", "review", or "reject"
    "risk_level": "high",      // "low", "medium", or "high"
    "reasons": [
      "High probability of AI generation detected."
    ]
  }
}
```

*Note: The most important fields for your backend integration are located under the `trust` object, specifically `trust_score` and `decision`.*