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:

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):

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):

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:

{
  "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.