¿Cuándo es válido un archivo?

Cuando el informe no tiene ningún mensaje FATAL ni ERROR. Los avisos por sí solos no invalidan un archivo. El summary de cada respuesta lo indica en valid, junto al número de mensajes fatal, error y warning.

¿Necesito una clave de API?

No. Sin clave, una validación gasta la cuota diaria gratuita de tu dirección IP. Una cuenta gratuita con clave recibe una cuota diaria y créditos mensuales propios; los planes están en la página de precios.

EPUBCheck como API

Valida archivos EPUB con EPUBCheck por HTTPS: una llamada devuelve el informe JSON completo de EPUBCheck y un resumen, por 2 créditos. Sin Java que instalar.

Última actualización 22 oct 2026

Endpoint	POST /v1/epubcheck/check con el EPUB como campo multipart file
Precio	2 créditos por validación, sea cual sea el resultado. Una llamada rechazada o fallida no cuesta nada.
Límites	25 MB por archivo y 45 segundos por validación, un archivo por llamada
Respuesta	El informe JSON de EPUBCheck (checker, publication, items, messages) más summary

EPUBCheck es el validador de conformidad del W3C para publicaciones EPUB. Valida el contenedor ZIP, el documento de paquete, la navegación y cada documento de contenido de un archivo EPUB 2 o EPUB 3 contra las especificaciones EPUB. Muchas tiendas de libros electrónicos y distribuidores exigen que un archivo la pase antes de aceptarlo.

Aquí funciona tras un endpoint HTTPS: envía el archivo y recibe el informe JSON de EPUBCheck tal cual, más un summary con el resultado.

Precio y límites

Una validación cuesta 2 créditos, sea cual sea el resultado: un archivo con errores es una respuesta normal (200), con los errores en messages. Una llamada rechazada o fallida (cualquier estado desde 400) no cuesta nada. Sin clave de API, una validación gasta la cuota diaria gratuita de tu dirección IP; la cuota gratuita y los planes están en la página de precios.

25 MB por archivo, un archivo por llamada.
45 segundos por validación. Una validación más larga se detiene y responde 504 engine_timeout.
EPUBCheck ejecuta una validación a la vez. Mientras está ocupado, una llamada responde 429 engine_busy con una cabecera Retry-After: espera esos segundos y vuelve a enviarla.

Alojarlo tú o usarlo alojado

EPUBCheck se distribuye como herramienta de línea de comandos en Java. Ejecutarlo tú significa un entorno de Java en cada máquina que valide archivos, la versión de EPUBCheck y sus actualizaciones, y una JVM nueva para cada validación: unos 512 MB de memoria y uno o dos segundos de arranque por archivo. Para llamarlo desde otro servicio, además escribes y mantienes un pequeño envoltorio HTTP a su alrededor.

Alojado, es una clave de API y una llamada HTTPS, desde cualquier lenguaje, sin nada que instalar ni actualizar.

Inicio rápido: curl

curl -sS -X POST https://api.pagespool.com/v1/epubcheck/check \
  -H "X-API-Key: $PAGESPOOL_KEY" \
  -F file=@book.epub | jq .summary

summary es el resultado de un vistazo:

{"valid": false, "fatal": 0, "error": 2, "warning": 1}

El resto de la respuesta es el informe de EPUBCheck tal como lo escribe EPUBCheck.

Inicio rápido: Python

import httpx

with open("book.epub", "rb") as f:
    resp = httpx.post(
        "https://api.pagespool.com/v1/epubcheck/check",
        headers={"X-API-Key": KEY},
        files={"file": ("book.epub", f, "application/epub+zip")},
        timeout=60,
    )
resp.raise_for_status()
report = resp.json()
print(report["summary"])
for message in report["messages"]:
    print(message["severity"], message["ID"], message["message"])

La respuesta

Una respuesta 200 es el informe JSON de EPUBCheck, sin cambios, con una clave añadida:

checker: la versión de EPUBCheck (checkerVersion) y sus propios recuentos.
publication: los metadatos que leyó EPUBCheck, como title, language y ePubVersion.
items: cada archivo del EPUB, con su tipo de medio.
messages: una entrada por problema, con ID (por ejemplo RSC-005), severity, message, locations (path, line, column; -1 si se desconoce) y suggestion. EPUBCheck agrupa todos los lugares de un problema en un mensaje.
summary: valid (ningún mensaje FATAL ni ERROR) y el número de mensajes fatal, error y warning.

Los errores son problemas RFC 9457 (application/problem+json) con un code estable: payload_too_large (413), engine_busy (429), engine_failed (502), engine_unavailable (503, con Retry-After) y engine_timeout (504).

Claves de API

Una clave va en uno de tres sitios:

la cabecera X-API-Key: -H "X-API-Key: $PAGESPOOL_KEY";
un token Bearer: -H "Authorization: Bearer $PAGESPOOL_KEY";
autenticación HTTP Basic con la clave como contraseña y cualquier nombre de usuario: curl -u "x:$PAGESPOOL_KEY" …, o una URL como https://x:<key>@… para un cliente que solo acepta una URL.

No pongas nunca la clave en la ruta ni en la query string: ambas acaban en los registros.

Herramienta gratuita y MCP

Para probar un archivo sin escribir código, usa el validador EPUB gratuito (archivos de hasta 4 MB).

Los agentes de IA obtienen la misma validación del servidor MCP en https://api.pagespool.com/mcp/epubcheck/. Su herramienta check_epub acepta el EPUB en base64 (hasta 4 MB) o como enlace https, y devuelve el resumen y los 20 mensajes más graves. Cuesta 2 créditos por llamada, como la API.

Marcas

EPUBCheck es un proyecto del W3C; pagespool no está afiliado al W3C.

Preguntas frecuentes

¿Qué valida EPUBCheck?: EPUBCheck valida un archivo EPUB 2 o EPUB 3 contra las especificaciones EPUB: el contenedor ZIP, el documento de paquete, la navegación y cada documento de contenido. Cada problema que encuentra es un mensaje con una gravedad: FATAL, ERROR, WARNING, USAGE o INFO.
¿Cuándo es válido un archivo?: Cuando el informe no tiene ningún mensaje FATAL ni ERROR. Los avisos por sí solos no invalidan un archivo. El summary de cada respuesta lo indica en valid, junto al número de mensajes fatal, error y warning.
¿Necesito una clave de API?: No. Sin clave, una validación gasta la cuota diaria gratuita de tu dirección IP. Una cuenta gratuita con clave recibe una cuota diaria y créditos mensuales propios; los planes están en la página de precios.