Fet per a agents d'IA, no només per a navegadors: com funciona l'API
Cada eina del catàleg és un punt de destinació REST sota /api/v1/ i també un servidor MCP a /mcp. Les crides anònimes no demanen compte ni clau d'API.
Una pestanya del navegador continua sent útil: trieu una eina, carregueu un fitxer i baixeu el resultat. Els agents i els scripts criden les mateixes operacions sense obrir cap interfície. Tots dos camins arriben al mateix catàleg.
Cada pàgina d'eina és també un punt de destinació
Uneix PDF, partir, comprimir, fer OCR i convertir: cada eina del catàleg es correspon amb un punt de destinació sota /api/v1/…. Obriu una pàgina d'eina i desplaceu-vos fins a Crida-ho des del codi per veure un exemple de curl construït amb els paràmetres reals d'aquella eina, no amb una plantilla genèrica. Al lloc públic les crides anònimes no demanen compte ni clau d'API; els prefixos anònims són /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ i /api/v1/filter/.
L'exemple d'unió és concret:
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
L'OpenAPI és a /v1/openapi.json. La feina de diversos passos fa servir POST /api/v1/pipeline amb una llista ordenada de steps. Envieu Idempotency-Key quan un reintent no hagi de tornar a executar una tasca que muta l'estat. Les respostes allotjades anuncien X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset; en un HTTP 429, llegiu Retry-After (limitació de taxa anònima).
L'OCR a través del mateix catàleg retorna Markdown (text/markdown) des de /api/v1/misc/ocr-pdf, no un PDF amb una capa de text oculta. Els agents que esperen un PDF cercable d'aquí gestionaran malament la descàrrega; el contracte és l'extracció de text per a pipelines, no una reescriptura a l'estil d'OCRmyPDF.
MCP per als clients que el parlen
MCP (Model Context Protocol) permet que els clients d'agent descobreixin i invoquin eines com a funcions en lloc d'haver d'extreure la informació de la documentació. Aquest lloc exposa un servidor MCP a /mcp al costat de l'API REST, de manera que un client compatible es connecta una sola vegada i obté el catàleg complet.
MCP i REST comparteixen les expectatives d'autenticació: anònima allà on els prefixos de les eines ho permeten, i claus d'API per a l'automatització estable i per als servidors autoallotjats restringits. Apuntar un agent a /mcp no és un producte diferent d'apuntar-hi curl via /api/v1/…. Documentació: MCP per a desenvolupadors.
Els errors són estructurats, no prosa
Els errors tornen application/problem+json (estil RFC 7807), no un 500 pelat ni un «alguna cosa ha fallat». Cada cos de resposta porta un codi estable (rate_limited, bad_request, invalid_document, missing_dependency i similars), una indicació llegible i sovint un pas següent. Les persones el poden llegir per sobre; els agents poden decidir si reintentar, canviar el fitxer o aturar-se sense interpretar cap traça de pila.
Aquesta estructura importa més que una pàgina HTML d'error amigable quan qui fa la crida és un script. Referència: Errors per a desenvolupadors.
llms.txt és per a les eines, no per al posicionament
/llms.txt és un índex en text pla de cada eina (nom, descripció breu i URL), generat a partir del mateix catàleg que alimenta el lloc. Els agents de programació i les eines de documentació el poden llegir com un README. No és una palanca per posicionar-se a Google: el cercador ignora /llms.txt (fonts: guia de Google per a l'optimització amb IA). Com que es genera automàticament, no pot quedar desactualitzat en silenci com un fitxer editat a mà.
La CLI i l'habilitat comparteixen les mateixes formes
pdfx pot executar el pdf-core local o --cloud contra una URL base. L'habilitat per a agents de programació que hi ha a dist/skills/pdf-toolbox/SKILL.md documenta les formes de curl per a la unió i el pipeline, perquè els agents no s'inventin un segon contracte. Quatre clients, un catàleg: La mateixa operació, quatre clients.
El camí del navegador no canvia
Deixar un fitxer en una pestanya continua funcionant igual. La superfície addicional són els mateixos punts de destinació per a un agent, un script o un CI: el mateix processament, sense cap persona pel mig. L'autoallotjament manté aquesta superfície a la vostra xarxa (Autoallotjament); l'allotjament continua sent el camí de prova anònim.
Referència de l'API: Swagger. Per començar: Ajuda i Desenvolupadors.