Създаден за AI агенти, не само за браузъри: как работи API

Един браузърен таб все още върши работа: избирате инструмент, качвате файл, изтегляте резултата. Агентите и скриптовете извикват същите операции, без да отварят интерфейс. И двата пътя стигат до един и същ каталог.

Всяка страница с инструмент е и крайна точка

Merge, split, compress, OCR, convert: всеки инструмент от каталога съответства на /api/v1/…. Отворете страницата на инструмента и превъртете до Call this from code, за да видите пример с curl, изграден от реалните параметри на инструмента, а не общ шаблон. Анонимните заявки на публичния сайт не изискват акаунт и API ключ; анонимните префикси са /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ и /api/v1/filter/.

Примерът за merge е конкретен:

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

OpenAPI е на /v1/openapi.json. Многостъпковата работа използва POST /api/v1/pipeline с подреден списък steps. Подавайте Idempotency-Key, когато повторен опит не бива да изпълни втори път операция с промяна. Отговорите от хостваната услуга обявяват X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset; при HTTP 429 прочетете Retry-After (анонимно ограничаване на честотата).

OCR през същия каталог връща Markdown (text/markdown) от /api/v1/misc/ocr-pdf, а не PDF със скрит текстов слой. Агентите, които очакват PDF с търсене от тази крайна точка, ще обработят изтеглянето погрешно; договорът е извличане на текст за потоци, а не пренаписване в стил OCRmyPDF.

MCP за клиенти, които го разбират

MCP (Model Context Protocol) позволява на клиентите за агенти да откриват и извикват инструменти като функции, вместо да извличат документация. Този сайт предоставя MCP сървър на /mcp до REST API, така че съвместим клиент се свързва веднъж и получава целия каталог.

MCP и REST споделят очакванията за автентикация: анонимно там, където префиксите на инструментите го позволяват; API ключове за стабилна автоматизация и за защитени самостоятелно хоствани сървъри. Насочването на агент към /mcp не е различен продукт от насочването на curl към /api/v1/…. Документация: MCP за разработчици.

Грешките са структурирани, не описателни

Неуспехите връщат application/problem+json (в стил RFC 7807), а не голо 500 или „нещо се обърка“. Всяко тяло има стабилен код (rate_limited, bad_request, invalid_document, missing_dependency и подобни), четим намек и често следваща стъпка. Хората го преглеждат бързо; агентите могат да решат да повторят, да сменят файла или да спрат, без човек да разчита проследяване на стека.

Тази структура е по-важна от приятелска HTML страница за грешка, когато извикващият е скрипт. Справка: Грешки за разработчици.

llms.txt е за инструменти, не за класации

/llms.txt е текстов индекс на всеки инструмент (име, кратко описание, URL), генериран от същия каталог, който захранва сайта. Агентите за програмиране и инструментите за документация могат да го четат като README. Той не е лост за класиране в Google: търсачката пренебрегва /llms.txt (източници: ръководството на Google за оптимизация за AI). Понеже е генериран, той не може тихо да остарее както файл, редактиран на ръка.

CLI и skill споделят едни и същи форми

pdfx може да изпълнява локалния pdf-core или --cloud срещу базов URL. Skill-ът за агент за програмиране в dist/skills/pdf-toolbox/SKILL.md документира формите на curl за merge и pipeline, за да не си измислят агентите втори договор. Четири клиента, един каталог: Една и съща операция, четири клиента.

Пътят през браузъра е непроменен

Пускане на файл в таб работи както преди. Допълнителната повърхност са същите крайни точки за агент, скрипт или CI: същата обработка, без човек по средата. Самостоятелното хостване запазва тази повърхност във вашата мрежа (Self-host); хостваната услуга остава анонимният пробен път.

Справка за API: Swagger. Основи за всеки от двата пътя: Помощ и Разработчици.