API

Avvio rapido

1. Accedi (Login / Registrazione) e crea una chiave API in Setup → API keys. 2. Invia un testo:

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 risposta contiene il testo velato e l’elenco di ciò che è stato sostituito:

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

Autenticazione

Indirizzo di base: https://api.aidataveil.eu. Invia la chiave nell’intestazione Authorization: Bearer veil_…. Tieni segrete le chiavi. Un account può avere fino a 5 chiavi e puoi eliminare una chiave in qualsiasi momento.

Richiesta: POST /v1/anonymize

Risposta

Testi brevi e lunghi

I testi fino a 1.000 token (circa 3.500 caratteri, una lunga e-mail) ricevono una risposta immediata. I testi più lunghi vengono accettati ed elaborati in background; il risultato si ritira più tardi. Le richieste brevi non ne risentono: hanno sempre la precedenza.

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

Ritira il risultato con GET result_url. Lo stato è queued, processing, done o failed. Un risultato pronto arriva in blocchi di al massimo 10.000 caratteri, ciascuno con un link al successivo:

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

• I segnaposto sono uguali in tutti i blocchi: [PERSON_1] indica sempre lo stesso termine. Ogni blocco elenca le sostituzioni che contiene.
• infos, usage e meta si trovano nel primo blocco.
• Ritirare il blocco N+1 conferma che il blocco N è arrivato; viene quindi rilasciato (410 block_released se lo richiedi di nuovo). Se una connessione cade, richiedi semplicemente di nuovo lo stesso blocco.
• Il next_url dell’ultimo blocco (next_is_confirmation: true) conferma la ricezione ed elimina la richiesta. Senza conferma il risultato viene eliminato 60 minuti dopo il ritiro dell’ultimo blocco, al più tardi dopo 24 ore. DELETE /v1/requests/{id} elimina subito.
• "async": true elabora in background anche i testi brevi (stesso prezzo). "async": false richiede una risposta immediata; un testo troppo lungo viene rifiutato con 413 too_large_for_immediate.

Un esempio completo 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 set

In Setup → Rule sets raccogli i tuoi termini: parole che vengono sempre sostituite (nomi di progetti, numeri cliente) e parole che non vengono mai sostituite (la tua azienda, i prodotti). Assegna un rule set a una chiave come predefinito oppure indicalo per richiesta con ruleset.

Oltre ai termini, un rule set può contenere campi: valori con una forma fissa, ad esempio un numero d’ordine. Crei un campo in Setup → Rule sets incollando un testo di esempio e facendo clic sul valore; costruiamo noi il modello e tu gli dai un nome tecnico come Ordernumber. Ogni corrispondenza viene restituita in infos.Ordernumber e, se vuoi, sostituita nel testo. I campi del rule set e le rules della richiesta funzionano insieme.

Token, limiti e fatturazione

• Si fatturano solo i token. Un token è un piccolo frammento di parola, di circa 3-4 caratteri. Ogni risposta mostra la dimensione in usage.
• POST /v1/tokens con {"text": "…"} restituisce il numero di token e se il testo riceverebbe una risposta immediata. Il testo non viene elaborato e non costa nulla.
• Il limite mensile di token appartiene all’account e vale per tutte le chiavi insieme; creare altre chiavi non lo aumenta.
• Per impostazione predefinita l’API si ferma al limite e risponde 429 quota_exceeded fino al mese successivo o fino all’ampliamento del piano. Continuare e fatturare dopo i token aggiuntivi sarà disponibile con i piani a pagamento; lo configuriamo noi per te.
• I proprietari ricevono un’e-mail quando la previsione del mese passa a giallo o rosso, se l’hanno attivato nel profilo.

Errori

Trattamento dei dati

• I testi vengono elaborati sui nostri server in Europa, con modelli che girano in locale. Non interviene alcun servizio di IA esterno e nulla viene usato per l’addestramento.
• Le richieste immediate sono elaborate in memoria. Conserviamo solo contatori (richieste, token), mai il testo.
• Le richieste in background sono l’unica eccezione: il testo è conservato cifrato finché non è elaborato e poi eliminato; il risultato resta cifrato finché non lo ritiri (rilasciato blocco per blocco), al massimo 24 ore.