Як підключити 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 і Cursor | npx -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 на кожен файл.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfТе саме об’єднання через TypeScript SDK:
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" });Те саме об’єднання через командний рядок:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfЯк працює автентифікація?
Анонімні виклики публічного API не потребують ні облікового запису, ні ключа. Надсилайте ключ API в заголовку X-API-KEY, якщо хочете ідентифікувати свій трафік або звертаєтеся до хостингової кінцевої точки MCP, якій ключ потрібен завжди.
Увійдіть, щоб створити ключ на панелі нижче, і збережіть його в надійному місці.
Перевіряємо сеанс…
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.pdfSDK приймає ключ як 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. Кожен крок отримує результат попереднього.
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 на файл |
| Тіло одного прямого запиту до API | 100 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_request | 400 | Недійсні параметри або тіло multipart |
password_required | 400 | PDF зашифровано, а пароль не надіслано |
invalid_pdf | 400 | Файл не є PDF або пошкоджений; спробуйте Полагодити PDF |
page_out_of_range | 400 | Запитаної сторінки не існує |
not_found | 404 | Невідомий шлях операції |
rate_limited | 429 | Квоту вичерпано; зачекайте на Retry-After |
Які інструменти викликати передусім?
Ці дванадцять інструментів покривають більшість запитів. Скористайтеся сторінкою інструмента, щоб спробувати його в браузері.
| Сторінка інструмента | Кінцева точка API | Команда CLI | Що робить |
|---|---|---|---|
| Об’єднати | /general/merge-pdfs | pdfx merge | Поєднує кілька PDF в один |
| Розрізати | /general/split-pages | pdfx split | Ділить PDF на окремі файли |
| Стиснути | /misc/compress-pdf | pdfx compress | Повторно стискає потоки PDF, щоб зменшити розмір |
| Повернути | /general/rotate-pdf | pdfx rotate | Змінює орієнтацію сторінок |
| Поставити пароль | /security/add-password | pdfx protect | Шифрує PDF паролем |
| Зняти пароль | /security/remove-password | pdfx unlock | Знімає захист паролем |
| Водяний знак | /security/add-watermark | pdfx watermark | Додає текстовий або графічний водяний знак |
| OCR | /misc/ocr-pdf | pdfx ocr | Розпізнає відсканований PDF і повертає Markdown |
| PDF у Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Перетворює PDF на Markdown |
| PDF у Word | /convert/pdf/word | pdfx convert-to-word | Перетворює PDF на файл Word, який можна редагувати |
| Відомості про документ | /security/get-info-on-pdf | pdfx get-info | Показує метадані, дозволи, шрифти й структуру |
| Полагодити | /misc/repair | pdfx 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 — коли інструмент обирає ШІ-агент. Усі три використовують той самий каталог і той самий сервер, тож їх можна поєднувати.