تخطَّ إلى المحتوى الرئيسي
PPDF123

PDF123 للمطوّرين: REST API وSDK وسطر الأوامر وMCP

توفّر منصة PDF123 للمطوّرين أدوات PDF الخمس والتسعين نفسها عبر أربع واجهات: REST API موصوفة بمواصفة OpenAPI، وTypeScript SDK وسطر أوامر pdfx وخوادم MCP لوكلاء الذكاء الاصطناعي. لا تحتاج الطلبات المجهولة إلى حساب ولا إلى مفتاح API.

في هذه الصفحة

كيف أستخدم 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وكلاء الذكاء الاصطناعي مثل Claude Code وClaude Desktop وCursornpx -y @pdf123/mcp أو https://pdf123.xyz/mcpدليل MCP

استخدم REST API إذا لم تكن شيفرتك مكتوبة بـ TypeScript. واستخدم SDK إذا كانت كذلك، لأن خيارات كل أداة محدّدة الأنواع ويجري التحقق منها قبل الرفع. واستخدم سطر الأوامر للمهام لمرة واحدة ولنصوص الصَّدفة. واستخدم MCP حين تريد أن يقرّر وكيل ذكاء اصطناعي أي أداة يشغّل.

يضم الكتالوج 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 لتحديد مفتاح واحد يقبله الخادم. راجع الاستضافة الذاتية.

أين مرجع 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 تلقائيًا إلى واجهة الرفع عندما يتجاوز المجموع 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_required400ملف PDF مشفّر ولم تُرسل كلمة المرور
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 الموقع ببيانات منظمة.

يشرح مقال "Built for AI Agents, Not Just Browsers" في مدونة PDF123 كيف يتكامل REST API مع MCP.

هل يمكنني تشغيل PDF123 على خادمي؟

نعم. الواجهة الخلفية هي برنامج pdfx-server الذي يعمل داخل Docker. وجّه SDK أو سطر الأوامر أو خادم MCP إليه عبر PDFX_API_BASE، وتبقى ملفاتك داخل شبكتك. راجع الاستضافة الذاتية للإعداد والمؤسسات لخيارات الدعم.

الأسئلة الشائعة

هل PDF123 API مجانية؟

نعم للاستخدام المجهول. لا تحتاج طلبات 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 عندما يختار وكيل ذكاء اصطناعي الأداة. تستخدم الثلاثة الكتالوج نفسه والخادم نفسه، فيمكنك الجمع بينها.