API

Inicio rápido

1. Inicia sesión (Login / Registro) y crea una clave de API en Setup → API keys. 2. Envía un texto:

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 respuesta contiene el texto velado y la lista de lo que se sustituyó:

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

Autenticación

Dirección base: https://api.aidataveil.eu. Envía tu clave en la cabecera Authorization: Bearer veil_…. Mantén las claves en secreto. Una cuenta puede tener hasta 5 claves y puedes eliminar una clave en cualquier momento.

Solicitud: POST /v1/anonymize

Respuesta

Textos cortos y largos

Los textos de hasta 1.000 tokens (unos 3.500 caracteres, un correo largo) se responden al instante. Los textos más largos se aceptan y se procesan en segundo plano; el resultado se recoge después. Las solicitudes cortas no se retrasan por ello: siempre van primero.

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

Recoge el resultado con GET result_url. El estado es queued, processing, done o failed. Un resultado terminado llega en bloques de hasta 10.000 caracteres, cada uno con un enlace al siguiente:

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

• Los marcadores son iguales en todos los bloques: [PERSON_1] siempre significa el mismo término. Cada bloque lista las sustituciones que contiene.
• infos, usage y meta están en el primer bloque.
• Recoger el bloque N+1 confirma que el bloque N ha llegado; entonces se libera (410 block_released si lo pides otra vez). Si se corta una conexión, pide simplemente el mismo bloque de nuevo.
• El next_url del último bloque (next_is_confirmation: true) confirma la recepción y elimina la solicitud. Sin confirmación, el resultado se elimina 60 minutos después de recoger el último bloque, como máximo a las 24 horas. DELETE /v1/requests/{id} elimina al instante.
• "async": true procesa también los textos cortos en segundo plano (mismo precio). "async": false exige una respuesta inmediata; un texto demasiado largo se rechaza con 413 too_large_for_immediate.

Un ejemplo completo 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

En Setup → Rule sets reúnes tus propios términos: palabras que siempre se sustituyen (nombres de proyectos, números de cliente) y palabras que nunca se sustituyen (tu empresa, productos). Asigna un rule set a una clave como predeterminado o indícalo por solicitud con ruleset.

Además de términos, un rule set puede contener campos: valores con una forma fija, por ejemplo un número de pedido. Creas un campo en Setup → Rule sets pegando un texto de ejemplo y haciendo clic en el valor; nosotros formamos el patrón y tú le das un nombre técnico como Ordernumber. Cada coincidencia se devuelve en infos.Ordernumber y, si quieres, se sustituye en el texto. Los campos del rule set y las rules de la solicitud funcionan juntos.

Tokens, límites y facturación

• Solo se facturan tokens. Un token es un pequeño fragmento de palabra, de unos 3 a 4 caracteres. Cada respuesta muestra el tamaño en usage.
• POST /v1/tokens con {"text": "…"} devuelve el número de tokens y si el texto se respondería al instante. No procesa el texto y no cuesta nada.
• El límite mensual de tokens pertenece a la cuenta y cuenta para todas las claves juntas; crear más claves no lo aumenta.
• Por defecto, la API se detiene en el límite y responde 429 quota_exceeded hasta el mes siguiente o hasta ampliar el plan. Seguir funcionando y facturar después los tokens adicionales llegará con los planes de pago; lo configuramos por ti.
• Los propietarios reciben un correo cuando la previsión del mes pasa a amarillo o rojo, si lo han activado en su perfil.

Errores

Tratamiento de los datos

• Los textos se procesan en nuestros propios servidores en Europa, con modelos que se ejecutan localmente. No interviene ningún servicio de IA externo y nada se usa para entrenar.
• Las solicitudes inmediatas se procesan en memoria. Solo guardamos contadores (solicitudes, tokens), nunca el texto.
• Las solicitudes en segundo plano son la única excepción: el texto se guarda cifrado hasta que se procesa y luego se elimina; el resultado permanece cifrado hasta que lo recoges (liberado bloque a bloque), como máximo 24 horas.