API-Dokumentation

KI-Audioerkennungs-API

Vollständige Dokumentation zur Integration der KI-Audioerkennungs-API von TruthScan in Ihre Anwendungen.

Probieren Sie es ohne Code aus, indem Sie unseren FastAPI-Endpunkt besuchen: https://detect-audio.truthscan.com/docs

Authentifizierung

TruthScan verwendet API-Schlüssel, um den Zugriff auf die API zu ermöglichen. Sie können Ihren API-Schlüssel oben auf der Seite in unserem Entwicklerportal abrufen.

TruthScan erwartet, dass der API-Schlüssel in allen API-Anfragen an den Server im Anforderungstext wie folgt enthalten ist:

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

Sie müssen YOUR API KEY GOES HERE durch Ihren persönlichen API-Schlüssel ersetzen.

KI-Audioerkennung

Erkennen (3-Schritte-Prozess)

Der KI-Audioerkennungsworkflow besteht aus den folgenden Schritten:

  • Eine vorsignierte Upload-URL abrufen
  • Das Audio hochladen
  • Das Audio zur Erkennung einreichen

1. Eine vorsignierte Upload-URL abrufen

Beginnen Sie damit, eine vorsignierte URL von der API anzufordern. Diese URL ermöglicht es Ihnen, Ihre Audiodatei sicher auf den Speicherserver hochzuladen.

Unterstützte Dateiformate

MP3, WAV, M4A, FLAC, OGG, MP4

Wichtiger Hinweis

Es ist notwendig, Leerzeichen aus dem Audiodateinamen zu entfernen, wenn Sie eine vorsignierte URL anfordern.

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

Beispielanfrage

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

Beispielantwort

{
  "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. Das Audio hochladen

Verwenden Sie die bereitgestellte 'presigned_url', um Ihr Audio über eine PUT-Anfrage hochzuladen. Stellen Sie sicher, dass der richtige Inhaltstyp entsprechend Ihrem Audioformat festgelegt ist.

Wichtiger Hinweis

Es ist notwendig, Leerzeichen aus dem Audiodateinamen zu entfernen, wenn Sie das Audio hochladen.

Beispielanfrage

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

Dateigrößenbeschränkungen

  • Minimale Dateigröße: 1KB
  • Maximale Dateigröße: 10MB

Stellen Sie sicher, dass das Dateiformat während des Upload-Prozesses konsistent bleibt. Ein erfolgreicher Upload gibt einen Statuscode von 200 zurück.

3. Audio zur KI-Erkennung einreichen

Nach dem Hochladen reichen Sie das Audio zur KI-Erkennung ein, indem Sie auf den 'file_path' aus dem vorherigen Schritt verweisen.

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

Beispielanfrage

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
}'

Der 'FILE_PATH' bezieht sich auf den Pfad, der aus der Antwort im ersten Schritt 'Eine vorsignierte Upload-URL abrufen' erhalten wurde.

Optionale Parameter

  • analyzeUpToSeconds: Bis zu N Sekunden vom Anfang analysieren (Standard: 60)
  • document_type: Dokumenttyp (Standard: 'Audio')
  • email: Optionale E-Mail-Adresse für die Verarbeitung

Beispielantwort

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

Die Antwort enthält eine eindeutige ID zur Verfolgung des Erkennungsstatus.

Erkennungsstatus und Ergebnisse abfragen

Um den Status zu überprüfen und die Ergebnisse abzurufen, verwenden Sie den /query-Endpunkt mit der ID.

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

Beispielanfrage

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

Beispielantwort

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

Ergebnisdetails

  • is_valid: Gibt an, ob die Audiodatei gültig ist (true/false)
  • message: Verarbeitungsnachricht
  • original_duration: Dauer in Sekunden des Originalaudios
  • is_truncated: Ob das Audio für die Analyse gekürzt wurde
  • truncated_duration: Analysierte Dauer wenn gekürzt
  • mean_ai_prob: Gesamtwahrscheinlichkeitsbewertung für KI
  • individual_chunks_ai_prob: KI-Wahrscheinlichkeitsbewertungen pro Chunk

Das Feld "status" wird einer der folgenden sein: "pending" (Verarbeitung ist in der Warteschlange), "analyzing" (KI-Erkennung läuft), "done" (Ergebnisse sind verfügbar) oder "failed" (Verarbeitung fehlgeschlagen).

Benutzerguthaben prüfen

Dieser Endpunkt akzeptiert den API-Schlüssel des Benutzers über den Header. Und gibt die Guthabendetails des Benutzers zurück.

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

Beispielanfrage

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'

Beispielantwort

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

Gesundheitsprüfung

Überprüfen Sie den Gesundheitsstatus des API-Servers.

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

Beispielanfrage

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

Beispielantwort

{
    "status": "healthy"
}

Fehler

Die meisten Fehler werden durch falsche Parameter verursacht, die an die API gesendet werden. Überprüfen Sie die Parameter jedes API-Aufrufs doppelt, um sicherzustellen, dass sie richtig formatiert sind, und versuchen Sie, den bereitgestellten Beispielcode auszuführen.

Die generischen Fehlercodes, die wir verwenden, entsprechen dem REST-Standard:

FehlercodeBedeutung
400Bad Request -- Ihre Anfrage ist ungültig.
403Forbidden -- Der API-Schlüssel ist ungültig oder es gibt nicht genügend Guthaben für die Audioverarbeitung.
404Not Found -- Die angegebene Ressource existiert nicht.
405Method Not Allowed -- Sie haben versucht, auf eine Ressource mit einer ungültigen Methode zuzugreifen.
406Not Acceptable -- Sie haben ein Format angefordert, das nicht JSON ist.
410Gone -- Die Ressource an diesem Endpunkt wurde entfernt.
422Invalid Request Body -- Ihr Anforderungstext ist falsch formatiert oder ungültig oder es fehlen Parameter.
429Too Many Requests -- Sie senden zu viele Anfragen! Verlangsamen Sie!
500Internal Server Error -- Wir hatten ein Problem mit unserem Server. Versuchen Sie es später erneut.
503Service Unavailable -- Wir sind vorübergehend wegen Wartungsarbeiten offline. Bitte versuchen Sie es später erneut.

Häufige Probleme und Lösungen

Authentifizierungsprobleme

"Benutzerüberprüfung fehlgeschlagen" (403)

Ursache: Ungültiger oder abgelaufener API-Schlüssel

Lösung:

  1. Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist
  2. Überprüfen Sie, ob Ihr API-Schlüssel in Ihrem Konto aktiv ist
  3. Versuchen Sie, Ihren API-Schlüssel neu zu generieren

"Nicht genügend Guthaben" (403)

Ursache: Unzureichendes Guthaben für die Audioverarbeitung

Lösung:

  1. Überprüfen Sie Ihr verbleibendes Guthaben mit /check-user-credits
  2. Kaufen Sie bei Bedarf zusätzliches Guthaben
  3. Verwenden Sie analyzeUpToSeconds, um weniger Audio zu analysieren und weniger Guthaben zu verbrauchen

Eingabevalidierungsprobleme

"Nicht unterstütztes Dateiformat" (400)

Ursache: Nicht unterstütztes oder ungültiges Audioformat eingereicht

Lösung:

  1. Überprüfen Sie, ob das Audioformat unterstützt wird (MP3, WAV, M4A, FLAC, OGG, MP4)
  2. Stellen Sie sicher, dass die Datei nicht beschädigt ist
  3. Überprüfen Sie den Content-Type-Header beim Hochladen

"Datei zu groß" (400)

Ursache: Dateigröße überschreitet das 10MB-Limit

Lösung:

  1. Komprimieren oder konvertieren Sie das Audio auf unter 10MB
  2. Überprüfen Sie die Dateigröße vor dem Hochladen
  3. Verwenden Sie nach Möglichkeit effizientere Formate wie MP3

Verarbeitungsprobleme

"Audio-Verarbeitung hat zu lange gedauert"

Ursache: Die Audio-Verarbeitung hat zu lange gedauert oder es ist ein Timeout aufgetreten

Lösung:

  1. Versuchen Sie es mit einer kleineren Audiodatei oder kürzeren Dauer
  2. Verwenden Sie analyzeUpToSeconds, um nur die ersten Sekunden zu analysieren
  3. Überprüfen Sie, ob der Dienst eine hohe Last erfährt
  4. Wiederholen Sie die Anfrage nach einigen Minuten

Status "fehlgeschlagen" in /query-Antwort

Ursache: Die Verarbeitung ist aus verschiedenen Gründen fehlgeschlagen

Lösung:

  1. Überprüfen Sie, ob das Audio die Mindestanforderungen erfüllt (1KB - 10MB)
  2. Überprüfen Sie, ob das Audio in einem unterstützten Format vorliegt
  3. Überprüfen Sie, ob der Upload erfolgreich abgeschlossen wurde, bevor Sie zur Erkennung einreichen
  4. Kontaktieren Sie den Support, wenn das Problem weiterhin besteht

Upload-Probleme

"Audio-Upload fehlgeschlagen" (403/400)

Ursache: Ungültige oder abgelaufene vorsignierte URL oder Probleme mit dem Speicherserver

Lösung:

  1. Stellen Sie sicher, dass Sie die vorsignierte URL sofort nach Erhalt verwenden (kann ablaufen)
  2. Überprüfen Sie, ob der Content-Type-Header für das Audioformat korrekt ist
  3. Entfernen Sie Leerzeichen aus dem Dateinamen vor dem Hochladen
  4. Versuchen Sie, eine neue vorsignierte URL zu generieren, wenn die aktuelle abgelaufen ist

"Ungültige vorsignierte URL" (400)

Ursache: Dateiname mit Leerzeichen oder abgelaufene/beschädigte vorsignierte URL

Lösung:

  1. Entfernen Sie alle Leerzeichen aus dem Dateinamen, bevor Sie die vorsignierte URL anfordern
  2. Verwenden Sie nur alphanumerische Zeichen, Bindestriche und Unterstriche im Dateinamen
  3. Generieren Sie bei Bedarf eine neue vorsignierte URL

Brauchen Sie Hilfe?

Für weitere Informationen zur Verwendung unserer API oder für technischen Support kontaktieren Sie uns bitte.

Kontaktieren Sie uns

API Häufig gestellte Fragen

Finden Sie Antworten auf die häufigsten Fragen zu unserer KI-Audioerkennungs-API.