Как использовать 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 и 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То же объединение с помощью SDK для TypeScript:
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 относительно базового URL https://pdf123.xyz/api/v1, сгруппированный по категориям. Например, объединение — /general/merge-pdfs, а сжатие — /misc/compress-pdf.
Как объединить несколько инструментов в один запрос?
POST /api/v1/pipeline принимает части fileInput и поле steps. Поле 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 МБ на файл |
| Тело одного прямого запроса к API | 100 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_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описывает сайт в виде структурированных данных.
Запись «Создан для 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 — когда инструмент выбирает ИИ-агент. Все три используют один каталог и один сервер, поэтому их можно сочетать.