Как установить 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 запускает инструмент для одного файла, например Сжать PDF, Повернуть PDF или Задать пароль, для каждого входного файла с одними и теми же параметрами. По умолчанию одновременно обрабатываются два файла. Один неудачный файл никогда не останавливает остальные.
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, чтобы сначала открыть зашифрованный файл. Снятие защиты и запуск инструмента выполняются в одном запросе. Для инструментов, которые принимают несколько файлов, например Объединить PDF, передайте 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, Задать пароль
Вопросы и ответы
Нужен ли SDK ключ API?
Нет. Клиент, созданный без параметров, обращается к публичному API анонимно. Передайте apiKey, чтобы отправлять заголовок X-API-KEY.
Какая версия Node нужна SDK?
Node 20.3 или новее, либо Bun. Корневой точке входа нужен только fetch, поэтому она работает и в браузерах, и в сборщиках.
Как вызвать инструмент, который новее SDK?
Используйте client.call. Он принимает идентификатор инструмента, идентификатор операции, например general/merge-pdfs, или путь /api/..., а также файлы и поля. Локально ничего не проверяется и значения по умолчанию не подставляются.
Файл какого размера можно загрузить?
Входные данные общим объёмом более 95 МБ автоматически проходят через API загрузки частями. Тело одного прямого запроса ограничено 100 MiB.
Почему вызов выбросил ошибку для PDF без таблиц?
Инструменты вроде pdf-to-csv и pdf-to-xlsx отвечают без содержимого, если в PDF нет обнаруживаемой таблицы. SDK выбрасывает Pdf123Error с кодом no_content вместо того, чтобы вернуть пустой файл. Проверяйте этот код, если пустой результат вас устраивает.