API

Démarrage rapide

1. Connectez-vous (Connexion / Inscription) et créez une clé API sous Setup → API keys. 2. Envoyez un texte :

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"}'

La réponse contient le texte voilé et la liste de ce qui a été remplacé :

{
  "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 }
}

Authentification

Adresse de base : https://api.aidataveil.eu. Envoyez votre clé dans l’en-tête Authorization: Bearer veil_…. Gardez les clés secrètes. Un compte peut avoir jusqu’à 5 clés, et vous pouvez supprimer une clé à tout moment.

Requête : POST /v1/anonymize

Réponse

Textes courts et longs

Les textes jusqu’à 1 000 tokens (environ 3 500 caractères, un long e-mail) reçoivent une réponse immédiate. Les textes plus longs sont acceptés et traités en arrière-plan ; vous récupérez le résultat plus tard. Les requêtes courtes ne sont pas retardées : elles passent toujours en premier.

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

Récupérez le résultat avec GET result_url. Le statut est queued, processing, done ou failed. Un résultat terminé arrive par blocs de 10 000 caractères au plus, chacun avec un lien vers le suivant :

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": { … }
}

• Les espaces réservés sont identiques dans tous les blocs : [PERSON_1] désigne toujours le même terme. Chaque bloc liste les remplacements qu’il contient.
• infos, usage et meta figurent dans le premier bloc.
• Récupérer le bloc N+1 confirme que le bloc N est bien arrivé ; il est alors libéré (410 block_released si vous le redemandez). Si une connexion est interrompue, demandez simplement le même bloc à nouveau.
• Le next_url du dernier bloc (next_is_confirmation: true) confirme la réception et supprime la requête. Sans confirmation, le résultat est supprimé 60 minutes après la récupération du dernier bloc, au plus tard après 24 heures. DELETE /v1/requests/{id} supprime immédiatement.
• "async": true traite aussi les textes courts en arrière-plan (même prix). "async": false exige une réponse immédiate ; un texte trop long est refusé avec 413 too_large_for_immediate.

Un exemple complet en 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

Sous Setup → Rule sets, vous rassemblez vos propres termes : les mots toujours remplacés (noms de projets, numéros de clients) et ceux jamais remplacés (votre entreprise, vos produits). Associez un rule set à une clé comme valeur par défaut ou nommez-le par requête avec ruleset.

Outre des termes, un rule set peut contenir des champs : des valeurs de forme fixe, par exemple un numéro de commande. Vous créez un champ sous Setup → Rule sets en collant un texte d’exemple et en cliquant sur la valeur ; nous construisons le motif pour vous, et vous lui donnez un nom technique comme Ordernumber. Chaque résultat est renvoyé sous infos.Ordernumber et, si vous le souhaitez, remplacé dans le texte. Les champs du rule set et les rules de la requête fonctionnent ensemble.

Tokens, limites et facturation

• Seuls les tokens sont facturés. Un token est un petit fragment de mot, d’environ 3 à 4 caractères. Chaque réponse indique la taille sous usage.
• POST /v1/tokens avec {"text": "…"} renvoie le nombre de tokens et si le texte recevrait une réponse immédiate. Le texte n’est pas traité, c’est gratuit.
• La limite mensuelle de tokens appartient au compte et vaut pour toutes les clés ensemble ; créer d’autres clés ne l’augmente pas.
• Par défaut, l’API s’arrête à la limite et répond 429 quota_exceeded jusqu’au mois suivant ou jusqu’à l’extension de l’offre. Continuer et facturer ensuite les tokens supplémentaires sera proposé avec les offres payantes ; nous le configurons pour vous.
• Les propriétaires reçoivent un e-mail lorsque la prévision du mois passe à l’orange ou au rouge, s’ils l’ont activé dans leur profil.

Erreurs

Traitement des données

• Les textes sont traités sur nos propres serveurs en Europe, avec des modèles exécutés localement. Aucun service d’IA externe n’intervient et rien n’est utilisé pour l’entraînement.
• Les requêtes immédiates sont traitées en mémoire. Nous ne stockons que des compteurs (requêtes, tokens), jamais le texte.
• Les requêtes en arrière-plan sont la seule exception : le texte est stocké chiffré jusqu’à son traitement, puis supprimé ; le résultat reste chiffré jusqu’à sa récupération (libéré bloc par bloc), 24 heures au plus.