API-documentatie

AI-tekstdetectie-API

Volledige documentatie voor het integreren van de AI-detectie-API van TruthScan in uw applicaties.

Probeer het zonder code via ons FastAPI-eindpunt: https://detect-text.truthscan.com/docs

Authenticatie

TruthScan gebruikt API-sleutels voor toegang tot de API. U vindt uw API-sleutel bovenaan de pagina in ons ontwikkelaarsportaal.

TruthScan verwacht dat de API-sleutel in alle API-verzoeken naar de server wordt opgenomen in een request body die er als volgt uitziet:

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

Vervang YOUR API KEY GOES HERE door uw persoonlijke API-sleutel.

Voor web socket-scenario's moet u uw Organization ID in de URL opnemen. U vindt uw Organization ID bovenaan de pagina in ons ontwikkelaarsportaal.

TruthScan verwacht uw Organization ID in de URL van alle web socket-verzoeken. De documentatie ziet er als volgt uit:

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

Vervang $ORG_ID door uw persoonlijke Organization ID.

AI-detector

Detecteren

Met dit eindpunt dient u tekst in voor AI-detectie. Voor de beste nauwkeurigheid worden minstens 200 woorden aanbevolen.

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

Drempel

Dit eindpunt geeft een "result"-score van 1–100. Voor de beste nauwkeurigheid: onder 50 = zeker menselijk, 50–60 = mogelijk AI, boven 60 = duidelijk AI. Dit is het meest nauwkeurige resultaat (>99% nauwkeurigheid).

Scores van andere detectors (zoals Writer en Copyleaks) zijn benaderingen en minder nauwkeurig dan de hoofd-"result"-score.

Regeleinden

Bij JSON moeten regeleinden in de string als \n worden gecodeerd.

Voorbeeldverzoek

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
}'

De invoer moet minder dan 30.000 woorden zijn.

Voorbeeldantwoord

{
    "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
}

Het antwoord bevat de door de server toegewezen document-ID. Het document staat in de wachtrij. Gebruik /query voor de status. Gemiddeld duurt een AI-detectie 2–4 seconden; langer bij veel woorden.

Query

Dit eindpunt accepteert een document-id uit /detect en geeft de status en het resultaat van de AI-detectie zoals afgehandeld door verschillende externe detectors.

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

Voorbeeldverzoek

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

Voorbeeldantwoord

{
    "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 geeft "result": 12,0 de "menselijkheid" aan. Onder de 50%-drempel is de tekst zeker menselijk. De waarden onder result_details geven per detector de inschatting van menselijkheid, bijvoorbeeld "scoreZeroGPT": 50,0 volgens ZeroGPT.

Controleer gebruikerscredits

Dit eindpunt accepteert de apikey via de header en geeft creditdetails terug.

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

Voorbeeldverzoek

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'

Voorbeeldantwoord

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

AI-detectie op zinsniveau

De detector op zinsniveau werkt via een WebSocket-protocol.

Stappen om zinsniveau-resultaten voor uw tekst te krijgen:

Maak verbinding met de WebSocket
Luister naar alle events van de WebSocket
Stuur een document_watch-verzoek
Ontvang een document_id-event
Gebruik het id uit document_id en dien een document in voor AI-detectie
Ontvang document_chunk-events: per zin met zinsniveau-resultaat
Als het document klaar is, ontvangt u een document_done-event

Verbind met de WebSocket

Met dit eindpunt stelt u de WebSocket-verbinding in

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

Voorbeeldcode

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

Luister naar alle events van de WebSocket

Na verbinding luistert u naar events over de WebSocket.

Voorbeeldcode

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

Stuur een document_watch-verzoek

Toon interesse in een document door document_watch over de WebSocket te sturen

Voorbeeldcode

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

Ontvang een document_id-event

Na document_watch stuurt de server een document_id-event.

Voorbeeldantwoord

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

Dien een AI-detectieverzoek in

Gebruik het id uit document_id en dien het document in voor AI-detectie

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

Voorbeeldverzoek

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"
}'

Ontvang resultaten op zinsniveau

Ontvang document_chunk-events met elke zin en het zinsniveau-resultaat

Voorbeeldantwoorden

{
    "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
}

Als het document klaar is, ontvangt u een document_done-event.

Voorbeeldantwoorden

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

Uitzonderlijke situaties

Bij een fout tijdens detectie stuurt de server een document_error naar de WebSocket-client. De client moet daarop reageren (bijv. foutmelding in de UI).

Bijvoorbeeld: REQUEST_TIMEOUT als het meer dan 20 seconden tussen chunk-events duurt.

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

Annuleren

Soms moet de UI de actie stoppen: gebruiker sluit het venster of annuleert expliciet

Stuur dan een document_halt-event

Voorbeeldantwoorden

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

Fouten

De meeste fouten komen door onjuiste parameters. Controleer elke API-aanroep en probeer de voorbeeldcode.

De algemene foutcodes volgen de REST-standaard:

Foutcode	Betekenis
400	Bad Request – Uw verzoek is ongeldig.
403	Forbidden – De API-sleutel is ongeldig of er zijn onvoldoende credits (0,1 per woord).
404	Not Found – De opgegeven resource bestaat niet.
405	Method Not Allowed – U probeerde een resource met een ongeldige methode te benaderen.
406	Not Acceptable – U vroeg een formaat dat geen JSON is.
410	Gone – De resource op dit eindpunt is verwijderd.
422	Invalid Request Body – Uw request body is onjuist of mist parameters.
429	Too Many Requests – U stuurt te veel verzoeken. Vertraag het tempo.
500	Internal Server Error – Er ging iets mis op onze server. Probeer later opnieuw.
503	Service Unavailable – We zijn tijdelijk offline voor onderhoud. Probeer later opnieuw.

Veelvoorkomende problemen en oplossingen

Authenticatieproblemen

"User verification failed" (403)

Oorzaak: Ongeldige of verlopen API-sleutel

Oplossing:

Controleer of uw API-sleutel klopt
Controleer of uw API-sleutel actief is in uw account
Genereer zo nodig een nieuwe API-sleutel

"Not enough credits" (403)

Oorzaak: Onvoldoende credits voor tekstverwerking

Oplossing:

Controleer uw resterende credits via /check-user-credits
Koop indien nodig extra credits
Gebruik kortere teksten om minder credits te verbruiken

Validatieproblemen bij invoer

"Input text cannot be empty" (400)

Oorzaak: Lege tekst of alleen spaties ingediend

Oplossing:

Zorg dat de tekstinvoer niet leeg is
Verwijder overbodige spaties aan begin/einde
Controleer of de tekstencoding klopt

"Input email is empty" (400)

Oorzaak: Ontbrekend e-mailadres voor URL-verwerking

Oplossing:

Geef een geldig e-mailadres op bij URL-indieningen
Controleer het e-mailformaat

Verwerkingsproblemen

"Request timeout" (WebSocket)

Oorzaak: Documentverwerking duurde te lang (>120 seconden)

Oplossing:

Probeer met kortere tekst
Controleer of de service hoge belasting heeft
Probeer het verzoek opnieuw

Documentstatus "failed"

Oorzaak: Verwerking om diverse redenen mislukt

Oplossing:

Controleer of de invoertekst aan de minimumvereisten voldoet
Controleer of het formaat wordt ondersteund
Probeer een ander model
Neem contact op met support als het probleem aanhoudt

WebSocket-verbindingsproblemen

Verbinding valt weg

Oorzaak: Netwerkproblemen of serververbinding verbroken

Oplossing:

Controleer uw netwerk
Implementeer opnieuw verbinden
Controleer of de WebSocket-URL klopt

"User not found" (WebSocket)

Oorzaak: Ongeldige Organization ID in de WebSocket-verbinding

Oplossing:

Controleer of de Organization ID klopt
Controleer of het account actief is
Authenticeer opnieuw indien nodig

Hulp nodig?

Voor meer informatie over onze API of technische ondersteuning kunt u contact met ons opnemen.

Neem contact op

Veelgestelde vragen over de API

Antwoorden op de meest gestelde vragen over onze AI-detectie-API.