Към основното съдържание
PPDF123

PDF123 за разработчици: REST API, SDK, команден ред и MCP

Платформата на PDF123 за разработчици предлага едни и същи 97 PDF инструмента през четири интерфейса: REST API с описание в OpenAPI, TypeScript SDK, команден ред pdfx и MCP сървъри за AI агенти. Анонимните заявки не изискват профил или API ключ.

На тази страница

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

И четирите интерфейса извикват едни и същи операции, затова обединяването дава един и същ резултат във всеки от тях. Изберете според това къде работи кодът ви.

ИнтерфейсНай-подходящ заИнсталиране или адресРъководство
REST APIВсеки език, сървъри, shell скриптовеhttps://pdf123.xyz/api/v1API документация
TypeScript SDKКод за Node, Bun и браузър, който се нуждае от типовеnpm install @pdf123/sdkРъководство за SDK
Команден редТерминал, CI задачи, пакети от локални файловеnpm install -g @pdf123/cliРъководство за CLI
MCPAI агенти като Claude Code, Claude Desktop и Cursornpx -y @pdf123/mcp или https://pdf123.xyz/mcpРъководство за MCP

Използвайте REST API, ако кодът ви не е на TypeScript. Използвайте SDK, ако е, защото опциите на всеки инструмент са типизирани и се проверяват преди качването. Използвайте командния ред за еднократни задачи и shell скриптове. Използвайте MCP, когато AI агент трябва сам да реши кой инструмент да пусне.

Каталогът съдържа 97 инструмента. 58 от тях имат страница в този сайт, например Обединяване на PDF, Разделяне на PDF и Компресиране на PDF. Останалите са операции на сървъра без уеб страница, като всички са достъпни в SDK, в командния ред и в MCP.

Как да изпратя първата си заявка?

Обединете два файла с curl. Заявката е multipart формуляр с по една част fileInput за всеки файл.

REST: merge two PDFsbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Същото обединяване с TypeScript SDK:

SDK: merge two PDFsts
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: merge two PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Как работи удостоверяването?

Анонимните заявки към публичния API не изискват профил или ключ. Изпращайте API ключ в заглавката X-API-KEY, когато искате да обособите трафика си или да извикате хостваната MCP крайна точка, която винаги изисква ключ.

Влезте в профила си, за да създадете ключ в панела по-долу, и го съхранявайте на сигурно място.

Проверка на сесията…

Call the API with a keybash
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 към базовия адрес https://pdf123.xyz/api/v1, групирана по категории. Например обединяването е /general/merge-pdfs, а компресирането е /misc/compress-pdf.

Как да свържа няколко инструмента в една заявка?

POST /api/v1/pipeline приема частите fileInput и поле steps. Полето със стъпките е JSON масив от обекти с op и по избор params. Всяка стъпка получава резултата от предишната.

Merge, then compress, in one requestbash
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_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 от AI агент?

Агентът може да използва инструментите по три начина:

  • Да свърже 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 за настройката и Enterprise за възможностите за поддръжка.

Често задавани въпроси

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

Да, за анонимна употреба. Заявките към публичния API не изискват профил или ключ. Хостваните отговори съдържат заглавки за ограничението на честотата, така че клиентът може да забави темпото, преди да получи отговор 429.

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

Не за REST API, SDK и командния ред, когато използвате публичния сайт. Да за хостваната MCP крайна точка на /mcp, която отговаря с 401 без заглавка X-API-KEY. Можете да създадете ключ на тази страница, след като влезете в профила си.

Какъв е ограничението за размер на файл?

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

Мога ли да пусна API на собствен сървър?

Да. Стартирайте сървъра сами и задайте базовия адрес на API към него. SDK, командният ред и локалният MCP сървър приемат собствен базов адрес.

Как да докладвам грешка?

Копирайте полетата code, reason и detail от отговора с описание на проблема, както и часа на заявката, и ги изпратете през страницата за контакт. Не изпращайте самия PDF файл, освен ако поддръжката не го поиска.

SDK, команден ред или MCP?

Използвайте SDK в TypeScript код, командния ред за скриптове и пакети от локални файлове, а MCP, когато AI агент избира инструмента. И трите използват един и същ каталог и един и същ сървър, затова можете да ги комбинирате.