Перейти до основного вмісту
PPDF123

PDF123 для розробників: REST API, SDK, командний рядок і MCP

Платформа PDF123 для розробників відкриває ті самі 97 інструментів PDF через чотири інтерфейси: REST API з описом OpenAPI, TypeScript SDK, командний рядок pdfx і MCP-сервери для ШІ-агентів. Для анонімних викликів не потрібні ні обліковий запис, ні ключ API.

На цій сторінці

Як підключити PDF123 зі свого коду?

Усі чотири інтерфейси викликають однакові операції, тож об’єднання дає однаковий результат у кожному з них. Обирайте залежно від того, де працює ваш код.

ІнтерфейсДля чого найкращеВстановлення або адресаПосібник
REST APIБудь-яка мова, сервери, shell-скриптиhttps://pdf123.xyz/api/v1Довідник API
TypeScript SDKКод на Node, Bun і в браузері, якому потрібні типиnpm install @pdf123/sdkПосібник з SDK
Командний рядокТермінали, завдання CI, пакети локальних файлівnpm install -g @pdf123/cliПосібник з CLI
MCPШІ-агенти, як-от Claude Code, Claude Desktop і Cursornpx -y @pdf123/mcp або https://pdf123.xyz/mcpПосібник з MCP

Якщо ваш код написано не на TypeScript, користуйтеся REST API. Якщо на TypeScript, користуйтеся SDK: параметри інструментів типізовані й перевіряються до завантаження. Для разових завдань і shell-скриптів підійде командний рядок. MCP потрібен, коли ШІ-агент сам вирішує, який інструмент запустити.

У каталозі 97 інструментів. 58 із них мають сторінку на цьому сайті, наприклад Об’єднати PDF, Розрізати PDF і Стиснути PDF. Решта — це операції бекенду без вебсторінки, і всі вони доступні в SDK, командному рядку та MCP.

Як виконати перший запит?

Об’єднайте два файли через curl. Запит — це форма multipart з однією частиною fileInput на кожен файл.

REST: об’єднати два PDFbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Те саме об’єднання через TypeScript SDK:

SDK: об’єднати два PDFts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

Те саме об’єднання через командний рядок:

CLI: об’єднати два PDFbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Як працює автентифікація?

Анонімні виклики публічного API не потребують ні облікового запису, ні ключа. Надсилайте ключ API в заголовку X-API-KEY, якщо хочете ідентифікувати свій трафік або звертаєтеся до хостингової кінцевої точки MCP, якій ключ потрібен завжди.

Увійдіть, щоб створити ключ на панелі нижче, і збережіть його в надійному місці.

Перевіряємо сеанс…

Виклик API з ключемbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

SDK приймає ключ як apiKey. Командний рядок і локальний MCP-сервер читають його зі змінної середовища PDFX_API_KEY.

Примітка

На власному сервері задайте змінну середовища SECURITY_CUSTOMGLOBALAPIKEY, щоб визначити один ключ, який приймає сервер. Див. Self-host.

Де довідник API?

REST API задокументовано у двох формах. У Swagger UI кожну кінцеву точку можна випробувати просто в браузері. Документ OpenAPI — машинночитне джерело для генераторів клієнтів.

Кожна операція — це запит POST за базовою адресою https://pdf123.xyz/api/v1, згрупований за категорією. Наприклад, об’єднання — це /general/merge-pdfs, а стиснення — /misc/compress-pdf.

Як поєднати кілька інструментів в одному запиті?

POST /api/v1/pipeline приймає частини fileInput і поле steps. Це поле — масив JSON з об’єктів, у кожного є op і необов’язкові params. Кожен крок отримує результат попереднього.

Об’єднати, потім стиснути — одним запитомbash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

Як безпечно повторити запит?

Надішліть заголовок Idempotency-Key до будь-якої операції. Повторний такий самий запит протягом 24 годин повертає перший результат із заголовком Idempotency-Replayed: true замість того, щоб виконуватися знову. Той самий ключ для іншого запиту відхиляється. Результати понад 32 MiB не зберігаються, тож повтор такого запиту відповідає 409 і потребує нового ключа.

Які є обмеження розміру й частоти?

ОбмеженняЗначення
Розмір файлу на сайті500 MB на файл
Тіло одного прямого запиту до API100 MiB разом зі службовою розміткою multipart
Завантаження частинамиSDK автоматично переходить на API завантаження, коли загальний розмір перевищує 95 MB

У відповідях є заголовки X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset. Відповідь зі статусом 429 додає Retry-After. Читайте заголовки, а не покладайтеся на фіксовану квоту: власний сервер задає свої ліміти. Помилку для завеликого тіла запиту пояснює допис у блозі про обмеження розміру запиту.

Як виглядає помилка?

Збої повертають application/problem+json з полями type, title, status, detail, code, reason і hint. Розгалужуйте логіку за reason, а якщо його немає, за code. Текст detail написано для людей, і в ньому ніколи немає сирого виводу інструмента. Усі коди перелічено на сторінці Коди помилок.

Код або причинаСтатус HTTPЗначення
bad_request400Недійсні параметри або тіло multipart
password_required400PDF зашифровано, а пароль не надіслано
invalid_pdf400Файл не є PDF або пошкоджений; спробуйте Полагодити PDF
page_out_of_range400Запитаної сторінки не існує
not_found404Невідомий шлях операції
rate_limited429Квоту вичерпано; зачекайте на Retry-After

Які інструменти викликати передусім?

Ці дванадцять інструментів покривають більшість запитів. Скористайтеся сторінкою інструмента, щоб спробувати його в браузері.

Сторінка інструментаКінцева точка APIКоманда CLIЩо робить
Об’єднати/general/merge-pdfspdfx mergeПоєднує кілька PDF в один
Розрізати/general/split-pagespdfx splitДілить PDF на окремі файли
Стиснути/misc/compress-pdfpdfx compressПовторно стискає потоки PDF, щоб зменшити розмір
Повернути/general/rotate-pdfpdfx rotateЗмінює орієнтацію сторінок
Поставити пароль/security/add-passwordpdfx protectШифрує PDF паролем
Зняти пароль/security/remove-passwordpdfx unlockЗнімає захист паролем
Водяний знак/security/add-watermarkpdfx watermarkДодає текстовий або графічний водяний знак
OCR/misc/ocr-pdfpdfx ocrРозпізнає відсканований PDF і повертає Markdown
PDF у Markdown/convert/pdf/markdownpdfx pdf-to-markdownПеретворює PDF на Markdown
PDF у Word/convert/pdf/wordpdfx convert-to-wordПеретворює PDF на файл Word, який можна редагувати
Відомості про документ/security/get-info-on-pdfpdfx get-infoПоказує метадані, дозволи, шрифти й структуру
Полагодити/misc/repairpdfx repairВідновлює структуру пошкодженого PDF

Кінцеві точки вказано відносно https://pdf123.xyz/api/v1. Виконайте pdfx list або відкрийте документ OpenAPI, щоб побачити всі 97 інструментів.

Як використати PDF123 у ШІ-агенті?

Агент може працювати з інструментами трьома способами:

  • Підключити MCP-сервер. Посібник з MCP розповідає про локальний сервер @pdf123/mcp для файлів на вашому комп’ютері та про хостингову кінцеву точку https://pdf123.xyz/mcp.
  • Завантажити скіл для агента. Скіли для агентів — це файли SKILL.md для Claude Code, Codex, Cursor та схожих засобів: один на весь каталог і по одному на кожен інструмент.
  • Прочитати індекс сайту. /llms.txt простим текстом перелічує інструменти, API та кінцеву точку MCP, а /site.jsonld описує сайт у вигляді структурованих даних.

Допис «Built for AI Agents, Not Just Browsers» у блозі PDF123 пояснює, як REST API і MCP доповнюють один одного.

Чи можна запустити PDF123 на власному сервері?

Так. Бекенд — це програма pdfx-server, яка працює в Docker. Спрямуйте на неї SDK, командний рядок або MCP-сервер через PDFX_API_BASE, і ваші файли залишаться у вашій мережі. Налаштування описано в Self-host, варіанти підтримки — на сторінці Для підприємств.

FAQ

Чи безкоштовний API PDF123?

Так, для анонімного використання. Виклики публічного API не потребують ні облікового запису, ні ключа. Хостингові відповіді містять заголовки з лімітами частоти, тож клієнт може сповільнитися до того, як отримає відповідь 429.

Чи потрібен мені ключ API?

Для REST API, SDK і командного рядка при роботі з публічним сайтом — ні. Для хостингової кінцевої точки MCP за адресою /mcp — так: без заголовка X-API-KEY вона відповідає 401. Ключ можна створити на цій сторінці після входу.

Яке обмеження розміру файлу?

Сайт приймає файли до 500 MB кожен. Тіло одного прямого запиту до API може сягати 100 MiB разом зі службовою розміткою multipart. Коли загальний розмір перевищує 95 MB, SDK автоматично завантажує більші вхідні дані частинами.

Чи можна розгорнути API у себе?

Так. Запустіть сервер самостійно й вкажіть його адресу як базову для API. SDK, командний рядок і локальний MCP-сервер приймають власну базову URL-адресу.

Як повідомити про помилку?

Скопіюйте поля code, reason і detail із відповіді-проблеми та час запиту й надішліть їх через сторінку контактів. Сам PDF не надсилайте, якщо цього не попросить підтримка.

Що обрати: SDK, командний рядок чи MCP?

SDK — усередині коду на TypeScript, командний рядок — для скриптів і пакетів локальних файлів, MCP — коли інструмент обирає ШІ-агент. Усі три використовують той самий каталог і той самий сервер, тож їх можна поєднувати.