API Documentation
ISO 27001SOC 2 CertifiedGDPR Compliant

KI-PDF-Erkennungs-API

Vollständige Dokumentation zur Integration der TruthScan KI-PDF-Erkennungs-API in Ihre Anwendungen.

Testen Sie die API ohne Code, indem Sie unseren FastAPI-Endpunkt besuchen: https://detect-text.truthscan.com/docs

Preise & Credits

Die PDF-Erkennung zieht 1.000 Credits pro Seite ab (z. B. verbraucht ein 5-seitiges PDF 5.000 Credits).

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.

Für Anfragen nach vorsignierten Upload-URLs (`GET /get-presigned-url`) fügen Sie Ihren API-Schlüssel im Header `apikey` hinzu.

Für PDF-Erkennungsanfragen (`POST /detect-pdf`) fügen Sie Ihren API-Schlüssel im JSON-Body als `key` hinzu.

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

PDF-Detektor

Der PDF-Detektor analysiert hochgeladene PDF-Dateien asynchron. PDFs müssen zuerst in den Object Storage hochgeladen und dann über `/detect-pdf` eingereicht werden. Pollen Sie `/query`, bis `status` `done` ist.

Drei Detektorversionen stehen zur Verfügung. Jede beantwortet eine andere Frage, wählen Sie die Version, die zu Ihrem Anwendungsfall passt (oder führen Sie v1 und v3/v4 an derselben Datei aus, indem Sie sie zweimal mit unterschiedlichen `model`-Werten einreichen):

  • v1: pdf_detector/v1

    Erkennt, ob das PDF mit einem KI-Tool erzeugt wurde, anhand von PDF-Metadaten.

  • v3: pdf_detector/v3

    Prüft auf digitale Bearbeitungen und Anzeichen KI-generierter Dokumente.

  • v4: pdf_detector/v4 (Standard / neueste Version)

    Neueste Version des Manipulationsdetektors mit verbesserter Gesamtleistung, empfohlen für neue Integrationen.

Modellauswahl

  • pdf_detector: Lassen Sie `model` weg oder senden Sie `pdf_detector`, um die neueste Version zu verwenden (derzeit `pdf_detector/v4`).
  • pdf_detector/v1: Senden Sie `model: pdf_detector/v1` für die Erkennung von KI-Generierungs-Metadaten.
  • pdf_detector/v3: Senden Sie `model: pdf_detector/v3`, um v3 festzulegen.
  • pdf_detector/v4: Senden Sie `model: pdf_detector/v4`, um v4 explizit festzulegen.
  • model: Jeder andere `model`-Wert gibt 400 Bad Request zurück.

Ablauf

  • `GET /get-presigned-url` mit einem `.pdf`-Dateinamen und Ihrem API-Schlüssel im Header `apikey`.
  • `PUT` der PDF-Bytes an die zurückgegebene `presigned_url`.
  • `POST /detect-pdf` mit der öffentlichen Objekt-`url`, Ihrem API-`key` und einem optionalen `model`.
  • `POST /query` mit der zurückgegebenen Dokument-`id`, bis die Verarbeitung abgeschlossen ist.

Dateilimits

PDF-Dateien müssen `.pdf` sein, höchstens 2 MB groß und unter der eingereichten `url` erreichbar.

Kreditabzug

Die PDF-Erkennung zieht 1.000 Credits pro Seite ab. Ein 5-seitiges PDF verbraucht 5.000 Credits. Überprüfen Sie Ihren Kontostand mit `/check-user-credits`, bevor Sie große Dokumente einreichen.

Vorsignierte Upload-URL abrufen

Fordern Sie eine vorsignierte Upload-URL an, bevor Sie ein PDF zur Erkennung einreichen.

Header

Fügen Sie Ihren API-Schlüssel im Header `apikey` hinzu.

GET https://detect-text.truthscan.com/get-presigned-url

Beispielanfrage

curl -X 'GET' \
  'https://detect-text.truthscan.com/get-presigned-url?file_name=report.pdf&expiration=3600' \
  -H 'accept: application/json' \
  -H 'apikey: YOUR-API-KEY-GOES-HERE'

Laden Sie die Datei per PUT an die `presigned_url` aus der Antwort hoch, bevor Sie `/detect-pdf` aufrufen.

Beispielantwort

{
    "status": "success",
    "presigned_url": "https://...digitaloceanspaces.com/...?X-Amz-Algorithm=...",
    "file_path": "userId_20250604120000_report.pdf"
}

PDF hochladen

Verwenden Sie die bereitgestellte presigned_url, um Ihr PDF per PUT-Anfrage hochzuladen.

Beispielanfrage

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_report.pdf...' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@report.pdf'

PDF erkennen

Reichen Sie ein PDF ein, das bereits in den Object Storage hochgeladen wurde.

Anfragekörper

  • url (erforderlich): Öffentliche Object-Storage-URL des hochgeladenen PDFs.
  • key (erforderlich): Ihr API-Schlüssel.
  • model: `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4` oder `pdf_detector` (neueste). Standard ist `pdf_detector/v4`.
POST https://detect-text.truthscan.com/detect-pdf

Beispielanfrage — Standard (v4 / neueste Version)

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect-pdf' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-bucket.region.digitaloceanspaces.com/userId_20250604120000_report.pdf",
  "key": "YOUR-API-KEY-GOES-HERE"
}'

Beispielanfrage — v1 festlegen (KI-Generierungs-Metadaten)

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect-pdf' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-bucket.region.digitaloceanspaces.com/userId_20250604120000_report.pdf",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "pdf_detector/v1"
}'

Beispielantwort

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_detector/v4",
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Die Antwort enthält die vom Server zugewiesene Dokument-ID. Verwenden Sie `POST /query`, um Ergebnisse abzufragen. Die typische Bearbeitungszeit beträgt wenige Sekunden.

Abfragen

Status und Ergebnisse der PDF-Erkennung anhand der Dokument-ID abfragen (derselbe Endpunkt wie bei der Texterkennung). Das Antwortformat hängt vom für den Job verwendeten `model` ab.

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

Beispielanfrage

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

Beispielantwort — v1 KI-Fingerabdruck gefunden

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "Tampering Detected",
    "result_details": {
        "prediction": "Grok",
        "base_category": "Possibly AI Generated/Edited"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": null
    },
    "retry_count": 0
}

v1-Felder

  • label: "Tampering Detected", wenn markiert; andernfalls "No Tampering Detected".
  • result_details.prediction: Spezifischer Toolname (z. B. "Grok", "ChatGPT"), generisches "AI Generated" oder "No Tampering Detected".
  • result_details.base_category: "Possibly AI Generated/Edited" oder "No Tampering Detected".
  • source_details.source: Zugeordnete Quelle bei einem Treffer; null, wenn kein Fingerabdruck gefunden wird.

Beispielantwort — v1 kein KI-Fingerabdruck

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "No Tampering Detected",
    "result_details": {
        "prediction": "No Tampering Detected",
        "base_category": "No Tampering Detected"
    },
    "result_categories": null,
    "source_details": null,
    "retry_count": 0
}

Beispielantwort — v3 strukturelle Manipulation erkannt

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Tampered",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Tampered",
            "rule": { "hidden": "high" },
            "max_severity": "high",
            "signals_flagged": 1,
            "signals": {
                "hidden": {
                    "label": "Hidden Text",
                    "flagged": true,
                    "severity": "high",
                    "findings": [
                        {
                            "severity": "high",
                            "detail": "Invisible or off-page text detected on page 1."
                        }
                    ]
                }
            }
        },
        "detailed_explanation": "Hidden text was found on page 1 that is not visible in the rendered document."
    }
}

Beispielantwort — v3 keine Manipulation erkannt (Genuine)

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Genuine",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Genuine",
            "rule": {},
            "max_severity": null,
            "signals_flagged": 0,
            "signals": {
                "hidden": { "label": "Hidden Text", "flagged": false, "severity": null, "findings": [] }
            }
        },
        "detailed_explanation": "No AI-generation or tampering fingerprints were detected; the PDF looks clean."
    }
}

Beispielantwort — v4 (gleiches Format wie v3)

v4 liefert dasselbe Antwortformat wie v3. Das Feld `model` zeigt `pdf_detector/v4`.

v3 / v4-Felder

  • label: Spiegelt `structure.prediction` wider: "Tampered", "Suspicious" oder "Genuine".
  • result_details.structure.signals: Aufschlüsselung für das `hidden`-Signal. Enthält `label`, `flagged`, `severity` und `findings` (mit optionalen `changes`, die Vorher/Nachher-Werte anzeigen, wenn verfügbar).
  • result_details.detailed_explanation: Natürlichsprachliche Zusammenfassung der Befunde.

Urteilsstufen

  • Tampered: Starke Hinweise auf Inhaltsmanipulation oder KI-generierte Herkunft.
  • Suspicious: Ein oder mehrere Signale erkannt, aber keines auf dem höchsten Konfidenzniveau.
  • Genuine: Keine Manipulationssignale erkannt.

Schweregrade

Jeder Befund verwendet `"low"`, `"medium"` oder `"high"`, um die Konfidenz anzugeben.

Fehler

Die meisten Fehler entstehen durch falsche Parameter, die an die API gesendet werden. Überprüfen Sie die Parameter jedes API-Aufrufs, 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.
403Verboten -- Der API-Schlüssel ist ungültig oder es sind nicht genügend Credits vorhanden (1.000 pro PDF-Seite).
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 kein JSON ist.
410Gone -- Die Ressource an diesem Endpunkt wurde entfernt.
422Invalid Request Body -- Ihr Anforderungstext ist falsch formatiert oder ungültig oder enthält 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 erneut.
503Service Unavailable -- Wir sind vorübergehend wegen Wartungsarbeiten offline. Bitte versuchen Sie es später erneut.

Benötigen Sie Hilfe?

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

Kontaktieren Sie uns

API Frequently Asked Questions

Find answers to the most common questions about our AI PDF detection API.