코드에서 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 | Claude Code, Claude Desktop, Cursor 같은 AI 에이전트 | npx -y @pdf123/mcp 또는 https://pdf123.xyz/mcp | MCP 가이드 |
코드가 TypeScript가 아니라면 REST API를 쓰세요. TypeScript라면 SDK를 쓰는 편이 좋습니다. 도구 옵션에 타입이 있고 업로드 전에 검사되기 때문입니다. 일회성 작업과 셸 스크립트에는 명령줄이 알맞습니다. 어떤 도구를 실행할지 AI 에이전트가 판단하게 하려면 MCP를 쓰세요.
카탈로그에는 97개의 도구가 있습니다. 그중 58개는 PDF 병합, PDF 분할, PDF 압축처럼 이 웹사이트에 페이지가 있습니다. 나머지는 웹 페이지가 없는 백엔드 작업이며, 모두 SDK, 명령줄, MCP에서 사용할 수 있습니다.
첫 요청은 어떻게 실행하나요?
curl로 파일 두 개를 병합합니다. 요청은 멀티파트 폼이며, 파일마다 fileInput 파트를 하나씩 보냅니다.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfTypeScript 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에 대한 익명 호출에는 계정도 키도 필요 없습니다. 내 트래픽을 구분하고 싶거나 항상 키가 필요한 호스팅 MCP 엔드포인트를 호출할 때는 X-API-KEY 헤더에 API 키를 담아 보내세요.
키를 만들려면 아래 패널에서 로그인하세요. 만든 키는 안전한 곳에 보관하세요.
세션을 확인하는 중…
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 문서는 클라이언트 생성기를 위한 기계 판독용 원본입니다.
모든 작업은 기본 URL https://pdf123.xyz/api/v1 아래의 POST이며 카테고리별로 묶여 있습니다. 예를 들어 병합은 /general/merge-pdfs, 압축은 /misc/compress-pdf입니다.
한 번의 요청으로 여러 도구를 연결하려면?
POST /api/v1/pipeline은 fileInput 파트와 steps 필드를 받습니다. steps 필드는 op와 선택 항목인 params를 가진 객체의 JSON 배열입니다. 각 단계는 이전 단계의 출력을 입력으로 받습니다.
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은 사람이 읽도록 쓴 문장이며 도구의 원시 출력은 담기지 않습니다. 모든 코드는 오류 코드에 정리되어 있습니다.
| 코드 또는 reason | HTTP 상태 | 의미 |
|---|---|---|
bad_request | 400 | 매개변수 또는 멀티파트 본문이 올바르지 않음 |
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에 대한 상대 경로입니다. 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를 쓰세요. 셋 다 같은 카탈로그와 같은 서버를 쓰므로 함께 사용할 수 있습니다.