Как да използвам PDF123 от код?
И четирите интерфейса извикват едни и същи операции, затова обединяването дава един и същ резултат във всеки от тях. Изберете според това къде работи кодът ви.
| Интерфейс | Най-подходящ за | Инсталиране или адрес | Ръководство |
|---|---|---|---|
| REST API | Всеки език, сървъри, shell скриптове | https://pdf123.xyz/api/v1 | API документация |
| TypeScript SDK | Код за Node, Bun и браузър, който се нуждае от типове | npm install @pdf123/sdk | Ръководство за SDK |
| Команден ред | Терминал, CI задачи, пакети от локални файлове | npm install -g @pdf123/cli | Ръководство за CLI |
| MCP | AI агенти като Claude Code, Claude Desktop и Cursor | npx -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 за всеки файл.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfСъщото обединяване с TypeScript SDK:
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 към базовия адрес https://pdf123.xyz/api/v1, групирана по категории. Например обединяването е /general/merge-pdfs, а компресирането е /misc/compress-pdf.
Как да свържа няколко инструмента в една заявка?
POST /api/v1/pipeline приема частите fileInput и поле 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 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_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 от 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 агент избира инструмента. И трите използват един и същ каталог и един и същ сървър, затова можете да ги комбинирате.