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

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 auf KI-Generierungs-Fingerabdrücke anhand von PDF-Metadaten (`/Creator`, `/Producer`). PDFs müssen zuerst in den Object Storage hochgeladen und dann zur asynchronen Verarbeitung eingereicht werden. Pollen Sie `/query`, bis `status` `done` ist.

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` und Ihrem API-`key` (`document_type` wird automatisch auf PDF gesetzt).
  • `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. Andere Dateitypen werden in diesem Ablauf abgelehnt.

Credit-Abzug

Die PDF-Erkennung zieht 1.000 Credits pro Seite ab. Ein 5-seitiges PDF verbraucht 5.000 Credits. Prüfen Sie Ihr Guthaben 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://ai-detect.undetectable.ai/get-presigned-url

Beispielanfrage

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

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' # Attachment

PDF erkennen

Reichen Sie ein PDF ein, das bereits in den Object Storage hochgeladen wurde. Dieser Endpunkt stellt die Metadatenanalyse und optional die textbasierte KI-Erkennung in die Warteschlange.

Schwellenwert

Für PDF-Jobs (Modell: `pdf_metadata_detector`) ist `result` immer 100.0 (Fingerabdruck erkannt → `label`: "AI") oder 0.0 (kein Fingerabdruck → `label`: "Human"). Die 50/60-Schwellenwerte für Mensch/KI gelten nur für die Texterkennung (Modell: `xlm_ud_detector`).

Antwortfelder

Pollen Sie `/query` für das Dokument. Bei PDF-Jobs (Modell: `pdf_metadata_detector`) enthält `result_details` `prediction`, `rule`, `base_category` und `basic_source` auf oberster Ebene. Die rohen Creator-/Producer-Werte des PDFs werden nicht zurückgegeben; sie werden intern verwendet und bei einem Treffer in `rule` widergespiegelt. `service_type` ist immer `detector`, und `model` bleibt für die gesamte Laufzeit des Jobs `pdf_metadata_detector`.

POST https://ai-detect.undetectable.ai/detect-pdf

Beispielanfrage

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/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",
  "retry_count": 0
}'

Optionale Parameter

  • Übergeben Sie `"id"`, um Ihre eigene Dokument-UUID anzugeben (darf noch nicht existieren).
  • Übergeben Sie `"generate_analysis_details": true`, um eine tiefe Textanalyse anzufordern, wenn Text-KI ausgeführt wird (gleiches Verhalten wie Text-`/detect`).
  • Sie können auch `POST /detect` mit `"document_type": "File"` für dasselbe Verhalten verwenden.

Beispielantwort

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_metadata_detector",
    "result": null,
    "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 für reine Metadaten-Jobs; Jobs mit zusätzlicher Text-KI können je nach extrahierter Wortanzahl länger dauern.

Abfragen

Status und Ergebnisse der PDF-Erkennung anhand der Dokument-ID abfragen (derselbe Endpunkt wie bei der Texterkennung).

POST https://ai-detect.undetectable.ai/query

Beispielanfrage

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

Beispielantwort (Metadaten-KI erkannt)

{
    "id": "49b5a390-2285-47fe-a161-303b4e22406f",
    "model": "pdf_metadata_detector",
    "status": "done",
    "result": 100.0,
    "result_details": {
        "prediction": "Grok",
        "rule": "PyMuPDF - Creator: Grok xAI",
        "base_category": "Possibly AI Generated/Edited",
        "basic_source": "Grok"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": 1000
    },
    "retry_count": 0,
    "label": "AI"
}

Wenn zusätzlich Text-KI ausgeführt wird, kann `model` `xlm_ud_detector` sein, `result_details` enthält sowohl Detektor-Scores als auch `pdf_metadata`, und `source_details` kann zusammengeführte Metadaten-/Text-Zuordnung enthalten.

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.