Met de Text Simplification API zet je een lang nieuwsartikel of een lange webpagina automatisch om naar een eenvoudige versie op taalniveau A2. Je eigen systeem, zoals je CMS, stuurt de tekst naar Tolkie en krijgt een herschreven artikel terug: een titel, een korte inleiding en een paar alinea's met tussenkoppen. Die versie sla je zelf op en laat je zelf zien aan je lezers. De koppeling bouwt je eigen developmentteam of webbouwer.

Wat doet de Text Simplification API?

De API herschrijft lange teksten naar eenvoudig Nederlands op taalniveau A2. Zo kunnen ook mensen die moeite hebben met lezen het nieuws volgen. De API is erop ingericht om feiten, citaten, namen en getallen juist over te nemen.

Je stuurt de volledige tekst in. Opmaak voor tussenkoppen is niet nodig, want de API maakt zelf een nieuwe opbouw. Afbeeldingen, bijschriften en ingesloten media zoals video's komen niet terug. Die voeg je zelf weer toe aan de eenvoudige versie.

Hoe gebruiken andere organisaties de API?

Omroep Brabant en NH Nieuws gebruiken de API voor hun nieuwsartikelen. Omroep Brabant heeft eigen knoppen in het CMS. Met één klik maakt een redacteur via de API een eenvoudige versie van een artikel. Die versie wordt opgeslagen, en lezers openen hem op de website met de knop Hulp bij lezen. NH Nieuws werkt op een vergelijkbare manier.

Wie toont de eenvoudige versie aan de lezer?

Dat doen jullie zelf. Tolkie levert alleen de tekst, niet de knoppen of de vormgeving. Je bepaalt dus zelf waar en hoe de eenvoudige versie op je website verschijnt. De koppeling bouwt jullie eigen developmentteam of webbouwer. Tolkie denkt mee, geeft advies en beantwoordt vragen, zodat jullie goed weten hoe je de koppeling zelf maakt.

Kan ik de schrijfstijl bijsturen?

De AI-instructies die je in Mijn Tolkie instelt, gelden niet voor de Text Simplification API. Ze hebben dus geen invloed op de tekst die deze API teruggeeft. Heb je wensen voor de schrijfstijl van de eenvoudige versie? Mail dan naar [email protected], dan kijken we samen wat mogelijk is.

Hoe krijg ik toegang tot de API?

Voor de API heb je een token nodig. Dat krijg je tijdens de implementatie van je contactpersoon bij Tolkie of van support. Wil je de API gaan gebruiken? Neem dan contact met ons op via de contactpagina.

Hoe werkt de API technisch?

Dit deel is bedoeld voor developers. Het endpoint herschrijft lange teksten, zoals nieuwsartikelen of beleidspagina's, naar Nederlands op taalniveau A2, voor volwassen lezers die moeite hebben met lezen. De uitvoer is opgebouwd als een kort nieuwsartikel: een titel, een inleiding en een aantal alinea's met tussenkoppen.

Dit endpoint hoort bij de openbare v1-API, niet bij /api/v2/.

Onderdeel	Waarde
Methode	`POST`
Pad	`/api/v1/tolkie/simplify_text`
Volledige URL (voorbeeld)	`https://<jouw-api-host>/api/v1/tolkie/simplify_text`

Hoe authenticeer je een aanvraag?

Stuur bij elke aanvraag het API-token van jullie organisatie mee:

Authorization: Token <jouw_api_token>
Content-Type: application/json

Status	Betekenis
401 Unauthorized	Het token ontbreekt of is ongeldig.
404 Not Found	Het token is geldig, maar er is geen Tolkie-klant aan deze gebruiker gekoppeld.

Anders dan de meeste /api/v2/-endpoints van de leeshulp past dit endpoint CheckOriginPermission niet toe. Voor de autorisatie heb je dus geen Origin-header en geen url_field in de body nodig. Je integratie mag Origin wel meesturen voor CORS in de browser, maar de server gebruikt die niet voor de toegangscontrole van dit endpoint.

Wat stuur je mee in de aanvraag?

Veld	Type	Verplicht	Beschrijving
`text`	`string`	Ja	De volledige brontekst die je wilt vereenvoudigen

Validatieregels

Minimale lengte: 250 tekens. Een kortere tekst geeft 400.
De tekst mag na het weghalen van spaties aan het begin en eind niet leeg zijn. Een lege tekst of een tekst met alleen spaties kan in de vereenvoudigingsstap 500 geven.

Hoe volg je een aanvraag terug?

Elk antwoord bevat de header X-Request-ID. Je kunt ook zelf een ID meesturen:

X-Request-ID: your-tracking-id-123

Het ID is 1 tot 64 tekens lang en bestaat uit letters, cijfers en koppeltekens. Bij validatiefouten staat dezelfde waarde soms ook als "request_id" in de body. Stuur dit ID mee als je support om hulp vraagt.

Hoe ziet een voorbeeldaanvraag eruit?

POST /api/v1/tolkie/simplify_text
Authorization: Token abc123...
Content-Type: application/json

{
  "text": "Hier volgt een lang artikel of paginatekst met minstens 250 tekens. De inhoud beschrijft wat er is gebeurd, wie erbij betrokken was, en waarom het relevant is voor de lezer. ..."
}

Wat krijg je terug?

Bij een geslaagde aanvraag (200 OK) krijg je JSON terug, opgebouwd als een nieuwsartikel. Dit zijn de velden:

Veld	Type	Beschrijving
`title`	`string`	Korte, duidelijke kop
`intro`	`string`	2 tot 3 zinnen met de kern van het nieuws
`paragraphs`	`array`	Een aantal onderdelen (meestal maximaal ongeveer 5)
`paragraphs[].heading`	`string`	Tussenkop, kort en geschreven als een zin
`paragraphs[].text`	`string`	Tekst van het onderdeel, met korte zinnen volgens de regels voor A2

Voorbeeldantwoord

{
  "title": "Grote brand in centrum",
  "intro": "Er is gisteravond brand geweest in het centrum. Niemand raakte gewond. De politie onderzoekt de oorzaak.",
  "paragraphs": [
    {
      "heading": "De brand begon in een winkel.",
      "text": "Om 22:00 uur zagen mensen rook. De brandweer kwam snel. Na 1 uur was het vuur uit."
    },
    {
      "heading": "De winkel blijft dicht.",
      "text": "De eigenaar mag nog niet naar binnen. De schade is groot."
    }
  ]
}

De precieze formulering en het aantal onderdelen hangen af van de tekst die je instuurt. De AI-instructies uit Mijn Tolkie hebben hier geen invloed op.

Hoe vereenvoudigt de API de tekst?

Taalniveau: de tekst wordt herschreven naar taalniveau A2 (ERK, in het Engels CEFR): eenvoudige woorden, korte zinnen, actieve zinnen en geen uitdrukkingen.
Opbouw: het antwoord volgt de vorm titel, inleiding en alinea's, en is dus geen platte lijst met zinnen.
Trouw aan de bron: de API krijgt de opdracht om feiten, citaten, namen en getallen juist over te nemen. Citaten blijven waar het kan letterlijk.

Welke foutmeldingen kun je krijgen?

400 Bad Request: validatiefout

Het veld text ontbreekt of de tekst is korter dan 250 tekens:

{
  "text": ["Text must be at least 250 characters long."]
}

Validatiefouten kunnen ook request_id bevatten als je een correlatie-ID gebruikt (zie hierboven).

404 Not Found: klant ontbreekt

{
  "error": "Client not found."
}

401 en 500

Een 401 betekent dat het token ontbreekt of ongeldig is. Een 500 kan optreden als de tekst leeg is of alleen uit spaties bestaat.

Waar kan ik terecht met vragen?

Heb je vragen over de koppeling of loop je ergens tegenaan? Mail naar [email protected] en stuur de X-Request-ID mee. Wil je de API gaan gebruiken? Neem dan contact op via de contactpagina.

Hoe vereenvoudig ik nieuwsartikelen met de Text Simplification API?