Aynı işlem, dört istemci: tarayıcı, curl, MCP, pdfx
Aynı PDF123 birleştirmesi dört istemciyle: tarayıcı formu, /api/v1/general/merge-pdfs’e curl, /mcp’de MCP ve API tabanınıza karşı yerel ya da --cloud pdfx.
Dört istemci dört ürün gibi görünür. Tek bir kataloğu paylaşırlar. Somut iş olarak Merge alın: sayfaları görüntülere rasterize etmeden PDF’leri yükleme sırasında birleştirin. Aynı kalıp diğer her katalog aracı için de geçerlidir (sıkıştırma, OCR, dönüştürme ve geri kalanı): bir işlem kimliği, onu çağırmanın dört yolu.
Tarayıcı
/merge sayfasını açın, dosyaları istediğiniz sırayla ekleyin, İşle’ye basın, indirin. Katalog araçları için hesap gerekmez. Sayfanın “Bunu koddan çağır” bloğu, formun gönderdiği aynı alanlardan curl üretir; böylece arayüz ile HTTP sözleşmesi hizalı kalır.
Bu blok pazarlama metni değildir. Portalın form için zaten kullandığı araç tanımından üretilir; bu yüzden bir parametre adı değişikliği iki yerde birlikte görünür. Form isteğe bağlı sortType=byFileName kabul ediyorsa curl örneği de aynı alanı taşıyabilir.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Anonim katalog çağrıları anahtar gerektirmez. Geliştiriciler sayfasından alınan anahtarlar otomasyona kararlı bir kimlik (ve kendi sunucunuzdaki sunuculara bir kapı) verir. OpenAPI /v1/openapi.json adresindedir.
Çok adımlı işler için POST /api/v1/pipeline, bir steps alanında sıralı işlemler kabul eder (örneğin birleştir, sonra filigran ekle, sonra sıkıştır). Yeniden denemeler işi iki kez çalıştırmamalıysa Idempotency-Key gönderin; başarılı bir yeniden oynatma Idempotency-Replayed ile dönebilir. Hatalar, rate_limited ve bad_request gibi kararlı kodlarla application/problem+json kullanır (Geliştirici hataları).
Barındırılan yanıtlar ayrıca X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını duyurur; HTTP 429 Retry-After içerir. Bu başlıkları canlı bütçe olarak alın, bir blog yazısından ezberlenmiş bir sayı olarak değil (anonim hız sınırlama).
MCP
Model Context Protocol konuşan ajanlar /mcp adresine bağlanır, merge’i bir araç olarak keşfeder ve REST ile aynı API anahtarı hikâyesiyle çağırır. Belgeler: Geliştiriciler MCP.
MCP ikinci bir katalog değildir. OpenAPI’nin listelediği aynı işlemler üzerinde bir keşif ve çağırma protokolüdür. Bir işlem MCP’de eksikse bu ayrı bir ürün yol haritası değil, bir sunucu hatasıdır. İstemci bağlanmadan önce araçların düzyazı bir dizinini istiyorsanız MCP’yi /llms.txt ile eşleyin.
pdfx CLI
Yerel pdf-core:
pdfx merge a.pdf b.pdf -o merged.pdf
Ya da portalın kullandığı aynı sunucu:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Yerel kip hiç yükleme yapmaz; bulut kipi taban URL’nize curl ile aynı çok parçalı biçimde istek atar. dist/skills/pdf-toolbox/SKILL.md altındaki kodlama ajanı becerisi, ajanların ikinci bir OpenAPI uydurmaması için aynı merge ve pipeline biçimlerini belgeler.
Bu istemcilerden herhangi biri üzerinden OCR yine /api/v1/misc/ocr-pdf adresinden Markdown döner, gizli bir metin katmanı değil. Bu olgu paylaşılan sözleşmenin parçasıdır: dönüş tipini diğerleri olmadan bir istemcide değiştirmek “aynı işlem” vaadini bozar. Compress, akış yeniden sıkıştırması için /api/v1/misc/compress-pdf üzerinde kalır; merge’den farklı bir işlemdir ve aynı dört yoldan erişilebilir.
Aynılık neden önemli
Tarayıcı birleştirmesi ile API birleştirmesi bir gün ayrışırsa, demo sayfası hâlâ iyi görünürken otomasyonlar sessizce geriler. Tek işlem, dört tutamak asıl meseledir. Portal bir kolaylık istemcisidir; merge, compress veya OCR’ın ikinci bir uygulaması değil.
Bu aynı zamanda masaüstü bir çatalın neden olmadığının da nedenidir: beşinci bir arayüz ağacı, kayma sorununu farklı bir ikili dosya adı altında yeniden yaratırdı. Daha geniş çerçeve: Yalnızca tarayıcılar için değil, yapay zeka ajanları için. Masaüstü kararı için Masaüstü uygulamayı neden atladık yazısına bakın. API’yi kendi ağınızda ayağa kaldırmak için Self-host sayfasına bakın.