Stworzone z myślą o agentach AI, nie tylko o przeglądarkach: jak działa API

Karta przeglądarki nadal działa: wybierasz narzędzie, wgrywasz plik, pobierasz wynik. Agenci i skrypty wywołują te same operacje bez otwierania interfejsu. Obie ścieżki prowadzą do tego samego katalogu.

Każda strona narzędzia to także punkt końcowy

Scal PDF, podział, kompresja, OCR, konwersja: każde narzędzie z katalogu odpowiada ścieżce /api/v1/…. Otwórz stronę narzędzia i przewiń do Call this from code, gdzie znajdziesz przykład curl zbudowany z rzeczywistych parametrów tego narzędzia, a nie z ogólnego szablonu. Anonimowe wywołania w publicznym serwisie nie wymagają konta ani klucza API; anonimowe prefiksy to /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ oraz /api/v1/filter/.

Przykład scalania jest konkretny:

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

OpenAPI jest dostępne pod /v1/openapi.json. Praca wieloetapowa korzysta z POST /api/v1/pipeline z uporządkowaną listą steps. Dodaj Idempotency-Key, gdy ponowna próba nie może drugi raz uruchomić zadania zmieniającego dane. Odpowiedzi serwera hostowanego podają X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset; przy HTTP 429 odczytaj Retry-After (anonimowe limity tempa).

OCR przez ten sam katalog zwraca Markdown (text/markdown) ze ścieżki /api/v1/misc/ocr-pdf, a nie PDF z ukrytą warstwą tekstu. Agent, który oczekuje z tego punktu końcowego przeszukiwalnego PDF, obsłuży pobrany plik błędnie; kontrakt to wyciąganie tekstu na potrzeby potoków, a nie przepisywanie pliku w stylu OCRmyPDF.

MCP dla klientów, które go rozumieją

MCP (Model Context Protocol) pozwala klientom agentów odkrywać i wywoływać narzędzia jako funkcje, zamiast wyciągać je z dokumentacji. Ten serwis udostępnia serwer MCP pod /mcp obok REST API, więc zgodny klient łączy się raz i dostaje cały katalog.

MCP i REST mają takie same zasady uwierzytelniania: anonimowo tam, gdzie pozwalają na to prefiksy narzędzi, oraz klucze API do stabilnej automatyzacji i dla zamkniętych serwerów self-hosted. Wskazanie agentowi /mcp to nie inny produkt niż wskazanie curlowi /api/v1/…. Dokumentacja: MCP dla programistów.

Błędy mają strukturę, a nie formę prozy

Niepowodzenia zwracają application/problem+json (styl RFC 7807), a nie gołe 500 albo „coś poszło nie tak”. Każdy ładunek ma stabilny kod (rate_limited, bad_request, invalid_document, missing_dependency i podobne), czytelną wskazówkę, a często także następny krok. Człowiek przejrzy to wzrokiem, natomiast agent może zdecydować o ponownej próbie, wymianie pliku albo zatrzymaniu się, bez czytania stosu wywołań.

Taka struktura liczy się bardziej niż przyjazna strona HTML z błędem, gdy wywołującym jest skrypt. Źródło: Błędy dla programistów.

llms.txt służy narzędziom, nie rankingom

/llms.txt to tekstowy indeks wszystkich narzędzi (nazwa, krótki opis, adres URL), generowany z tego samego katalogu, który napędza serwis. Agenci kodujący i narzędzia dokumentacyjne mogą czytać go jak README. To nie dźwignia pozycji w Google: wyszukiwarka ignoruje /llms.txt (źródła: przewodnik Google po optymalizacji pod AI). Ponieważ plik jest generowany, nie starzeje się po cichu tak jak plik edytowany ręcznie.

CLI i skill dzielą te same kształty

pdfx potrafi uruchomić lokalny pdf-core albo tryb --cloud przeciwko adresowi bazowemu. Skill dla agenta kodującego w dist/skills/pdf-toolbox/SKILL.md opisuje kształty wywołań curl dla scalania i potoku, aby agenci nie wymyślali drugiego kontraktu. Cztery klienty, jeden katalog: Ta sama operacja, cztery klienty.

Ścieżka przeglądarki bez zmian

Upuszczenie pliku w karcie działa tak samo. Do tego dochodzą te same punkty końcowe dla agenta, skryptu czy CI: identyczne przetwarzanie, bez człowieka pośrodku. Self-host zostawia ten kanał w twojej sieci (Self-host), a wersja hostowana pozostaje anonimową ścieżką próbną.

Dokumentacja API: Swagger. Podstawy dla obu ścieżek: Pomoc i Dla programistów.