API-documentatie
ISO 27001SOC 2 CertifiedGDPR Compliant

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,
  "generate_analysis_details": true
}'

De invoer moet minder dan 30.000 woorden zijn.

Optionele Parameters

  • model: Te gebruiken AI-detectiemodel (standaard: 'xlm_ud_detector')
  • retry_count: Aantal pogingen bij verwerkingsfouten (standaard: 0)
  • generate_analysis_details: Stel in op 'true' om diepgaande AI-analyseresultaten in te schakelen (standaard: 'false'). Indien ingeschakeld bevat het queryantwoord de velden analysis_results_status en analysis_results.

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,
    "label": "Human",
    "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,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

Resultaatinterpretatie

  • result: Score van 0-100 die de waarschijnlijkheid aangeeft dat de tekst door AI is gegenereerd. Onder 50 = zeker menselijk. 50-60 = mogelijk AI. Boven 60 = zeker AI.
  • label: De algehele bepaling: 'Human', 'AI' of 'Paraphrase'
  • result_details scores: Geschatte scores van externe detectoren: GPTZero, OpenAI, Writer, CrossPlag, CopyLeaks, Sapling, ContentAtScale, ZeroGPT (elk 0, 50 of 100)
  • human: Gemiddelde van alle scores van externe detectoren dat aangeeft hoe menselijk de tekst lijkt
  • result_categories.advanced: Geavanceerde resultaatcategorie met gelaagde scoring (1-99 formaat)
  • result_categories.standard: Standaard resultaatcategorie
  • analysis_results_status: Status van diepgaande AI-analyse ('pending', 'ready', 'skipped' of null). Bij 'pending' blijf het /query-endpoint bevragen — de analyse wordt nog op de achtergrond verwerkt. Bij 'ready' bevat het veld analysis_results de voltooide analyse. Bij 'skipped', null of afwezig is diepgaande analyse niet beschikbaar voor deze tekst.
  • analysis_results: Diepgaande AI-analyseresultaten (beschikbaar wanneer analysis_results_status 'ready' is). Bevat: agreement (strong/moderate/weak/disagreement), confidence (0-100), keyIndicators (array van gevonden tekstindicatoren), detailedReasoning (uitleg), linguisticPatterns (array van waargenomen taalpatronen) en recommendations (uitvoerbare items).

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
}

Analyseresultaten (Asynchrone Diepgaande Analyse)

Wanneer u 'generate_analysis_details' instelt op 'true' in het /detect-verzoek, voert TruthScan een diepgaande AI-analyse uit op de achtergrond nadat de initiële detectie is voltooid. Het initiële queryantwoord retourneert met status 'done' en uw detectieresultaten klaar voor gebruik, maar het veld analysis_results_status kan nog 'pending' zijn. U kunt de initiële resultaten direct gebruiken en optioneel pollen totdat de diepgaande analyse is voltooid.

1. Initieel Resultaat Vastgesteld (Analyse Nog in Behandeling)

Wanneer u indient met 'generate_analysis_details': true en voor het eerst bevraagt met status 'done', zijn de kerndetectieresultaten (result, label, result_details) gereed. Echter, analysis_results_status kan 'pending' zijn — dit betekent dat de diepgaande AI-analyse nog op de achtergrond wordt verwerkt.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

Wat te doen

U kunt de initiële detectieresultaten (result, label, result_details-scores) direct gebruiken. Als u ook de diepgaande analyse nodig heeft, blijf het /query-endpoint bevragen met dezelfde document-ID totdat analysis_results_status verandert van 'pending'.

2. Blijf Pollen voor Analyseresultaten

Blijf het /query-endpoint aanroepen met dezelfde document-ID. Controleer het veld analysis_results_status bij elk antwoord. Wanneer het verandert van 'pending' naar 'ready', wordt het analysis_results-object gevuld.

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

3. Analyse Voltooid — Volledig Antwoord

Zodra analysis_results_status 'ready' is, bevat het analysis_results-object de volledige diepgaande AI-analyse met overeenstemmingsniveau, betrouwbaarheid, belangrijke indicatoren, gedetailleerde redenering, taalpatronen en aanbevelingen.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

Wanneer Analyse Niet Beschikbaar Is

Als analysis_results_status 'skipped', null of afwezig is, wordt er geen diepgaande analyse geproduceerd voor deze tekst. Dit gebeurt wanneer 'generate_analysis_details' niet op 'true' was ingesteld in het /detect-verzoek, of bij bepaalde verwerkingsscenario's. U moet de initiële detectieresultaten als definitief beschouwen.

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Analyseresultaatvelden

  • analysis_results_status: 'pending' = nog in verwerking, 'ready' = resultaten beschikbaar, 'skipped' / null / afwezig = niet beschikbaar voor deze tekst
  • analysis_results.agreement: Hoe sterk de diepgaande analyse overeenkomt met de initiële detectie (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Betrouwbaarheidsscore van de diepgaande analyse (0-100)
  • analysis_results.keyIndicators: Array van specifieke tekstindicatoren gevonden in de tekst
  • analysis_results.detailedReasoning: Uitleg van 2-4 zinnen waarom de tekst zo is geclassificeerd
  • analysis_results.linguisticPatterns: Array van waargenomen taalpatronen (bijv. consistentie in zinsstructuur, woordenschatpatronen)
  • analysis_results.recommendations: Array van uitvoerbare aanbevelingen om de authenticiteit van de tekst te begrijpen

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:

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

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

"Not enough credits" (403)

Oorzaak: Onvoldoende credits voor tekstverwerking

Oplossing:

  1. Controleer uw resterende credits via /check-user-credits
  2. Koop indien nodig extra credits
  3. 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:

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

"Input email is empty" (400)

Oorzaak: Ontbrekend e-mailadres voor URL-verwerking

Oplossing:

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

Verwerkingsproblemen

"Request timeout" (WebSocket)

Oorzaak: Documentverwerking duurde te lang (>120 seconden)

Oplossing:

  1. Probeer met kortere tekst
  2. Controleer of de service hoge belasting heeft
  3. Probeer het verzoek opnieuw

Documentstatus "failed"

Oorzaak: Verwerking om diverse redenen mislukt

Oplossing:

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

WebSocket-verbindingsproblemen

Verbinding valt weg

Oorzaak: Netwerkproblemen of serververbinding verbroken

Oplossing:

  1. Controleer uw netwerk
  2. Implementeer opnieuw verbinden
  3. Controleer of de WebSocket-URL klopt

"User not found" (WebSocket)

Oorzaak: Ongeldige Organization ID in de WebSocket-verbinding

Oplossing:

  1. Controleer of de Organization ID klopt
  2. Controleer of het account actief is
  3. Authenticeer opnieuw indien nodig

Hulp nodig?

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

Veelgestelde vragen over de API

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