API-Dokumentation

KI-Texterkennungs-API

Vollständige Dokumentation zur Integration der KI-Erkennungs-API von TruthScan 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.

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.

Für WebSocket-Szenarien müssen Sie Ihre Organization ID als Teil der URL senden. Sie können Ihre Organization ID oben auf der Seite in unserem Entwicklerportal.

TruthScan erwartet, dass Ihre Organization ID in der URL aller WebSocket-Anfragen enthalten ist. Die Dokumentation sieht wie folgt aus:

wss://detect-text.truthscan.com/ws/$ORG_ID

Sie müssen $ORG_ID durch Ihre persönliche Organization ID ersetzen.

KI-Detektor

Erkennen

Dieser Endpunkt ermöglicht es Ihnen, Text zur KI-Erkennung einzureichen. Mindestens 200 Wörter werden für beste Genauigkeit empfohlen.

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

Schwellenwert

Dieser Endpunkt gibt eine "result"-Bewertung von 1-100 zurück. Für beste Genauigkeit wird jede Bewertung unter 50 als definitiv menschlich betrachtet. 50-60 ist möglicherweise KI. Über 60 ist definitiv KI. Dies ist das genaueste Ergebnis mit 99%+ Genauigkeit.

Die Bewertungen für andere Detektoren wie Writer und Copyleaks sind ungefähr und nicht so genau wie die Haupt-"result"-Bewertung.

Zeilenumbrüche

Wenn Sie Daten als JSON senden, sollten Zeilenumbrüche als \n innerhalb der Zeichenfolge codiert werden.

Beispielanfrage

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0
}'

Hier muss die Anfrageeingabe weniger als 30.000 Wörter betragen.

Beispielantwort

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Die Antwort enthält die vom Server zugewiesene ID des Dokuments. Zu diesem Zeitpunkt befindet sich das Dokument nun in der Warteschlange zur Verarbeitung. Sie können den /query-API-Endpunkt verwenden, um den Status der KI-Erkennungsanfrage abzufragen. Die durchschnittliche Zeit zum Abschließen einer KI-Erkennungsprüfung beträgt 2-4 Sekunden. Es kann je nach Wortanzahl länger dauern.

Abfragen

Dieser Endpunkt akzeptiert eine Dokument-ID, die von der /detect-Anfrage zurückgegeben wird. Und gibt den Status der Dokumentenübermittlung sowie das Ergebnis der KI-Erkennungsoperation zurück, wie von verschiedenen KI-Detektoren von Drittanbietern behandelt.

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

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0
    },
    "status": "done",
    "retry_count": 0
}

Hier zeigt "result": 12.0 die Menschlichkeit der Eingabe an. Dies bedeutet, dass der Text definitiv menschlich ist, da er unter dem Schwellenwert von 50% liegt. Ebenso geben die Werte unter result_details die Menschlichkeit der Eingabe an. Zum Beispiel bedeutet "scoreZeroGPT": 50.0, dass der Text laut ZeroGPT wahrscheinlich zu 50% von Menschen geschrieben wurde. Das Gleiche gilt für die anderen Detektoren.

Benutzerguthaben prüfen

Dieser Endpunkt akzeptiert den API-Schlüssel des Benutzers über den Header und gibt Details zum Benutzerguthaben zurück.

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

Beispielanfrage

curl -X 'GET' \
  'https://detect-text.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
}

KI-Erkennung auf Satzebene

Der KI-Detektor auf Satzebene läuft auf einem WebSocket-basierten Protokoll.

Hier sind die notwendigen Schritte, um Ergebnisse auf Satzebene für Ihren Text zu erhalten:

  • Mit dem WebSocket verbinden
  • Auf alle Ereignisse lauschen, die vom WebSocket empfangen werden
  • Eine document_watch-Anfrage senden
  • Ein document_id-Ereignis empfangen
  • Nehmen Sie die von der document_id-Antwort generierte ID und reichen Sie ein Dokument zur KI-Erkennung ein
  • Beginnen Sie, document_chunk-Ereignisse zu empfangen. document_chunk-Ereignisse geben jeden Satz zusammen mit dem Ergebnis auf Satzebene zurück
  • Wenn die Dokumentverarbeitung abgeschlossen ist, erhalten Sie ein document_done-Ereignis

Mit dem WebSocket verbinden

Dieser Endpunkt ermöglicht es Ihnen, die WebSocket-Verbindung herzustellen

wss://detect-text.truthscan.com/ws/$ORG_ID

Beispielcode

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

Auf alle Ereignisse vom WebSocket lauschen

Sobald die WebSocket-Verbindung hergestellt ist, lauschen Sie auf Ereignisse, die über die WebSocket-Verbindung gesendet werden.

Beispielcode

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Eine document_watch-Anfrage senden

Zeigen Sie Interesse daran, ein Dokument zu senden, indem Sie eine document_watch-Anfrage über das WebSocket senden

Beispielcode

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Ein document_id-Ereignis empfangen

Nachdem Sie ein document_watch-Ereignis gesendet haben, gibt der Server ein document_id-Ereignis zurück.

Beispielantwort

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Eine KI-Erkennungsanfrage einreichen

Nehmen Sie die von der document_id-Antwort generierte ID und reichen Sie ein Dokument zur KI-Erkennung ein

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

Beispielanfrage

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Ergebnisse auf Satzebene empfangen

Beginnen Sie, document_chunk-Ereignisse zu empfangen. document_chunk-Ereignisse geben jeden Satz zusammen mit dem Ergebnis auf Satzebene zurück

Beispielantworten

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Wenn die Dokumentverarbeitung abgeschlossen ist, erhalten Sie ein document_done-Ereignis.

Beispielantworten

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

Umgang mit außergewöhnlichen Umständen

Wenn der Server aus irgendeinem Grund einen Fehler beim Durchführen der KI-Erkennung feststellt, wird ein document_error-Ereignis an den WebSocket-Client gesendet. Der Client sollte entsprechend handeln, zum Beispiel wird eine Benutzeroberfläche eine Fehlermeldung anzeigen.

Zum Beispiel sendet der Server einen REQUEST_TIMEOUT-Fehlercode, wenn es mehr als 20 Sekunden zwischen Chunk-Ereignissen dauert.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

Stornierungen

Es wird Fälle geben, in denen die Benutzeroberfläche die Operation abbrechen möchte. Der Benutzer entscheidet sich, das Fenster zu schließen, oder bricht das Ereignis explizit ab.

Wenn dies geschieht, sollten Sie ein document_halt-Ereignis senden

Beispielantworten

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

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.
403Forbidden -- Der API-Schlüssel ist ungültig oder es sind nicht genügend Credits vorhanden (0,1 pro Wort).
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.

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 Credits" (403)

Ursache: Unzureichende Credits für Textverarbeitung

Lösung:

  1. Überprüfen Sie Ihre verbleibenden Credits mit /check-user-credits
  2. Kaufen Sie bei Bedarf zusätzliche Credits
  3. Verwenden Sie kürzere Texteingaben, um weniger Credits zu verbrauchen

Eingabevalidierungsprobleme

"Eingabetext darf nicht leer sein" (400)

Ursache: Leerer oder nur Leerzeichen enthaltender Text eingereicht

Lösung:

  1. Stellen Sie sicher, dass Ihre Texteingabe nicht leer ist
  2. Entfernen Sie führende/nachfolgende Leerzeichen
  3. Überprüfen Sie, ob die Textkodierung korrekt ist

"Eingabe-E-Mail ist leer" (400)

Ursache: Fehlende E-Mail für URL-Verarbeitung

Lösung:

  1. Geben Sie beim Einreichen von URLs eine gültige E-Mail-Adresse an
  2. Überprüfen Sie, ob das E-Mail-Format korrekt ist

Verarbeitungsprobleme

"Anfrage-Zeitüberschreitung" (WebSocket)

Ursache: Dokumentverarbeitung dauerte zu lange (>120 Sekunden)

Lösung:

  1. Versuchen Sie es mit einer kürzeren Texteingabe
  2. Überprüfen Sie, ob der Dienst eine hohe Auslastung hat
  3. Wiederholen Sie die Anfrage

Dokumentstatus "fehlgeschlagen"

Ursache: Die Verarbeitung ist aus verschiedenen Gründen fehlgeschlagen

Lösung:

  1. Überprüfen Sie, ob der Eingabetext die Mindestanforderungen erfüllt
  2. Überprüfen Sie, ob der Text in einem unterstützten Format vorliegt
  3. Versuchen Sie es mit einem anderen Modell
  4. Wenden Sie sich an den Support, wenn das Problem weiterhin besteht

WebSocket-Verbindungsprobleme

Verbindungsabbrüche

Ursache: Netzwerkprobleme oder Server-Verbindungsabbrüche

Lösung:

  1. Überprüfen Sie Ihre Netzwerkverbindung
  2. Implementieren Sie eine Wiederverbindungslogik
  3. Überprüfen Sie, ob die WebSocket-URL korrekt ist

"Benutzer nicht gefunden" (WebSocket)

Ursache: Ungültige Organization ID in der WebSocket-Verbindung

Lösung:

  1. Überprüfen Sie, ob die Organization ID korrekt ist
  2. Stellen Sie sicher, dass das Benutzerkonto aktiv ist
  3. Authentifizieren Sie sich bei Bedarf 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

Häufig gestellte Fragen zur API

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