ควรเรียกใช้ PDF123 จากโค้ดด้วยวิธีใด
ทั้งสี่ช่องทางเรียกการทำงานเดียวกัน ดังนั้นการรวมไฟล์ให้ผลลัพธ์เหมือนกันไม่ว่าจะใช้ช่องทางใด เลือกตามที่ที่โค้ดของคุณทำงาน
| ช่องทาง | เหมาะกับ | การติดตั้งหรือที่อยู่ | คู่มือ |
|---|---|---|---|
| REST API | ภาษาใดก็ได้ เซิร์ฟเวอร์ และสคริปต์เชลล์ | 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 หากเขียนด้วย TypeScript เพราะตัวเลือกของเครื่องมือมีชนิดข้อมูลและถูกตรวจสอบก่อนอัปโหลด ใช้บรรทัดคำสั่งสำหรับงานครั้งเดียวและสคริปต์เชลล์ ใช้ 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 เพื่อกำหนดคีย์หนึ่งชุดที่เซิร์ฟเวอร์ยอมรับ ดู โฮสต์เอง
เอกสารอ้างอิง 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 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 แล้วไฟล์ของคุณจะอยู่ในเครือข่ายของคุณเอง ดูโฮสต์เองสำหรับการตั้งค่า และ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 base เป็นที่อยู่ของเซิร์ฟเวอร์นั้น SDK บรรทัดคำสั่ง และเซิร์ฟเวอร์ MCP ในเครื่องรองรับ base URL ที่กำหนดเองทั้งหมด
จะรายงานข้อผิดพลาดได้อย่างไร
คัดลอกฟิลด์ code, reason และ detail จากคำตอบแบบ problem พร้อมเวลาที่ส่งคำขอ แล้วส่งผ่านหน้าติดต่อ อย่าส่งไฟล์ PDF เว้นแต่ทีมสนับสนุนขอ
ควรใช้ SDK บรรทัดคำสั่ง หรือ MCP
ใช้ SDK ภายในโค้ด TypeScript ใช้บรรทัดคำสั่งสำหรับสคริปต์และชุดไฟล์ในเครื่อง และใช้ MCP เมื่อให้เอเจนต์ AI เป็นผู้เลือกเครื่องมือ ทั้งสามใช้แคตตาล็อกและเซิร์ฟเวอร์เดียวกัน จึงใช้ร่วมกันได้