API

Schnellstart

1. Melde dich an (Login / Registrieren) und lege unter Setup → API keys einen API-Key an. 2. Sende einen Text:

curl https://api.aidataveil.eu/v1/anonymize \
  -H "Authorization: Bearer $VEIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, I am Anna Schmidt from Berlin, anna@example.com.", "lang": "en"}'

Die Antwort enthält den verschleierten Text und die Liste dessen, was ersetzt wurde:

{
  "text": "Hello, I am [PERSON_1] from [LOCATION_1], [EMAIL_1].",
  "replacements": [
    { "type": "PERSON",   "original": "Anna Schmidt",     "replacement": "[PERSON_1]" },
    { "type": "LOCATION", "original": "Berlin",           "replacement": "[LOCATION_1]" },
    { "type": "EMAIL",    "original": "anna@example.com", "replacement": "[EMAIL_1]" }
  ],
  "infos": {},
  "usage": { "chars": 55, "tokens": 18, "size_class": "S", "weight": 1, "billed_tokens": 18 },
  "meta": { "lang": "en", "mode": "technical", "total_ms": 240 }
}

Anmeldung

Basisadresse: https://api.aidataveil.eu. Sende den Key im Header Authorization: Bearer veil_…. Halte Keys geheim. Ein Account kann bis zu 5 Keys haben, und du kannst einen Key jederzeit löschen.

Anfrage: POST /v1/anonymize

Antwort

Kurze und lange Texte

Texte bis 1.000 Token (etwa 3.500 Zeichen, eine lange E-Mail) werden sofort beantwortet. Längere Texte werden angenommen und im Hintergrund verarbeitet; das Ergebnis holst du später ab. Kurze Anfragen werden dadurch nicht aufgehalten: Sie gehen immer vor.

HTTP/1.1 202 Accepted
{
  "request_id": "6549e33e1121a934ac0ece670c8b5017",
  "status": "queued",
  "tokens": 15900,
  "size_class": "XL",
  "result_url": "/v1/requests/6549e33e1121a934ac0ece670c8b5017",
  "poll_after_seconds": 100
}

Das Ergebnis holst du mit GET result_url ab. Der Status ist queued, processing, done oder failed. Ein fertiges Ergebnis kommt in Blöcken zu höchstens 10.000 Zeichen, jeder mit einem Link auf den nächsten:

GET /v1/requests/6549e33e1121a934ac0ece670c8b5017
{
  "request_id": "6549e33e1121a934ac0ece670c8b5017",
  "status": "done",
  "block": 1,
  "blocks": 7,
  "next_url": "/v1/requests/6549e33e1121a934ac0ece670c8b5017?block=2",
  "next_is_confirmation": false,
  "text": "…first 10,000 characters, veiled…",
  "replacements": [ … only those used in this block … ],
  "infos": {}, "usage": { … }, "meta": { … }
}

• Die Platzhalter sind in allen Blöcken gleich: [PERSON_1] meint immer denselben Begriff. Jeder Block listet die Ersetzungen, die in ihm vorkommen.
• infos, usage und meta stehen im ersten Block.
• Wer Block N+1 abholt, bestätigt damit, dass Block N angekommen ist; Block N wird dann freigegeben (bei erneuter Anfrage 410 block_released). Bricht eine Verbindung ab, fordere denselben Block einfach noch einmal an.
• Die next_url des letzten Blocks (next_is_confirmation: true) bestätigt den Empfang und löscht die Anfrage. Ohne Bestätigung wird das Ergebnis 60 Minuten nach dem Abholen des letzten Blocks gelöscht, spätestens nach 24 Stunden. DELETE /v1/requests/{id} löscht sofort.
• "async": true verarbeitet auch kurze Texte im Hintergrund (gleicher Preis). "async": false verlangt eine sofortige Antwort; ein zu langer Text wird mit 413 too_large_for_immediate abgelehnt.

Ein vollständiges Beispiel in Python:

import os, time, requests

API = "https://api.aidataveil.eu"
H = {"Authorization": "Bearer " + os.environ["VEIL_KEY"]}

def anonymize(text, lang="de"):
    r = requests.post(API + "/v1/anonymize", headers=H, json={"text": text, "lang": lang})
    r.raise_for_status()
    if r.status_code == 200:                      # short text: the answer is here
        return r.json()["text"]
    url = API + r.json()["result_url"]            # 202: processed in the background
    while (block := requests.get(url, headers=H).json())["status"] in ("queued", "processing"):
        time.sleep(10)
    if block["status"] == "failed":
        raise RuntimeError(block["error"])
    parts = []
    while True:
        parts.append(block["text"])
        if block["next_is_confirmation"]:         # last block: confirm, the data is deleted
            requests.get(API + block["next_url"], headers=H)
            return "".join(parts)
        block = requests.get(API + block["next_url"], headers=H).json()

Rule sets

Unter Setup → Rule sets sammelst du eigene Begriffe: Wörter, die immer ersetzt werden (Projektnamen, Kundennummern), und Wörter, die nie ersetzt werden (dein Unternehmen, Produkte). Ordne ein Rule set einem Key als Standard zu oder nenne es je Anfrage mit ruleset.

Neben Begriffen kann ein Rule set Felder enthalten: Werte mit festem Aufbau, etwa eine Bestellnummer. Ein Feld legst du unter Setup → Rule sets an: Beispieltext einfügen, den Wert anklicken, das Muster bilden wir für dich, und du gibst einen technischen Namen wie Ordernumber vor. Jeder Treffer kommt unter infos.Ordernumber zurück und wird auf Wunsch im Text ersetzt. Felder des Rule sets und rules der Anfrage wirken zusammen.

Token, Limits und Abrechnung

• Abgerechnet werden nur Token. Ein Token ist ein kleiner Wortbaustein, etwa 3 bis 4 Zeichen. Jede Antwort zeigt die Größe unter usage.
• POST /v1/tokens mit {"text": "…"} liefert die Token-Zahl und ob der Text sofort beantwortet würde. Der Text wird nicht verarbeitet, es kostet nichts.
• Das monatliche Token-Limit gehört zum Account und zählt für alle Keys zusammen; weitere Keys erhöhen es nicht.
• Standardmäßig stoppt die API am Limit und antwortet mit 429 quota_exceeded, bis der nächste Monat beginnt oder der Tarif erweitert wird. Weiterlaufen und die zusätzlichen Token nachträglich berechnen gibt es mit den bezahlten Tarifen; wir richten es für dich ein.
• Owner bekommen eine E-Mail, wenn die Prognose für den Monat auf Gelb oder Rot wechselt, sofern sie das im Profil eingeschaltet haben.

Fehler

Umgang mit Daten

• Texte werden auf unseren eigenen Servern in Europa verarbeitet, mit Modellen, die lokal laufen. Es ist kein externer KI-Dienst beteiligt, und nichts wird zum Training verwendet.
• Sofortige Anfragen werden im Arbeitsspeicher verarbeitet. Wir speichern nur Zähler (Anfragen, Token), nie den Text.
• Hintergrundanfragen sind die einzige Ausnahme: Der Text liegt verschlüsselt, bis er verarbeitet ist, und wird dann gelöscht; das Ergebnis bleibt verschlüsselt liegen, bis du es abgeholt hast (Block für Block freigegeben), höchstens 24 Stunden.