API de análisis con IA
Envía un PDF —de cualquier tamaño, leído entero— y recibe un informe técnico con puntuación, recomendación y deficiencias, evaluado con la normativa de tu colegio. Con opción de IA europea (procesada en la UE). La IA asiste; decide el técnico.
Cómo funciona, de un vistazo
La regla de oro
La API key es un secreto de servidor. Nunca la uses desde el navegador: si la pones en el JavaScript de tu web queda expuesta y con ella se puede consumir tu cuota. La key va solo en tu servidor.
En cinco minutos
Consigue la URL base y la key
El administrador de tu colegio las obtiene en su panel (Administración → API): genera la key —se muestra una sola vez— y ve la URL base de vuestra instancia. La key tiene el aspecto avk_live_XXXX…
Guárdala como secreto
En tu servidor, como variable de entorno, p. ej. AIVISADO_API_KEY. Nunca en el código del navegador.
Comprueba la conexión
Con el endpoint de salud (no gasta análisis). Debe responder ok: true.
curl https://TU-BASE/api/v1/health \
-H "Authorization: Bearer $AIVISADO_API_KEY"Analizar un documento
https://TU-BASE/api/v1/analisisAutenticación por cabecera Authorization: Bearer avk_live_… (o x-api-key). Cuerpo multipart/form-data, un PDF por petición.
archivorequeridofichero (PDF)El PDF a analizar. Máx. 200 MB, de cualquier extensión (se lee entero). Debe tener texto (los escaneos sin OCR se rechazan con 422).
tipoopcionaltextoTipo de documento, p. ej. «Proyecto de ejecución». Afina el análisis.
tituloopcionaltextoTítulo del proyecto o expediente.
descripcionopcionaltextoContexto breve del proyecto.
tipo_trabajoopcionaltextoTipo de trabajo declarado (obra nueva, reforma, legalización…). Orienta el análisis.
uso_caracteristicoopcionaltextoUso característico del edificio (residencial, comercial…).
usos_subsidiariosopcionaltexto / listaUsos secundarios del edificio. Acepta un texto o una lista.
El informe
{
"contrato_version": 1,
"analisis_id": "an_9f3k2a8b1c4d5e6f",
"estado": "completado",
"modelo": "claude-haiku-4-5-20251001",
"informe": {
"puntuacion": 68,
"recomendacion": "CORRECCION",
"resumen": "Memoria coherente; faltan dos justificaciones…",
"deficiencias": [
{ "deficiencia": "Falta el certificado energético del edificio terminado",
"solucion": "1) Adjuntar el CEE… 2) …",
"norma": "CTE DB-HE", "gravedad": "moderada" }
],
"criterios_evaluados": [ /* … */ ],
"aspectos_conformes": [ /* … */ ],
"justificacion": "…"
}
}puntuaciongarantizadoEntero 0–100.
recomendaciongarantizadoAPROBAR · CORRECCION · RECHAZAR. Se re-deriva con reglas deterministas: la IA no decide.
resumenResumen en lenguaje natural del dictamen.
criterios_evaluados[]Cada criterio con su norma, estado (cumple/no_cumple/no_consta/no_aplica), cita textual y comentario.
aspectos_conformes[]Aspectos correctos, con su norma y cita.
deficiencias[]Cada deficiencia con solucion (pasos), norma, gravedad (leve/moderada/grave) y cita.
justificacionJustificación global de la recomendación.
analisis_paso_a_paso). Solo puntuacion y recomendacion tienen garantía de tipo cerrada. El campo modelo indica el modelo de IA que ejecutó el análisis —según la configuración de tu colegio, puede ser un modelo europeo (ver IA europea)—. El contrato formal es el OpenAPI v1 del servicio.Cierre por fase
https://TU-BASE/api/v1/faseVarios PDFs de una misma fase → un único informe consolidado. Campo documentos (de 1 a 20 PDFs) y fase obligatorio; admite además tipologia, titulo, descripcion y los mismos campos de contexto que /analisis. La respuesta añade fase y documentos_analizados[] (con el nº de páginas de cada uno).
/analisis, admite ?modo=async.Documentos de cualquier tamaño
El análisis lee el documento entero, no solo el principio. Un proyecto de cientos o miles de páginas se procesa por partes y se consolida en un único informe, sin que tengas que dividirlo tú. Para documentos muy grandes, el análisis puede tardar algunos minutos: usa el modo asíncrono.
texto_truncado: true. Nunca se afirma una cobertura que no se hizo.Consola de análisis
Una demostración —sin backend real— de cómo se ve una petición y su informe. Lanza el análisis de una memoria de ejemplo y observa el resultado.
Memoria coherente y bien estructurada; faltan dos justificaciones normativas antes de poder aprobar el visado.
El dictamen es asesor y no sustituye la revisión del técnico. Datos de ejemplo con fines ilustrativos.
Modo asíncrono
Si tu cliente no puede esperar ~30 s con la conexión abierta, añade ?modo=async: la API responde al instante con un identificador y recoges el resultado después (se conserva 48 horas).
# 1) Lanzas el análisis y te devuelve un identificador al instante
POST https://TU-BASE/api/v1/analisis?modo=async
→ 202 { "analisis_id": "an_…", "estado": "analizando" } (+ cabecera Location)
# 2) Consultas el resultado (se conserva 48 h)
GET https://TU-BASE/api/v1/analisis/an_…
→ "analizando" (sigue en curso; respeta Retry-After ~15 s)
→ "completado" (el mismo envoltorio con el informe)
→ "error" (con code/error; si es "interrumpido", reenvía la petición)Copia y pega
curl -X POST https://TU-BASE/api/v1/analisis \
-H "Authorization: Bearer $AIVISADO_API_KEY" \
-F "archivo=@memoria.pdf" \
-F "tipo=Proyecto de ejecución" \
--max-time 180// En TU backend (nunca en el navegador): recibe el PDF del navegador y lo reenvía.
app.post("/analizar", subida.single("pdf"), async (req, res) => {
const fd = new FormData();
fd.append("archivo", new Blob([req.file.buffer], { type: "application/pdf" }), "memoria.pdf");
fd.append("tipo", "Proyecto de ejecución");
const r = await fetch("https://TU-BASE/api/v1/analisis", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.AIVISADO_API_KEY}` },
body: fd,
signal: AbortSignal.timeout(180000), // >= 120 s
});
const data = await r.json();
if (!r.ok) return res.status(r.status).json(data); // 401/413/415/429/503…
res.json(data.informe);
});import os, requests
def analizar(ruta_pdf):
with open(ruta_pdf, "rb") as f:
r = requests.post(
"https://TU-BASE/api/v1/analisis",
headers={"Authorization": f"Bearer {os.environ['AIVISADO_API_KEY']}"},
files={"archivo": ("memoria.pdf", f, "application/pdf")},
data={"tipo": "Proyecto de ejecución"},
timeout=180, # >= 120 s
)
r.raise_for_status()
return r.json()["informe"]Códigos y qué hacer
Devuelven { "error": "…", "code": "…" }; algunos incluyen retriable: true o la cabecera Retry-After. Reintenta solo 429/503/504 (con espera); no reintentes 4xx de petición.
Falta el PDF o está corrupto. Revisa el envío multipart. No reintentar.
Key ausente, inválida, revocada o caducada. Revísala con el colegio. No reintentar.
El módulo API no está activo para tu colegio, o el análisis async no existe / caducó (48 h).
Falta la longitud del cuerpo (solo en cierre por fase). Añade la cabecera Content-Length.
El PDF supera el máximo, o la fase lleva más de 20 documentos. Reduce o divide.
El fichero no es un PDF. Envía un PDF real.
El PDF no tiene texto (escaneo sin OCR). Usa un PDF con capa de texto.
Límite alcanzado. Respeta Retry-After; el de peticiones/hora trae cabeceras RateLimit-*.
Temporal. Reintenta más tarde (retriable: true).
El análisis tardó demasiado. Reintenta la petición.
Uso responsable
- Un PDF por petición. Para varios, una petición por cada uno.
- Límite por hora, cuota diaria y concurrencia por key: espacia o encola en tu lado.
- Presupuesto mensual por colegio: al alcanzarlo, 429 hasta el mes siguiente.
- Guarda la key como secreto; si se filtra, pide al colegio que la revoque y rote.
- Timeout del cliente ≥120 s, o usa el modo asíncrono.
El documento no se almacena
El PDF se procesa en memoria y no se guarda; su texto tampoco. En modo síncrono el informe se devuelve y se descarta; en modo asíncrono se conserva 48 horas para su recogida y se elimina automáticamente. Solo quedan metadatos de uso y coste, sin el contenido del documento.
El dictamen es asesor: no sustituye la revisión del técnico. El análisis usa un proveedor de IA como encargado del tratamiento, declarado en las condiciones que firma el colegio.
Opción de IA europea
El análisis puede ejecutarse con un modelo de IA europeo (Mistral, procesado en la UE), de modo que el contenido del documento no salga de la Unión Europea. Es una opción que se activa para tu colegio al contratar; el modelo que ejecutó cada análisis se indica en el campo modelo de la respuesta. El proveedor de IA actúa como encargado del tratamiento, recogido en las condiciones que firma el colegio.
Cómo se factura
Se factura por análisis (no por tokens), con la API key de tu colegio. Cada análisis queda medido: el colegio ve su uso y su coste en su propio panel. El precio se ajusta a vuestro volumen.
Pagas por análisis realizado. Para empezar o para volumen bajo, sin cuota fija.
Cuota con análisis incluidos y mejor precio por análisis cuanto mayor es el volumen.
El acceso lo contrata el colegio (IVA aparte). Te preparamos una propuesta con el precio para vuestro volumen.