본문으로 건너뛰기
PPDF123

개발자를 위한 PDF123: REST API, SDK, 명령줄, MCP

PDF123 개발자 플랫폼은 같은 97개 PDF 도구를 네 가지 방식으로 제공합니다. OpenAPI로 기술된 REST API, TypeScript SDK, pdfx 명령줄, AI 에이전트용 MCP 서버입니다. 익명 호출에는 계정이나 API 키가 필요 없습니다.

이 페이지의 내용

코드에서 PDF123을 쓰려면 어떤 방법을 골라야 하나요?

네 가지 인터페이스는 모두 같은 작업을 호출하므로, 병합 결과는 어느 쪽을 써도 같습니다. 코드가 실행되는 환경에 맞춰 고르세요.

인터페이스적합한 용도설치 또는 주소가이드
REST API모든 언어, 서버, 셸 스크립트https://pdf123.xyz/api/v1API 레퍼런스
TypeScript SDK타입이 필요한 Node, Bun, 브라우저 코드npm install @pdf123/sdkSDK 가이드
명령줄터미널, CI 작업, 로컬 파일 일괄 처리npm install -g @pdf123/cliCLI 가이드
MCPClaude Code, Claude Desktop, Cursor 같은 AI 에이전트npx -y @pdf123/mcp 또는 https://pdf123.xyz/mcpMCP 가이드

코드가 TypeScript가 아니라면 REST API를 쓰세요. TypeScript라면 SDK를 쓰는 편이 좋습니다. 도구 옵션에 타입이 있고 업로드 전에 검사되기 때문입니다. 일회성 작업과 셸 스크립트에는 명령줄이 알맞습니다. 어떤 도구를 실행할지 AI 에이전트가 판단하게 하려면 MCP를 쓰세요.

카탈로그에는 97개의 도구가 있습니다. 그중 58개는 PDF 병합, PDF 분할, PDF 압축처럼 이 웹사이트에 페이지가 있습니다. 나머지는 웹 페이지가 없는 백엔드 작업이며, 모두 SDK, 명령줄, MCP에서 사용할 수 있습니다.

첫 요청은 어떻게 실행하나요?

curl로 파일 두 개를 병합합니다. 요청은 멀티파트 폼이며, 파일마다 fileInput 파트를 하나씩 보냅니다.

REST: PDF 두 개 병합bash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

TypeScript SDK로 같은 병합을 하는 예입니다.

SDK: PDF 두 개 병합ts
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: PDF 두 개 병합bash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

인증은 어떻게 동작하나요?

공개 API에 대한 익명 호출에는 계정도 키도 필요 없습니다. 내 트래픽을 구분하고 싶거나 항상 키가 필요한 호스팅 MCP 엔드포인트를 호출할 때는 X-API-KEY 헤더에 API 키를 담아 보내세요.

키를 만들려면 아래 패널에서 로그인하세요. 만든 키는 안전한 곳에 보관하세요.

세션을 확인하는 중…

키를 넣어 API 호출bash
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 문서는 클라이언트 생성기를 위한 기계 판독용 원본입니다.

모든 작업은 기본 URL https://pdf123.xyz/api/v1 아래의 POST이며 카테고리별로 묶여 있습니다. 예를 들어 병합은 /general/merge-pdfs, 압축은 /misc/compress-pdf입니다.

한 번의 요청으로 여러 도구를 연결하려면?

POST /api/v1/pipeline은 fileInput 파트와 steps 필드를 받습니다. steps 필드는 op와 선택 항목인 params를 가진 객체의 JSON 배열입니다. 각 단계는 이전 단계의 출력을 입력으로 받습니다.

병합 후 압축을 한 번의 요청으로bash
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 요청 본문 1회100 MiB(멀티파트 구조 포함)
청크 업로드총 크기가 95 MB를 넘으면 SDK가 자동으로 업로드 API로 전환

응답에는 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은 사람이 읽도록 쓴 문장이며 도구의 원시 출력은 담기지 않습니다. 모든 코드는 오류 코드에 정리되어 있습니다.

코드 또는 reasonHTTP 상태의미
bad_request400매개변수 또는 멀티파트 본문이 올바르지 않음
password_required400PDF가 암호화되어 있는데 비밀번호가 전송되지 않음
invalid_pdf400PDF가 아니거나 손상됨. PDF 복구를 시도해 보세요
page_out_of_range400요청한 페이지가 없음
not_found404알 수 없는 작업 경로
rate_limited429할당량을 모두 사용함. Retry-After만큼 기다리세요

먼저 호출해 볼 만한 도구는 무엇인가요?

다음 열두 가지 도구로 대부분의 요청을 처리할 수 있습니다. 브라우저에서 도구를 시험해 보려면 각 도구 페이지를 이용하세요.

도구 페이지API 엔드포인트CLI 명령기능
병합/general/merge-pdfspdfx merge여러 PDF를 하나로 합침
분할/general/split-pagespdfx splitPDF를 여러 파일로 나눔
압축/misc/compress-pdfpdfx compressPDF 스트림을 다시 압축해 크기를 줄임
회전/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-markdownPDF를 Markdown으로 변환
PDF를 Word로/convert/pdf/wordpdfx convert-to-wordPDF를 편집 가능한 Word 파일로 변환
문서 정보/security/get-info-on-pdfpdfx get-info메타데이터, 권한, 글꼴, 구조를 보고
복구/misc/repairpdfx repair손상된 PDF의 구조를 다시 만듦

엔드포인트는 https://pdf123.xyz/api/v1에 대한 상대 경로입니다. 97개 도구 전체를 보려면 pdfx list를 실행하거나 OpenAPI 문서를 여세요.

AI 에이전트에서 PDF123을 쓰려면?

에이전트가 도구를 사용하는 방법은 세 가지입니다.

  • MCP 서버를 연결합니다. MCP 가이드에서 내 컴퓨터의 파일을 위한 로컬 서버 @pdf123/mcp와 https://pdf123.xyz/mcp의 호스팅 엔드포인트를 설명합니다.
  • 에이전트 스킬을 불러옵니다. 에이전트 스킬은 Claude Code, Codex, Cursor 같은 도구를 위한 SKILL.md 파일이며, 카탈로그용 하나와 도구마다 하나씩 있습니다.
  • 사이트 색인을 읽습니다. /llms.txt에는 도구, API, MCP 엔드포인트가 일반 텍스트로 나열되어 있고, /site.jsonld는 사이트를 구조화된 데이터로 설명합니다.

REST API와 MCP가 어떻게 어우러지는지는 PDF123 블로그의 글 "Built for AI Agents, Not Just Browsers"에서 설명합니다.

PDF123을 내 서버에서 실행할 수 있나요?

네. 백엔드는 pdfx-server 프로그램이며 Docker에서 실행됩니다. SDK, 명령줄, MCP 서버가 PDFX_API_BASE로 해당 서버를 가리키게 하면 파일이 내 네트워크 안에 머뭅니다. 설정 방법은 셀프 호스트, 지원 옵션은 엔터프라이즈를 참고하세요.

FAQ

PDF123 API는 무료인가요?

익명 사용은 무료입니다. 공개 API 호출에는 계정이나 키가 필요 없습니다. 호스팅 응답에 요청 횟수 제한 헤더가 포함되므로, 클라이언트는 429 응답을 받기 전에 속도를 늦출 수 있습니다.

API 키가 필요한가요?

공개 사이트를 쓰는 경우 REST API, SDK, 명령줄에는 필요 없습니다. 호스팅 MCP 엔드포인트 /mcp에는 필요하며, X-API-KEY 헤더가 없으면 401로 응답합니다. 키는 이 페이지에서 로그인한 뒤 만들 수 있습니다.

파일 크기 제한은 얼마인가요?

웹사이트는 파일당 최대 500 MB까지 받습니다. 직접 API 요청 본문 하나는 멀티파트 구조를 포함해 최대 100 MiB입니다. 총 크기가 95 MB를 넘으면 SDK가 더 큰 입력을 자동으로 청크 단위로 업로드합니다.

API를 셀프 호스트할 수 있나요?

네. 서버를 직접 실행하고 API 기본 주소를 그 서버의 주소로 설정하세요. SDK, 명령줄, 로컬 MCP 서버 모두 사용자 지정 기본 URL을 받아들입니다.

오류는 어떻게 신고하나요?

문제 응답의 code, reason, detail 필드와 요청한 시각을 복사해 문의하기 페이지로 보내 주세요. 지원팀이 요청하지 않는 한 PDF 파일 자체는 보내지 마세요.

SDK, 명령줄, MCP 중 무엇을 써야 하나요?

TypeScript 코드 안에서는 SDK, 스크립트와 로컬 파일 일괄 처리에는 명령줄, AI 에이전트가 도구를 고르게 하려면 MCP를 쓰세요. 셋 다 같은 카탈로그와 같은 서버를 쓰므로 함께 사용할 수 있습니다.