Yalnızca tarayıcılar için değil, yapay zeka ajanları için: API nasıl çalışır

Tarayıcı sekmesi hâlâ çalışır: bir araç seçin, dosyayı yükleyin, sonucu indirin. Ajanlar ve betikler aynı işlemleri bir arayüz açmadan çağırır. İki yol da aynı kataloğa çıkar.

Her araç sayfası aynı zamanda bir uç noktadır

Merge, bölme, sıkıştırma, OCR, dönüştürme: katalogdaki her araç /api/v1/… altına eşlenir. Bir araç sayfasını açıp Bunu koddan çağır bölümüne inin; genel bir şablon değil, o aracın gerçek parametrelerinden üretilmiş bir curl örneği bulacaksınız. Anonim çağrılar genel sitede hesap ve API anahtarı istemez; anonim önekler /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ ve /api/v1/filter/ şeklindedir.

Birleştirme örneği somuttur:

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

OpenAPI /v1/openapi.json adresinde bulunur. Çok adımlı işler, sıralı bir steps listesiyle POST /api/v1/pipeline kullanır. Bir yeniden denemenin değiştirici bir görevi ikinci kez çalıştırmaması gerekiyorsa Idempotency-Key gönderin. Barındırılan yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını duyurur; HTTP 429 durumunda Retry-After değerini okuyun (anonim hız sınırlama).

Aynı katalog üzerinden OCR, /api/v1/misc/ocr-pdf adresinden Markdown (text/markdown) döner; gizli metin katmanı olan bir PDF değil. Bu uç noktadan aranabilir bir PDF bekleyen ajanlar indirmeyi yanlış işler; sözleşme ardışık düzenler için metin çıkarmadır, OCRmyPDF tarzı yeniden yazma değil.

MCP’yi konuşan istemciler için MCP

MCP (Model Context Protocol), ajan istemcilerinin dokümanları kazımak yerine araçları fonksiyon olarak keşfetmesini ve çağırmasını sağlar. Bu site, REST API’nin yanında /mcp adresinde bir MCP sunucusu sunar; uyumlu bir istemci bir kez bağlanır ve kataloğun tamamını alır.

MCP ve REST aynı kimlik doğrulama beklentilerini paylaşır: araç öneklerinin izin verdiği yerde anonim; kararlı otomasyon ve kapılı self-host sunucular için API anahtarları. Bir ajanı /mcp adresine yöneltmek, curl’ü /api/v1/… adresine yöneltmekten farklı bir ürün değildir. Belgeler: Geliştiriciler MCP.

Hatalar düzyazı değil, yapılandırılmıştır

Hatalar çıplak bir 500 ya da “bir şeyler ters gitti” yerine application/problem+json (RFC 7807 tarzı) döner. Her yükün kararlı bir kodu (rate_limited, bad_request, invalid_document, missing_dependency ve benzerleri), okunabilir bir ipucu ve çoğu zaman bir sonraki adımı vardır. İnsanlar üzerinden göz gezdirebilir; ajanlar bir yığın izini kimseye ayrıştırtmadan yeniden denemeye, dosyayı değiştirmeye veya durmaya karar verebilir.

Çağıran bir betik olduğunda bu yapı, dostane bir HTML hata sayfasından daha önemlidir. Başvuru: Geliştirici hataları.

llms.txt araçlar içindir, sıralamalar için değil

/llms.txt, siteyi süren aynı katalogdan üretilen ve her aracı (ad, kısa açıklama, URL) listeleyen düz metin bir dizindir. Kodlama ajanları ve doküman araçları onu bir README gibi okuyabilir. Bir Google sıralama kaldıracı değildir: Arama /llms.txt dosyasını yok sayar (kaynaklar: Google'ın yapay zeka optimizasyonu kılavuzu). Üretildiği için, elle düzenlenen bir dosyanın sessizce bayatlaması gibi bayatlayamaz.

CLI ve beceri aynı biçimleri paylaşır

pdfx yerel pdf-core’u ya da bir taban URL’ye karşı --cloud seçeneğini çalıştırabilir. dist/skills/pdf-toolbox/SKILL.md altındaki kodlama ajanı becerisi, ajanların ikinci bir sözleşme uydurmaması için merge ve pipeline curl biçimlerini belgeler. Dört istemci, tek katalog: Aynı işlem, dört istemci.

Tarayıcı yolu değişmedi

Bir sekmeye dosya bırakmak aynı şekilde çalışır. Eklenen yüzey, bir ajan, betik veya CI için aynı uç noktalardır: arada insan olmadan aynı işleme. Self-host bu yüzeyi kendi ağınızda tutar (Self-host); barındırılan sürüm anonim deneme yolu olarak kalır.

API başvurusu: Swagger. Her iki yol için temeller: Yardım ve Geliştiriciler.