Ana içeriğe geç
PPDF123

Geliştiriciler için PDF123: REST API, SDK, komut satırı ve MCP

PDF123 geliştirici platformu, aynı 97 PDF aracını dört arayüzle sunar: OpenAPI ile tanımlı bir REST API, bir TypeScript SDK, pdfx komut satırı ve yapay zekâ ajanları için MCP sunucuları. Anonim çağrılar için hesap ya da API anahtarı gerekmez.

Bu sayfada

PDF123'ü koddan hangi yolla kullanmalıyım?

Dört arayüz de aynı işlemleri çağırır; bu yüzden birleştirme her birinde aynı sonucu verir. Kodunuzun çalıştığı yere göre seçin.

ArayüzEn uygun kullanımKurulum veya adresKılavuz
REST APIHerhangi bir dil, sunucular, kabuk betiklerihttps://pdf123.xyz/api/v1API başvurusu
TypeScript SDKTür bilgisi isteyen Node, Bun ve tarayıcı kodunpm install @pdf123/sdkSDK kılavuzu
Komut satırıTerminaller, CI işleri, yerel dosya topluluklarınpm install -g @pdf123/cliCLI kılavuzu
MCPClaude Code, Claude Desktop ve Cursor gibi yapay zekâ ajanlarınpx -y @pdf123/mcp veya https://pdf123.xyz/mcpMCP kılavuzu

Kodunuz TypeScript ile yazılmadıysa REST API'yi kullanın. TypeScript ile yazıldıysa SDK'yı kullanın; araç seçenekleri türlüdür ve yüklemeden önce denetlenir. Tek seferlik işler ve kabuk betikleri için komut satırını kullanın. Hangi aracın çalışacağına bir yapay zekâ ajanı karar verecekse MCP'yi kullanın.

Katalogda 97 araç var. Bunlardan 58'sının bu sitede kendi sayfası bulunur; örneğin PDF birleştir, PDF böl ve PDF sıkıştır. Diğerleri web sayfası olmayan arka uç işlemleridir ve hepsi SDK'da, komut satırında ve MCP'de kullanılabilir.

İlk isteğimi nasıl çalıştırırım?

İki dosyayı curl ile birleştirin. İstek, her dosya için bir fileInput parçası içeren çok parçalı (multipart) bir formdur.

REST: iki PDF'yi birleştirmebash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Aynı birleştirme TypeScript SDK ile:

SDK: iki PDF'yi birleştirmets
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" });

Aynı birleştirme komut satırıyla:

CLI: iki PDF'yi birleştirmebash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Kimlik doğrulama nasıl çalışır?

Genel API'ye yapılan anonim çağrılar için hesap ya da anahtar gerekmez. Trafiğinizi tanımlamak istediğinizde veya her zaman anahtar gerektiren barındırılan MCP uç noktasını çağırırken X-API-KEY başlığında bir API anahtarı gönderin.

Aşağıdaki panelde anahtar oluşturmak için giriş yapın ve anahtarı güvenli bir yerde saklayın.

Oturumunuz kontrol ediliyor…

API'yi anahtarla çağırmabash
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 anahtarı apiKey olarak alır. Komut satırı ve yerel MCP sunucusu anahtarı PDFX_API_KEY ortam değişkeninden okur.

Not

Kendi sunucunuzda, sunucunun kabul edeceği tek bir anahtar tanımlamak için SECURITY_CUSTOMGLOBALAPIKEY ortam değişkenini ayarlayın. Bkz. Self-host.

API başvurusu nerede?

REST API iki biçimde belgelenmiştir. Swagger UI her uç noktayı tarayıcıda denemenizi sağlar. OpenAPI belgesi istemci üreticileri için makine tarafından okunabilir kaynaktır.

Her işlem, https://pdf123.xyz/api/v1 temel adresi altında kategoriye göre gruplanmış bir POST isteğidir. Örneğin birleştirme /general/merge-pdfs, sıkıştırma /misc/compress-pdf yoludur.

Birkaç aracı tek istekte nasıl zincirlerim?

POST /api/v1/pipeline, fileInput parçalarını ve bir steps alanını alır. Bu alan, her biri bir op ve isteğe bağlı params içeren nesnelerden oluşan bir JSON dizisidir. Her adım, önceki adımın çıktısını girdi olarak alır.

Tek istekte birleştir, sonra sıkıştırbash
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

Bir isteği güvenle nasıl yeniden denerim?

Herhangi bir işlemde Idempotency-Key başlığı gönderin. Aynı isteğin 24 saat içinde tekrarı, yeniden çalışmak yerine ilk sonucu Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtarı farklı bir istek için kullanmak reddedilir. 32 MiB'den büyük sonuçlar saklanmaz; bu yüzden böyle bir isteğin tekrarı 409 yanıtı verir ve yeni bir anahtar gerekir.

Boyut ve hız sınırları nelerdir?

SınırDeğer
Web sitesinde dosya boyutuDosya başına 500 MB
Tek bir doğrudan API isteğinin gövdesi100 MiB, multipart çerçeveleme dahil
Parçalı yüklemeSDK, toplam 95 MB'ı aşınca yükleme API'sine otomatik geçer

Yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır. Durum kodu 429 olan bir yanıt ayrıca Retry-After ekler. Sabit bir kota varsaymak yerine başlıkları okuyun; çünkü kendi sunucunuz kendi sınırlarını belirler. Aşırı büyük bir gövde için alacağınız hatayı istek boyutu sınırı hakkındaki blog yazısı açıklar.

Bir hata neye benzer?

Başarısız istekler application/problem+json döndürür; alanlar type, title, status, detail, code, reason ve hint olur. Önce reason değerine göre dallanın, yoksa code değerine başvurun. detail metni insanlar için yazılmıştır ve ham araç çıktısı içermez. Tüm kodlar Hata kodları sayfasında listelenir.

Kod veya nedenHTTP durumuAnlamı
bad_request400Geçersiz parametreler veya multipart gövde
password_required400PDF şifrelenmiş ve parola gönderilmemiş
invalid_pdf400Dosya PDF değil veya hasarlı; PDF onar aracını deneyin
page_out_of_range400İstenen sayfa yok
not_found404Bilinmeyen işlem yolu
rate_limited429Kota doldu; Retry-After süresini bekleyin

Önce hangi araçları çağırabilirim?

Bu on iki araç isteklerin çoğunu karşılar. Bir aracı tarayıcıda denemek için araç sayfasını kullanın.

Araç sayfasıAPI uç noktasıCLI komutuNe yapar
Birleştir/general/merge-pdfspdfx mergeBirden çok PDF'yi tek dosyada birleştirir
Böl/general/split-pagespdfx splitBir PDF'yi ayrı dosyalara böler
Sıkıştır/misc/compress-pdfpdfx compressBoyutu küçültmek için PDF akışlarını yeniden sıkıştırır
Döndür/general/rotate-pdfpdfx rotateSayfa yönünü değiştirir
Koru/security/add-passwordpdfx protectPDF'yi parolayla şifreler
Kilidi aç/security/remove-passwordpdfx unlockParola korumasını kaldırır
Filigran/security/add-watermarkpdfx watermarkMetin veya görsel filigran ekler
OCR/misc/ocr-pdfpdfx ocrTaranmış bir PDF'yi okuyup Markdown döndürür
PDF'den Markdown'a/convert/pdf/markdownpdfx pdf-to-markdownBir PDF'yi Markdown'a dönüştürür
PDF'den Word'e/convert/pdf/wordpdfx convert-to-wordBir PDF'yi düzenlenebilir Word dosyasına dönüştürür
Belge bilgisi/security/get-info-on-pdfpdfx get-infoMeta verileri, izinleri, yazı tiplerini ve yapıyı raporlar
Onar/misc/repairpdfx repairHasarlı bir PDF'nin yapısını yeniden kurar

Uç noktalar https://pdf123.xyz/api/v1 adresine görelidir. 97 aracın tamamını görmek için pdfx list komutunu çalıştırın veya OpenAPI belgesini açın.

PDF123'ü bir yapay zekâ ajanından nasıl kullanırım?

Bir ajan araçları üç yolla kullanabilir:

  • Bir MCP sunucusu bağlayın. MCP kılavuzu, makinenizdeki dosyalar için yerel @pdf123/mcp sunucusunu ve https://pdf123.xyz/mcp adresindeki barındırılan uç noktayı anlatır.
  • Bir ajan becerisi yükleyin. Ajan becerileri, Claude Code, Codex, Cursor ve benzeri araçlar için SKILL.md dosyalarıdır; biri katalog, biri de her araç içindir.
  • Site dizinini okuyun. /llms.txt araçları, API'yi ve MCP uç noktasını düz metin olarak listeler; /site.jsonld ise siteyi yapılandırılmış veri olarak tanımlar.

PDF123 blogundaki "Built for AI Agents, Not Just Browsers" yazısı, REST API ile MCP'nin nasıl birbirini tamamladığını anlatır.

PDF123'ü kendi sunucumda çalıştırabilir miyim?

Evet. Arka uç, Docker içinde çalışan pdfx-server programıdır. SDK'yı, komut satırını veya MCP sunucusunu PDFX_API_BASE ile ona yöneltin; dosyalarınız ağınızdan çıkmaz. Kurulum için Self-host, destek seçenekleri için Kurumsal sayfasına bakın.

SSS

PDF123 API'si ücretsiz mi?

Anonim kullanım için evet. Genel API'ye yapılan çağrılar için hesap veya anahtar gerekmez. Barındırılan yanıtlar hız sınırı başlıklarını içerir; böylece istemci 429 yanıtı almadan önce yavaşlayabilir.

API anahtarına ihtiyacım var mı?

Genel siteyi kullanırken REST API, SDK ve komut satırı için hayır. /mcp adresindeki barındırılan MCP uç noktası için evet; X-API-KEY başlığı olmadan 401 yanıtı verir. Giriş yaptıktan sonra bu sayfada bir anahtar oluşturabilirsiniz.

Dosya boyutu sınırı nedir?

Web sitesi her biri en fazla 500 MB olan dosyaları kabul eder. Tek bir doğrudan API isteğinin gövdesi, multipart çerçeveleme dahil en fazla 100 MiB olabilir. Toplam 95 MB'ı geçtiğinde SDK daha büyük girdileri otomatik olarak parçalar halinde yükler.

API'yi kendi sunucumda çalıştırabilir miyim?

Evet. Sunucuyu kendiniz çalıştırın ve API tabanını onun adresine ayarlayın. SDK, komut satırı ve yerel MCP sunucusunun hepsi özel bir temel URL kabul eder.

Bir hatayı nasıl bildiririm?

Sorun yanıtındaki code, reason ve detail alanlarını ve isteğin zamanını kopyalayıp iletişim sayfası üzerinden gönderin. Destek istemedikçe PDF dosyasının kendisini göndermeyin.

SDK'yı, komut satırını mı yoksa MCP'yi mi kullanmalıyım?

TypeScript kodunun içinde SDK'yı, betikler ve yerel dosya toplulukları için komut satırını, aracı bir yapay zekâ ajanı seçecekse MCP'yi kullanın. Üçü de aynı kataloğu ve aynı sunucuyu kullanır; dilerseniz birlikte kullanabilirsiniz.