API-Dokumentation
ISO 27001SOC 2 CertifiedGDPR Compliant

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

Preise & Credits

Jede Videoerkennungsanfrage verbraucht Credits aus Ihrem Konto, wenn die Verarbeitung abgeschlossen ist.

Prüfen Sie Ihr Guthaben mit GET /check-user-credits. Preispläne anzeigen

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 zwei Schritten:

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

Erkennungsmodelle

Wählen Sie mit dem optionalen model-Parameter, welches ML-Modell während der Erkennungspipeline ausgeführt wird. Wenn weggelassen, wird generic verwendet.

  • generic: Allgemeines KI-Videoerkennungsmodell (Standard)
  • faceswap: Dediziertes Face-Swap-Videoerkennungsmodell

Beide Modelle verwenden dieselbe Erkennungspipeline (metadata → watermark → ML) und liefern dasselbe Antwortformat. Ungültige model-Werte geben 422 zurück.

1. Video einreichen

Laden Sie eine Videodatei direkt zur API hoch oder reichen Sie eine Video-URL ein. Der Server validiert die Datei.

Unterstützte Dateiformate

mp4, mov, avi, mkv, webm

Dateigrößenbeschränkungen

  • Minimale Dateigröße: 1KB
  • Maximale Dateigröße: 100MB
Per Datei-Upload einreichen

Header

  • key (erforderlich): Ihr API-Schlüssel
  • email: Optionale E-Mail-Adresse
  • userkey: Optionaler Integrations-Benutzerschlüssel

Multipart form-data

  • file (erforderlich): Das zu analysierende Video
  • model: Zu verwendendes Erkennungsmodell, d.h. generic oder faceswap (optional, Standard: generic)
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'

Face-Swap-Modell-Beispiel

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' \
  -F 'model=faceswap'

Optionale Parameter

  • document_type: Dokumenttyp (Standard: Video)
  • email: E-Mail-Adresse für die Verarbeitung
  • model: Erkennungsmodell, d.h. generic oder faceswap (Standard: generic)
Per URL einreichen

Header

  • Content-Type: application/json

Body (JSON)

  • key (erforderlich): Ihr API-Schlüssel
  • url: https://ai-video-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>
  • model: Zu verwendendes Erkennungsmodell, d.h. generic oder faceswap (optional, Standard: generic)
POST https://detect-video.truthscan.com/detect

Beispiel-Request

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "generic"
}'

Face-Swap-Modell-Beispiel

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "faceswap"
}'

Optionale Parameter

  • document_type: Dokumenttyp (Standard: Video)
  • email: E-Mail-Adresse für die Verarbeitung
  • model: Erkennungsmodell, d.h. generic oder faceswap (Standard: generic)

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 KI-Wahrscheinlichkeitsbewertung in [0.0, 1.0] (höher = wahrscheinlicher KI-generiert), 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: Klassifikatormodell, das 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 Feld "status" ist eines von: "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

Ungültiger model-Wert (422)

Ursache: Der model-Parameter ist weder generic noch faceswap

Lösung:

  1. Lassen Sie model weg, um das Standardmodell generic zu verwenden
  2. Setzen Sie model auf generic für allgemeine KI-Videoerkennung
  3. Setzen Sie model auf faceswap für Face-Swap-Videoerkennung

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
  4. 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.