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üz | En uygun kullanım | Kurulum veya adres | Kılavuz |
|---|---|---|---|
| REST API | Herhangi bir dil, sunucular, kabuk betikleri | https://pdf123.xyz/api/v1 | API başvurusu |
| TypeScript SDK | Tür bilgisi isteyen Node, Bun ve tarayıcı kodu | npm install @pdf123/sdk | SDK kılavuzu |
| Komut satırı | Terminaller, CI işleri, yerel dosya toplulukları | npm install -g @pdf123/cli | CLI kılavuzu |
| MCP | Claude Code, Claude Desktop ve Cursor gibi yapay zekâ ajanları | npx -y @pdf123/mcp veya https://pdf123.xyz/mcp | MCP 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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfAynı birleştirme TypeScript SDK ile:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfKimlik 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…
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 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.
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.pdfBir 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ır | Değer |
|---|---|
| Web sitesinde dosya boyutu | Dosya başına 500 MB |
| Tek bir doğrudan API isteğinin gövdesi | 100 MiB, multipart çerçeveleme dahil |
| Parçalı yükleme | SDK, 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 neden | HTTP durumu | Anlamı |
|---|---|---|
bad_request | 400 | Geçersiz parametreler veya multipart gövde |
password_required | 400 | PDF şifrelenmiş ve parola gönderilmemiş |
invalid_pdf | 400 | Dosya PDF değil veya hasarlı; PDF onar aracını deneyin |
page_out_of_range | 400 | İstenen sayfa yok |
not_found | 404 | Bilinmeyen işlem yolu |
rate_limited | 429 | Kota 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 komutu | Ne yapar |
|---|---|---|---|
| Birleştir | /general/merge-pdfs | pdfx merge | Birden çok PDF'yi tek dosyada birleştirir |
| Böl | /general/split-pages | pdfx split | Bir PDF'yi ayrı dosyalara böler |
| Sıkıştır | /misc/compress-pdf | pdfx compress | Boyutu küçültmek için PDF akışlarını yeniden sıkıştırır |
| Döndür | /general/rotate-pdf | pdfx rotate | Sayfa yönünü değiştirir |
| Koru | /security/add-password | pdfx protect | PDF'yi parolayla şifreler |
| Kilidi aç | /security/remove-password | pdfx unlock | Parola korumasını kaldırır |
| Filigran | /security/add-watermark | pdfx watermark | Metin veya görsel filigran ekler |
| OCR | /misc/ocr-pdf | pdfx ocr | Taranmış bir PDF'yi okuyup Markdown döndürür |
| PDF'den Markdown'a | /convert/pdf/markdown | pdfx pdf-to-markdown | Bir PDF'yi Markdown'a dönüştürür |
| PDF'den Word'e | /convert/pdf/word | pdfx convert-to-word | Bir PDF'yi düzenlenebilir Word dosyasına dönüştürür |
| Belge bilgisi | /security/get-info-on-pdf | pdfx get-info | Meta verileri, izinleri, yazı tiplerini ve yapıyı raporlar |
| Onar | /misc/repair | pdfx repair | Hasarlı 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/mcpsunucusunu vehttps://pdf123.xyz/mcpadresindeki 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.mddosyaları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.jsonldise 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.