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

OptionWhen omittedMeaning
modelOperator's preprocessing.pii_modelDetector model, not the main inference model
entitiesAll eight categoriesperson, address, email, phone, iban, identifier, date_of_birth, organization
threshold0.5Native detector confidence threshold from zero to one; lower values accept more reported spans, but cannot recover an unreported span
restoretrueAllows 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.

SignalInterpretation
Direct endpoint reports no span for the valueNo accepted detection; unchanged text is expected, not evidence of restoration
Direct endpoint reports a span and masked contains its placeholderDetection and direct transformation worked for that request; this alone does not prove the chat provider body
Captured inference request contains the placeholderTransformation happened before inference
Inference response contains that placeholder, client response contains its originalConsistent 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

SituationBehavior
No detector configured501 feature_unavailable, non-retryable and without Retry-After; retrying cannot configure it
No route meets policy, including ZDRNo unauthorized detector call; check field issues and remedy_hint
Detector failure or unusable outputAn eligible fallback or an error; required redaction must not silently become unmasked inference
Optional native detection with operator-approved fail_openA detection failure may allow original text to reach inference; restore: false does not disable this exception
Later inference failsAlready 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.