API-documentatie

AI-audiodetectie-API

Volledige documentatie voor het integreren van de AI-audiodetectie-API van TruthScan in uw applicaties.

Probeer het zonder code via ons FastAPI-eindpunt: https://detect-audio.truthscan.com/docs

Authenticatie

TruthScan gebruikt API-sleutels voor toegang tot de API. U vindt uw API-sleutel bovenaan de pagina in ons ontwikkelaarsportaal.

TruthScan verwacht dat de API-sleutel in alle API-verzoeken naar de server wordt opgenomen in een request body die er als volgt uitziet:

{
  "key": "YOUR API KEY GOES HERE"
}

Vervang YOUR API KEY GOES HERE door uw persoonlijke API-sleutel.

AI-audiodetector

Detecteren (3 stappen)

De AI-audiodetectieworkflow bestaat uit de volgende stappen:

Vraag een vooraf ondertekende upload-URL aan
Upload de audio
Dien de audio in voor detectie

1. Vraag een vooraf ondertekende upload-URL aan

Vraag eerst een vooraf ondertekende URL aan bij de API. Met deze URL upload u uw audiobestand veilig naar de opslagserver.

Ondersteunde bestandsformaten

MP3, WAV, M4A, FLAC, OGG, MP4

Belangrijke opmerking

Verwijder spaties uit de audiobestandsnaam bij het aanvragen van een vooraf ondertekende URL.

GET https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3

Voorbeeldverzoek

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

Voorbeeldantwoord

{
  "status": "success",
  "presigned_url": "https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. Upload de audio

Gebruik de opgegeven 'presigned_url' om uw audio via een PUT-verzoek te uploaden. Zorg dat het juiste content type is ingesteld volgens uw audioformaat.

Belangrijke opmerking

Verwijder spaties uit de audiobestandsnaam bij het uploaden van de audio.

Voorbeeldverzoek

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

Bestandsgroottelimieten

Minimale bestandsgrootte: 1 KB
Maximale bestandsgrootte: 100 MB

Zorg dat het bestandsformaat tijdens het uploaden gelijk blijft. Een geslaagde upload geeft statuscode 200 terug.

3. Dien audio in voor AI-detectie

Na het uploaden dient u de audio in voor AI-detectie door te verwijzen naar 'file_path' uit de vorige stap.

POST https://detect-audio.truthscan.com/detect

Voorbeeldverzoek

curl -X 'POST' \
  'https://detect-audio.truthscan.com/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
}'

'FILE_PATH' verwijst naar het pad uit het antwoord in de eerste stap, 'Vraag een vooraf ondertekende upload-URL aan'.

Optionele parameters

analyzeUpToSeconds: Analyseer maximaal N seconden vanaf het begin (standaard: 60)
document_type: Documenttype (standaard: 'Audio')
email: Optioneel e-mailadres voor verwerking

Voorbeeldantwoord

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

Het antwoord bevat een unieke ID om de detectiestatus te volgen.

Vraag detectiestatus en resultaten op

Gebruik het /query-eindpunt met de ID om de status te controleren en de resultaten op te halen.

POST https://detect-audio.truthscan.com/query

Voorbeeldverzoek

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

Voorbeeldantwoord

{
    "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]
    }
}

Resultaatdetails

is_valid: Geeft aan of het audiobestand geldig is (true/false)
message: Verwerkingsbericht
original_duration: Duur in seconden van de originele audio
is_truncated: Of de audio is ingekort voor analyse
truncated_duration: Geanalyseerde duur indien ingekort
mean_ai_prob: Totale AI-waarschijnlijkheidsscore
individual_chunks_ai_prob: AI-waarschijnlijkheidsscores per segment

Het veld "status" is één van: "pending" (in de wachtrij), "analyzing" (AI-detectie bezig), "done" (resultaten beschikbaar) of "failed" (verwerking mislukt).

Controleer gebruikerscredits

Dit eindpunt accepteert de apikey van de gebruiker via de header en geeft de creditdetails terug.

GET https://detect-audio.truthscan.com/check-user-credits

Voorbeeldverzoek

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

Voorbeeldantwoord

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

Health check

Controleer de status van de API-server.

GET https://detect-audio.truthscan.com/health

Voorbeeldverzoek

curl -X 'GET' \
  'https://detect-audio.truthscan.com/health' \
  -H 'accept: application/json'

Voorbeeldantwoord

{
    "status": "healthy"
}

Fouten

De meeste fouten komen door onjuiste parameters. Controleer de parameters van elke API-aanroep en probeer de voorbeeldcode.

De algemene foutcodes die we gebruiken volgen de REST-standaard:

Foutcode	Betekenis
400	Bad Request – Uw verzoek is ongeldig.
403	Forbidden – De API-sleutel is ongeldig of er zijn onvoldoende credits voor audiobewerking.
404	Not Found – De opgegeven resource bestaat niet.
405	Method Not Allowed – U probeerde een resource met een ongeldige methode te benaderen.
406	Not Acceptable – U vroeg een formaat dat geen JSON is.
410	Gone – De resource op dit eindpunt is verwijderd.
422	Invalid Request Body – Uw request body is onjuist geformatteerd, ongeldig of mist parameters.
429	Too Many Requests – U stuurt te veel verzoeken. Vertraag het tempo.
500	Internal Server Error – Er ging iets mis op onze server. Probeer later opnieuw.
503	Service Unavailable – We zijn tijdelijk offline voor onderhoud. Probeer later opnieuw.

Veelvoorkomende problemen en oplossingen

Authenticatieproblemen

"User verification failed" (403)

Oorzaak: Ongeldige of verlopen API-sleutel

Oplossing:

Controleer of uw API-sleutel klopt
Controleer of uw API-sleutel actief is in uw account
Genereer zo nodig een nieuwe API-sleutel

"Not enough credits" (403)

Oorzaak: Onvoldoende credits voor audiobewerking

Oplossing:

Controleer uw resterende credits via /check-user-credits
Koop indien nodig extra credits
Gebruik analyzeUpToSeconds om minder audio te analyseren en minder credits te verbruiken

Validatieproblemen bij invoer

"Unsupported file format" (400)

Oorzaak: Niet-ondersteund of ongeldig audioformaat

Oplossing:

Controleer of het formaat wordt ondersteund (MP3, WAV, M4A, FLAC, OGG, MP4)
Controleer of het bestand niet beschadigd is
Controleer de Content-Type-header bij uploaden

"File too large" (400)

Oorzaak: Bestandsgrootte overschrijdt de limiet van 100 MB

Oplossing:

Comprimeer of converteer de audio tot onder 100 MB
Controleer de bestandsgrootte vóór upload
Gebruik waar mogelijk efficiëntere formaten zoals MP3

Verwerkingsproblemen

"Audio processing took too long"

Oorzaak: Audiobewerking duurde te lang of er trad een time-out op

Oplossing:

Probeer een kleiner audiobestand of kortere duur
Gebruik analyzeUpToSeconds om alleen de eerste seconden te analyseren
Controleer of de service hoge belasting heeft
Probeer het verzoek na enkele minuten opnieuw

Status "failed" in /query-antwoord

Oorzaak: Verwerking om diverse redenen mislukt

Oplossing:

Controleer of de audio aan de minimumvereisten voldoet (1 KB – 100 MB)
Controleer of het audio in een ondersteund formaat is
Controleer of de upload succesvol was vóór indienen voor detectie
Neem contact op met support als het probleem aanhoudt

Uploadproblemen

"Audio upload failed" (403/400)

Oorzaak: Ongeldige of verlopen vooraf ondertekende URL, of problemen met de opslagserver

Oplossing:

Gebruik de vooraf ondertekende URL direct na ontvangst (kan verlopen)
Controleer of de Content-Type-header klopt voor het audioformaat
Verwijder spaties uit de bestandsnaam vóór upload
Genereer een nieuwe vooraf ondertekende URL als de huidige is verlopen

"Invalid pre-signed URL" (400)

Oorzaak: Bestandsnaam met spaties of verlopen/beschadigde vooraf ondertekende URL

Oplossing:

Verwijder alle spaties uit de bestandsnaam vóór het aanvragen van de URL
Gebruik alleen alfanumerieke tekens, koppeltekens en underscores in de bestandsnaam
Genereer zo nodig een nieuwe vooraf ondertekende URL

Hulp nodig?

Voor meer informatie over onze API of technische ondersteuning kunt u contact met ons opnemen.

Neem contact op

Veelgestelde vragen over de API

Antwoorden op de meest gestelde vragen over onze AI-audiodetectie-API.