API-Dokumentation

KI-Videoerkennungs-API

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

Testen Sie die API ohne Code, indem Sie unseren FastAPI-Endpunkt besuchen: https://detect-video.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 erhalten.

TruthScan erwartet, dass der API-Schlüssel in allen API-Anfragen an den Server entweder als Form-Parameter oder Header wie folgt enthalten ist:

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

Sie müssen YOUR_API_KEY durch Ihren persönlichen API-Schlüssel ersetzen.

KI-Videoerkennung

Erkennung (2-Schritte-Prozess)

Der KI-Videoerkennungs-Workflow besteht aus den folgenden Schritten:

  • Video zur Erkennung einreichen (Multipart-Upload)
  • Auftrag abfragen, um Ergebnisse abzurufen

1. Video zur Erkennung einreichen

Laden Sie eine Videodatei direkt zur API hoch. Der Server validiert die Datei.

Unterstützte Dateiformate

MP4, MOV, AVI, MKV, WEBM

Dateigrößenbeschränkungen

  • Minimale Dateigröße: 1KB
  • Maximale Dateigröße: 100MB
POST https://detect-video.truthscan.com/detect-file

Beispiel-Request

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Optionale Parameter

  • document_type: Typ des Dokuments (Standard: 'Video')
  • email: Optionale E-Mail-Adresse für die Verarbeitung

Beispiel-Antwort

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

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

2. Erkennungsstatus und Ergebnisse abfragen

Nach der Einreichung fragen Sie den /query-Endpunkt mit der Auftrags-ID ab, um Status und Ergebnisse abzurufen.

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

Beispiel-Request

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

Beispiel-Antwort

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Ergebnisdetails

  • status: "pending", "analyzing", "done" oder "failed"
  • result: Skalare Bewertung in [0.0, 1.0] abgeleitet von ML prob_fake
  • final_stage: Letzte Stufe, die zum Ergebnis beigetragen hat: 'metadata', 'watermark' oder 'ml'
  • metadata: Setzt immer prediction: 'no_detection' und confidence: 0.0. Status kann 'reject', 'reencode' oder 'ok' sein
  • watermark: Heuristik, die Frames abtastet und Pseudo-Konfidenz aus Pixelvarianz berechnet
  • ml: ConvNeXt-basierter Klassifikator, der auf abgetasteten Frames läuft. Gibt prob_fake in [0.0, 1.0] und Label zurück ('ai_generated' wenn prob_fake ≥ 0.5, sonst 'no_detection')
  • latency_sec: Gesamte Pipeline-Zeit

Das "status"-Feld kann einen der folgenden Werte haben: "pending" (Verarbeitung in Warteschlange), "analyzing" (KI-Erkennung läuft), "done" (Ergebnisse verfügbar) oder "failed" (Verarbeitung fehlgeschlagen).

Benutzerguthaben prüfen

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

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

Beispiel-Request

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

Beispiel-Antwort

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

Gesundheitsprüfung

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

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

Beispiel-Request

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

Beispiel-Antwort

{
    "status": "healthy"
}

Fehler

Die meisten Fehler stammen von falschen Parametern, die an die API gesendet werden. Überprüfen Sie die Parameter jedes API-Aufrufs, um sicherzustellen, dass sie korrekt 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 Credits für die Videoverarbeitung.
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 Request Body ist falsch formatiert, ungültig oder hat fehlende 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 noch einmal.
503Service Unavailable -- Wir sind vorübergehend wegen Wartungsarbeiten offline. Bitte versuchen Sie es später noch einmal.

Häufige Probleme und Lösungen

Authentifizierungsprobleme

"Benutzerverifizierung fehlgeschlagen" (403)

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

Lösung:

  1. Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist
  2. Prü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 Credits" (403)

Ursache: Unzureichende Credits für die Videoverarbeitung

Lösung:

  1. Überprüfen Sie Ihre verbleibenden Credits mit /check-user-credits
  2. Kaufen Sie bei Bedarf zusätzliche Credits

Eingabevalidierungsprobleme

"Nicht unterstützter Videotyp" (400)

Ursache: Dateiformat nicht unterstützt

Lösung:

  1. Konvertieren Sie das Video in ein unterstütztes Format (MP4, MOV, AVI, MKV, WEBM)
  2. Stellen Sie sicher, dass Dateierweiterung und MIME-Typ korrekt sind

"Dateigröße überschreitet Limit" (400)

Ursache: Videodatei ist zu groß

Lösung:

  1. Komprimieren, kürzen oder neu kodieren Sie das Video, um die Größe zu reduzieren (maximal 100MB)
  2. Verwenden Sie einen effizienteren Codec/Container

"Dateigröße zu klein" (400)

Ursache: Videodatei liegt unter der Mindestgröße

Lösung:

  1. Verwenden Sie eine größere Videodatei (mindestens 1KB)
  2. Überprüfen Sie, ob die Datei beim Hochladen beschädigt wurde

"Ungültiger Dateityp" (400)

Ursache: Dateityp-Validierung fehlgeschlagen (z.B. falscher MIME-Typ oder beschädigte Datei)

Lösung:

  1. Stellen Sie sicher, dass die Datei ein gültiges Videoformat ist
  2. Überprüfen Sie, ob der MIME-Typ mit der Dateierweiterung übereinstimmt
  3. Exportieren oder kodieren Sie die Datei bei Bedarf neu

Verarbeitungsprobleme

Videostatus "fehlgeschlagen"

Ursache: Verarbeitung fehlgeschlagen (z.B. unlesbarer Container, Dekodierungsfehler)

Lösung:

  1. Stellen Sie sicher, dass Container/Codec häufig unterstützt wird (H.264/AAC in MP4 empfohlen)
  2. Kodieren Sie das Video mit einer Standardvoreinstellung (z.B. ffmpeg) neu und laden Sie es erneut hoch
  3. Stellen Sie sicher, dass die Datei Größen- und Formatanforderungen erfüllt

Videostatus "Timeout" oder lange Verarbeitung

Ursache: Videoverarbeitung dauert länger als erwartet oder ist abgelaufen

Lösung:

  1. Warten Sie etwas länger und überprüfen Sie den Status erneut mit /query
  2. Stellen Sie sicher, dass die Videodatei alle Format- und Größenanforderungen erfüllt
  3. Kontaktieren Sie den Support, wenn das Problem weiterhin besteht

"Benutzer nicht gefunden"

Ursache: Ungültige Benutzer-ID

Lösung:

  1. Überprüfen Sie, ob Ihr API-Schlüssel korrekt und mit einem aktiven Konto verknüpft ist
  2. Stellen Sie sicher, dass der Integrationsbenutzer gültig und aktiv ist
  3. Authentifizieren Sie sich bei Bedarf erneut

"Dateimetadaten konnten nicht abgerufen werden" (500)

Ursache: Kann nicht auf die hochgeladene Datei zugreifen oder sie parsen

Lösung:

  1. Überprüfen Sie, ob der Upload erfolgreich abgeschlossen wurde
  2. Prüfen Sie, ob die Datei zugänglich und nicht beschädigt ist
  3. Versuchen Sie, die Datei erneut hochzuladen

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-Videoerkennungs-API.