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_IDVervang $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/detectDrempel
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/queryVoorbeeldverzoek
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 lijktresult_categories.advanced: Geavanceerde resultaatcategorie met gelaagde scoring (1-99 formaat)result_categories.standard: Standaard resultaatcategorieanalysis_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-creditsVoorbeeldverzoek
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 tekstanalysis_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 tekstanalysis_results.detailedReasoning: Uitleg van 2-4 zinnen waarom de tekst zo is geclassificeerdanalysis_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_IDVoorbeeldcode
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/detectVoorbeeldverzoek
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.
Veelgestelde vragen over de API
Antwoorden op de meest gestelde vragen over onze AI-detectie-API.