Як установити SDK?
Установіть пакет через свій менеджер пакетів. Потрібні Node 20.3 або новіша версія, Bun чи бандлер. Типи TypeScript входять до пакета, а @types/node не потрібен.
npm install @pdf123/sdkbun add @pdf123/sdk і pnpm add @pdf123/sdk працюють так само.
Як об’єднати два PDF?
Створіть клієнт, запустіть інструмент merge для двох файлів і збережіть результат. Без параметрів клієнт анонімно звертається до публічного API.
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")],
});
const path = await saveResult(result, { output: "merged.pdf" });
console.log(path);Результат містить байти в data, contentType, ім’я файлу від сервера в filename та json для інструментів, що повертають звіт. Ту саму операцію на сайті виконує Об’єднати PDF.
Яку точку входу імпортувати?
| Точка входу | Що потрібно | Що надає |
|---|---|---|
@pdf123/sdk | Лише fetch | Pdf123Client, TOOLS, getTool, Pdf123Error і допоміжні функції каталогу |
@pdf123/sdk/node | Node або Bun | readFileInput, fileSource, saveResult, checkOutput і clientFromEnv |
У браузерах і edge-середовищах імпортуйте з кореневої точки входу, а точку node додавайте лише там, де читаєте або записуєте файли.
Які методи є в клієнта?
| Метод | Що робить |
|---|---|
run(tool, { input, params }) | Запускає один інструмент і повертає результат |
runBatch(tool, inputs, options) | Запускає інструмент, що обробляє один файл, для багатьох вхідних файлів і повертає по одному запису на кожен |
pipeline(steps, input, options) | Запускає кілька інструментів в одному запиті |
call(target, files, fields) | Надсилає сирий запит до ідентифікатора інструмента, ідентифікатора операції або шляху /api/... |
upload(file) | Завантажує один файл через API завантаження частинами й повертає його ідентифікатор |
Допоміжні функції каталогу — звичайні функції: TOOLS перелічує всі інструменти, getTool(id) повертає поля, типові значення та допустимі типи файлів одного інструмента, а toolGroup, toolSummary, matchesQuery і suggestTools допомагають будувати вибір інструментів. Командний рядок виводить той самий каталог командами pdfx list і pdfx describe.
Як передати параметри інструменту?
params типізовано для кожного інструмента. Він приймає лише поля цього інструмента, а поля вибору — лише дозволені значення. Числові поля перевіряються за мінімумом і максимумом, а файл — за допустимими типами, ще до будь-якого завантаження. Типові значення, потрібні серверу, підставляються.
const marked = await client.run("watermark", {
input: await readFileInput("a.pdf"),
params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });Порожній рядок означає «не задано», тож діє типове значення. Що робить кожен параметр, див. на сторінці Водяний знак.
Як обробити багато файлів?
runBatch запускає інструмент, що обробляє один файл, як-от Стиснути, Повернути чи Поставити пароль, для кожного вхідного файла з однаковими параметрами. За замовчуванням обробляються по два файли одночасно. Один поганий файл ніколи не зупиняє решту.
import { fileSource, saveResult } from "@pdf123/sdk/node";
const controller = new AbortController();
const entries = await client.runBatch("compress", [fileSource("a.pdf"), fileSource("b.pdf")], {
concurrency: 2,
signal: controller.signal,
onResult: async (entry, index) => {
if (entry.ok) await saveResult(entry.result, { output: "compressed/" });
},
});
console.log(entries.map((entry) => entry.ok));fileSource(path)— це відкладене джерело: файл читається лише тоді, коли його бере воркер, тому багато великих файлів ніколи не лежать у пам’яті разом.onResultотримує кожен результат одразу після завершення. Зберігайте його там: якщо скасувати на файлі 50 зі 100, перші 49 залишаться. ЗretainData: falseповернений масив не зберігає байти.- Будь-який виклик приймає
timeoutMsіsignalдля скасування. idempotencyKeyдля кожного файла перетворюється на<key>:<index>.
Інструменти-фільтри (ідентифікатори, що починаються з filter-) завершуються з matched: false, а не викидають помилку, коли умова не виконується. У пакетній обробці такий файл усе одно вважається ok.
Як поєднати інструменти в одному запиті?
pipeline надсилає список кроків і один чи кілька вхідних файлів. Сервер передає результат кожного кроку наступному.
const piped = await client.pipeline(
[{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
[await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
await saveResult(piped, { output: "out.pdf" });Конвеєри приймають ті самі параметри паролів, що й run.
Як працювати із зашифрованими PDF?
Передайте password у run, щоб спершу відкрити зашифровані вхідні дані. Розблокування та інструмент виконуються в одному запиті. Для інструментів із кількома файлами, як-от Об’єднати, передайте passwords з одним елементом на кожен файл, а для відкритого файла вкажіть порожній рядок. Кожен файл розблоковується окремо.
await client.run("compress", { input: await readFileInput("locked.pdf"), password: "secret" });
await client.run("merge", {
input: [await readFileInput("locked.pdf"), await readFileInput("open.pdf")],
passwords: ["secret", ""],
});Для пакетної обробки passwordFor(file, index) повертає пароль для кожного вхідного файла. Щоб зняти захист назавжди, скористайтеся інструментом Зняти пароль.
Як працюють помилки?
Збої викидають Pdf123Error. Він має status (undefined, якщо відповіді не було), code, reason для докладної причини, наприклад password_required, і problem з відомостями про проблему від сервера, серед яких за наявності є hint. Помилки перевірки викидаються до будь-якого завантаження.
import { Pdf123Error } from "@pdf123/sdk";
try {
await client.run("compress", { input: await readFileInput("locked.pdf") });
} catch (error) {
if (error instanceof Pdf123Error) {
console.error(error.status, error.code, error.reason, error.problem?.hint);
} else {
throw error;
}
}Коди сервера перелічено на сторінці Коди помилок. Клієнт додає такі власні коди:
| Код | Значення |
|---|---|
network_error | Запит не отримав відповіді |
timeout | Запит перевищив timeoutMs |
cancelled | Ваш signal перервав виклик |
input_unreadable | Локальний шлях не вдалося прочитати |
output_unwritable | Результат не вдалося зберегти за вказаним шляхом |
output_mismatch | saveResult відмовився записувати ZIP під іменем .pdf |
unsupported_file_type | Інструмент не приймає цей тип файла |
unknown_tool | Ідентифікатора інструмента не існує; у повідомленні запропоновано схожі |
invalid_target | call відхилив шлях /api/... із сегментами .., . або порожніми |
no_content | Інструменту не було що повернути (HTTP 204) |
saveResult ніколи не перезаписує файл усередині каталогу. Щоб ще до завантаження дізнатися, чи можна записати за певним шляхом, спершу викличте checkOutput(output, { several }).
Які налаштування TypeScript і модулів підходять?
Типи розпізнаються за значеннями moduleResolution nodenext, node16, bundler і старішого node10, зокрема для підшляху @pdf123/sdk/node. Пакет — модуль ES, тому import працює всюди. require("@pdf123/sdk") із CommonJS працює на Node 22.12 або новішій версії, а на Node 20 недоступний.
Як налаштувати клієнт?
| Параметр | Змінна середовища | Типове значення |
|---|---|---|
baseUrl | PDFX_API_BASE | https://pdf123.xyz |
apiKey | PDFX_API_KEY | немає, анонімно |
timeoutMs | немає | 300000 |
new Pdf123Client() ніколи не читає середовище. clientFromEnv() з @pdf123/sdk/node читає дві змінні, і передані вами параметри мають пріоритет. Ключ надсилається в заголовку X-API-KEY; див. Автентифікація.
Щоб використовувати власний сервер, задайте в baseUrl його адресу, наприклад http://localhost:8080. Див. Self-host.
Чи можна використовувати SDK у браузері?
Так. Кореневій точці входу @pdf123/sdk потрібен лише fetch, і залежностей від Node в неї немає. Об’єкти FileInput створюйте самі з File або Uint8Array, бо допоміжні функції для файлів містяться в точці входу node. Не вбудовуйте ключ API в код для браузера, який можуть прочитати інші люди.
Пов’язані сторінки
- Огляд для розробників з REST API й автентифікацією
- Командний рядок pdfx, побудований на цьому SDK
- MCP-сервери для ШІ-агентів
- Swagger UI і документ OpenAPI
- Сторінки інструментів: Об’єднати, Розрізати, Стиснути, OCR, Поставити пароль
FAQ
Чи потрібен SDK ключ API?
Ні. Клієнт, створений без параметрів, анонімно викликає публічний API. Передайте apiKey, щоб надсилати заголовок X-API-KEY.
Яка версія Node потрібна SDK?
Node 20.3 або новіша версія, чи Bun. Кореневій точці входу потрібен лише fetch, тому вона працює й у браузерах та бандлерах.
Як отримати інструмент, новіший за SDK?
Скористайтеся client.call. Він приймає ідентифікатор інструмента, ідентифікатор операції на кшталт general/merge-pdfs або шлях /api/..., а також файли й поля. Локально нічого не перевіряється й не підставляється за замовчуванням.
Файл якого розміру можна завантажити?
Вхідні дані загальним розміром понад 95 MB автоматично йдуть через API завантаження частинами. Тіло одного прямого запиту обмежено 100 MiB.
Чому виклик викинув помилку для PDF без таблиць?
Інструменти pdf-to-csv і pdf-to-xlsx відповідають без вмісту, якщо в PDF немає таблиці, яку можна виявити. SDK викидає Pdf123Error із кодом no_content замість того, щоб повернути порожній файл. Перевіряйте цей код, якщо порожній результат для вас прийнятний.