Перейти к основному содержимому
PPDF123

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

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

На этой странице

Как использовать PDF123 из кода?

Все четыре интерфейса вызывают одни и те же операции, поэтому объединение файлов даёт одинаковый результат в каждом из них. Выбирайте по тому, где выполняется ваш код.

ИнтерфейсДля чего подходитУстановка или адресРуководство
REST APIЛюбой язык, серверы, shell-скриптыhttps://pdf123.xyz/api/v1Справочник API
SDK для TypeScriptКод на 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

То же объединение с помощью SDK для TypeScript:

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 относительно базового URL https://pdf123.xyz/api/v1, сгруппированный по категориям. Например, объединение — /general/merge-pdfs, а сжатие — /misc/compress-pdf.

Как объединить несколько инструментов в один запрос?

POST /api/v1/pipeline принимает части fileInput и поле steps. Поле 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 МБ на файл
Тело одного прямого запроса к API100 MiB, включая служебные данные multipart
Загрузка частямиSDK автоматически переключается на API загрузки, когда общий объём превышает 95 МБ

В ответах есть заголовки 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 описывает сайт в виде структурированных данных.

Запись «Создан для AI-агентов, а не только для браузеров» в блоге PDF123 объясняет, как REST API и MCP работают вместе.

Можно ли запустить PDF123 на собственном сервере?

Да. Бэкенд — это программа pdfx-server, которая работает в Docker. Укажите её адрес в переменной PDFX_API_BASE для SDK, командной строки или MCP-сервера, и ваши файлы останутся внутри вашей сети. Настройка описана в разделе Self-host, варианты поддержки — на странице Для предприятий.

Вопросы и ответы

Бесплатен ли API PDF123?

Да, для анонимного использования. Вызовы публичного API не требуют ни аккаунта, ни ключа. Ответы размещённого сервиса содержат заголовки с лимитами, поэтому клиент может снизить скорость раньше, чем получит ответ 429.

Нужен ли мне ключ API?

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

Каков предел размера файла?

Сайт принимает файлы до 500 МБ каждый. Тело одного прямого запроса к API может достигать 100 MiB, включая служебные данные multipart. SDK загружает более крупные входные данные частями автоматически, как только общий объём превысит 95 МБ.

Можно ли развернуть API на собственном сервере?

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

Как сообщить об ошибке?

Скопируйте поля code, reason и detail из ответа с описанием проблемы, добавьте время запроса и отправьте через страницу контактов. Сам PDF не присылайте, пока этого не попросит поддержка.

Что выбрать: SDK, командную строку или MCP?

SDK — внутри кода на TypeScript, командную строку — для скриптов и пакетов локальных файлов, MCP — когда инструмент выбирает ИИ-агент. Все три используют один каталог и один сервер, поэтому их можно сочетать.