Product3 min czytania

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

Każde narzędzie z katalogu to punkt końcowy REST pod /api/v1/, a obok działa MCP pod /mcp. Anonimowe wywołania nie wymagają konta ani klucza API.

By the PDF123 team · Updated 2026-10-09
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.

Schemat: klik w przeglądarce oraz wywołanie agenta lub skryptu trafiają do tych samych punktów końcowych API i zwracają ten sam wynik

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 domyślnie Markdown (text/markdown) ze ścieżki /api/v1/misc/ocr-pdf. Po wysłaniu outputFormat=pdf ten sam punkt końcowy zwraca zamiast tego przeszukiwalny PDF (application/pdf, do 50 stron, rozpoznany przez Tesseract). Agent powinien odczytać nagłówek Content-Type odpowiedzi, a nie zakładać pobrania tekstu, bo oba wyniki pochodzą z różnych silników i mają różne limity.

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 jest klientem tego samego interfejsu REST, skierowanym na adres bazowy z opcjonalnym kluczem API, więc wysyła żądanie multipart, które wysłałby curl, zamiast wystawiać drugi katalog. Opublikowany skill pod /skills/pdf123.md opisuje kształty 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.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool