/v1/text/transformTransform complex German text into simplified formats using AI. Supports Leichte Sprache, Einfache Sprache, and explanatory modes.
Authentication
x-api-key Header
Rate Limit
10 req/min (default)
Base URL
https://api.klao.eu/api
Try it in the Playground
Send live requests, inspect responses, and copy code snippets
The API supports three transformation modes, each designed for a different level of language simplification:
Transforms text into Leichte Sprache (Easy-to-Read German). The content is simplified using very clear vocabulary, short sentences, and structured formatting to make it accessible for people with cognitive disabilities, learning difficulties, or limited language proficiency.
mode: "leichte_sprache"Rewrites text into Einfache Sprache (Plain German). The language is simplified and easier to understand than standard German while still preserving more detail and natural phrasing than Leichte Sprache.
mode: "einfache_sprache"Provides explanations for words within the context of Leichte Sprache. It clarifies difficult terms and offers additional context to help readers better understand the simplified content.
mode: "ls_explain"All API requests require authentication via an API key in the x-api-key header. You can generate API keys from your API Keys page.
x-api-key: klao_xxxxxxxxxxxxxxxxxxKeep your API key secret
Never expose your API key in client-side code or public repositories. Rotate keys immediately if compromised.
Send a JSON body with the following parameters:
{
"mode": "leichte_sprache",
"input_text": "Complex German text...",
"output_format": "html",
"summarize": true
}| Parameter | Type | Description |
|---|---|---|
mode | string | Transformation mode. leichte_spracheeinfache_sprachels_explain |
input_text | string | The German text to transform. Max 10,000 characters. HTML is detected automatically. |
output_format | string | Desired output format. Defaults to plaintext. plaintexthtmlmarkdown |
summarize | boolean | Focus the output on the most important parts, omitting detail. Use this when you want a shorter result rather than a full transformation. Only applies to leichte_sprache and einfache_sprache modes. Defaults to false. truefalse |
stream | boolean | Stream the response as Server-Sent Events (SSE). Each chunk arrives as a delta event. The final event includes usage and timing. Defaults to false. truefalse |
The API automatically detects when input_text contains HTML and handles it intelligently — no schema changes required. The entire HTML document is translated and returned with the original markup, tags, attributes, and links preserved.
Set output_format to plaintext when sending HTML
When the API detects HTML input, it rebuilds the HTML structure itself regardless of output_format. Using plaintext as the format is the safest choice for web app plugins that may send either plain text or HTML — the API handles both correctly.
What counts as HTML input
The API looks for common HTML block and inline tags. Always send well-formed HTML — plain text that happens to contain < and > characters will be treated as plain text.
| Input | Detected as |
|---|---|
<p>Willkommen auf unserer Seite</p> | HTML ✓ |
<h2>Datenschutz</h2><p>Text...</p> | HTML ✓ |
<a href="/link">Mehr erfahren</a> | HTML ✓ |
Wir bieten umfangreiche Dienste an. | Plain text ✓ |
Preserved
Tag attributes (href, class, id, aria-*), link destinations, form structure (label, button, input), SVG icons, table layout, select options. Script, style, code, pre, svg, and math blocks are left untouched.
May be simplified
Decorative inline tags (strong, em, b, i, span) are preserved when they solely wrap text. When mixed with other content inside a block, their text is translated but the tags may be stripped.
Use these examples to quickly integrate the API into your application:
curl -X POST https://api.klao.eu/api/v1/text/transform \
-H "x-api-key: klao_xxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"mode": "leichte_sprache",
"input_text": "Complex German text...",
"output_format": "html",
"summarize": true
}'Standard response
A successful request returns 200 OK with the following JSON body:
{
"success": true,
"data": {
"output_text": "Simplified text...",
"output_format": "html",
"tokens": {
"input": 145,
"output": 89,
"total": 234
},
"mode": "leichte_sprache",
"request_id": "req_7x9k2m4p8q1w3e5r",
"processing_time_ms": 1245
}
}| Field | Description |
|---|---|
data.output_text | The transformed text. |
data.output_format | The output format that was used (plaintext, html, or markdown). |
data.mode | The transformation mode that was applied. |
data.request_id | Unique reference for this request, useful for debugging and support. |
data.tokens.input | Tokens counted from the input. |
data.tokens.output | Tokens generated in the output. |
data.tokens.total | Total tokens billed for this request. |
data.processing_time_ms | Time taken by the AI service to process the request (ms). |
Streaming response
When "stream": true, the response is delivered as Server-Sent Events (SSE). Text is delivered token by token as it is generated.
Event sequence
One or more events during generation. Each carries a text chunk in the "delta" field.
Final event. "delta" is empty string; includes output_format, mode, request_id, tokens (input/output/total), and processing_time_ms.
Sentinel line that signals the stream is closed. Safe to stop reading after this.
Delta events
data: {"id": "f3a1b2c4-5e6f-7890-abcd-ef1234567890", "delta": "Wir bieten "}
data: {"id": "f3a1b2c4-5e6f-7890-abcd-ef1234567890", "delta": "viele Dienste an."}Done event + termination
data: {"id": "f3a1b2c4-5e6f-7890-abcd-ef1234567890", "delta": "", "output_format": "plaintext", "mode": "leichte_sprache", "request_id": "req_7x9k2m4p8q1w3e5r", "tokens": {"input": 48, "output": 12, "total": 60}, "processing_time_ms": 412.3, "done": true}
data: [DONE]| Field | Present in | Description |
|---|---|---|
id | All events | UUID shared across all events in the same request. |
delta | All events | Text chunk to append. Empty string in the done event. |
output_format | Done event | The output format that was used (plaintext, html, or markdown). |
mode | Done event | The transformation mode that was applied. |
request_id | Done event | Unique reference for this request, useful for debugging and support. |
tokens.input | Done event | Tokens counted from the input. |
tokens.output | Done event | Tokens generated in the output. |
tokens.total | Done event | Total tokens billed for this request. |
processing_time_ms | Done event | Wall-clock time from first token to last (ms). |
done | Done event | Always true. Signals this is the final event before [DONE]. |
Streaming with HTML input
When HTML is detected in input_text, the full document must be processed before any output can be returned. Requesting stream: true still works — you will receive a single delta event containing the complete translated HTML, followed immediately by the done event and [DONE].
The API uses standard HTTP status codes. Here are the possible error responses:
Bad Request
Missing or invalid request parameters. Check required fields and enum values.
Unauthorized
Invalid or missing API key. Ensure your key is active and correctly formatted.
Payment Required
Insufficient Tokens. Buy more tokens to continue making requests.
Too Many Requests
Rate limit exceeded. Wait and retry, or check X-RateLimit-Reset header.
Internal Server Error
Something went wrong on our end. Contact support if this persists.
Service Unavailable
AI service is under high demand. Please wait a moment and retry your request.
Every response includes rate limit headers to help you manage usage:
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1704067200| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of requests allowed per minute. |
X-RateLimit-Remaining | Number of requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp (seconds) when the rate limit window resets. |
Test the API interactively
Try the POST /v1/text/transform endpoint directly in your browser — no setup required.