PII redaction
Replace detected personal information before a request reaches an inference route.
Understand the boundary
The pii-redact plugin scans supported text at an approved detector. The gateway replaces validated detections with typed placeholders before sending the text to the inference route.
- The detector receives original text. Masking does not hide it from that provider.
- Only reported, accepted spans are replaced. Missed detections and excluded categories remain unchanged and can reach inference.
- This is not proof of anonymization and does not cover arbitrary binary attachments.
Use only data your application is allowed to process.
Request explicit redaction
The example uses a synthetic reserved email address, requests email and disables gateway restoration with restore: false.
curl
curl --request POST \
--url 'https://api.tokenlane.de/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}'
node
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}, {});
console.log(response);
python
import os
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
"max_tokens": 400,
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}''')
response = client.chat.completions.create(
model=body["model"],
messages=body["messages"],
max_tokens=body["max_tokens"],
extra_body=json.loads(r'''{
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
}''')
)
print(response)
vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
model: tokenlane("deepseek/deepseek-v4-flash-0731"),
messages: [
{
"role": "user",
"content": "Summarize this contact: lena@example.invalid"
}
],
maxOutputTokens: 400,
providerOptions: { tokenlane: {
"plugins": [
{
"id": "pii-redact",
"entities": [
"email"
],
"threshold": 0.5,
"restore": false
}
]
} },
});
console.log(result.text);
Defaults and categories
| Option | When omitted | Meaning |
|---|---|---|
model | Operator's preprocessing.pii_model | Detector model, not the main inference model |
entities | All eight categories | person, address, email, phone, iban, identifier, date_of_birth, organization |
threshold | 0.5 | Native detector confidence threshold from zero to one; lower values accept more reported spans, but cannot recover an unreported span |
restore | true | Allows the gateway to replace recognized placeholders with their originals in the response, subject to enforced rules |
For example, requesting only email does not also request phone detection. Model quality, language and context affect what is reported. LLM locations do not have calibrated confidence; threshold is not a quality guarantee for them.
What restore:false does
With restore: false, the gateway does not restore recognized values from its replacement map in either JSON or SSE responses. The inference request is masked in the same way as with restore: true; restoration changes the response path, not detection.
This is not an output PII filter. An address in an answer may have been missed by the detector, excluded by category, or generated independently by the inference model. Its presence alone does not prove gateway restoration or what the inference provider received. Conversely, a model can change or omit placeholders, so restore: true cannot guarantee a complete round trip.
Preserve enforced policy
Organization and key rules can require redaction independently of the plugin. Requests cannot disable those rules, narrow their categories, raise their confidence threshold or enable restoration that a rule forbids. Conditions are evaluated for each actual inference route, including fallback routes; an explicitly exempt route may receive original text.
The detector has its own routed request. Model, provider, country, jurisdiction, price and zero-data-retention requirements also apply to the detector that receives the originals. A masked inference request does not exempt detection from those requirements.
Diagnose a visible original value
Use synthetic local inputs and a controlled inference endpoint when verifying the data path. Do not log real personal information or replacement maps.
| Signal | Interpretation |
|---|---|
| Direct endpoint reports no span for the value | No accepted detection; unchanged text is expected, not evidence of restoration |
Direct endpoint reports a span and masked contains its placeholder | Detection and direct transformation worked for that request; this alone does not prove the chat provider body |
| Captured inference request contains the placeholder | Transformation happened before inference |
| Inference response contains that placeholder, client response contains its original | Consistent with restoration when allowed; with restore: false this needs investigation |
Use the same text, model, categories and threshold for comparisons. Routing and detector output can differ between separate requests. The direct PII endpoint returns masked and validated spans without main inference; LLM detection itself still makes model calls.
Detector failures and costs
| Situation | Behavior |
|---|---|
| No detector configured | 501 feature_unavailable, non-retryable and without Retry-After; retrying cannot configure it |
| No route meets policy, including ZDR | No unauthorized detector call; check field issues and remedy_hint |
| Detector failure or unusable output | An eligible fallback or an error; required redaction must not silently become unmasked inference |
Optional native detection with operator-approved fail_open | A detection failure may allow original text to reach inference; restore: false does not disable this exception |
| Later inference fails | Already incurred detection charges can remain |
The direct endpoint always fails closed. LLM detection cannot enable fail_open. A mandatory rule overrides native fail-open behavior, but it does not turn a successful empty detection into proof that the text contains no personal information.
Detection adds processing time and cost separately from main inference. Native models use their character tariff. Approved LLM tasks use actual token prices and may make several sequential calls over overlapping windows; overlaps can be processed again. Receipts retain paid attempts, fallback work and detection charges even if later processing fails. Missing confirmed usage is not free detection.
Choose the detector model
Both the direct endpoint and plugin accept a model ID. A chat model is eligible only with an explicitly approved structured PII task, not simply because it supports chat:
{ "id": "pii-redact", "model": "<approved-model>", "restore": false }
This is a placeholder, not an available model name. Omitting model uses the configured default; null and empty names do not.
LLM tasks return source locations, never replacement text. Exact quotes and Unicode scalar offsets are validated; invalid entries are counted, and entirely invalid nonempty output fails or falls back. Input is bounded to 65,536 UTF-8 bytes with bounded overlapping windows. See the PII guide for limits, receipt fields and native versus LLM pricing.