API
Belge dönüştürme API'si
Belge dönüştürme API'si, tek bir POST /v1/convert/{name} çağrısında bir dosya, URL veya HTML alıp Markdown döndüren bir HTTPS API'sidir.
Anonim deneme, 10 MB ve 25 sayfaya kadar dosya kabul eder; IP başına saatte 3, günde 10 dönüştürme yapılabilir. Lite, 100 MB'a kadar dosyalarla aylık $20 ile başlar. Pro aylık $50; Max aylık $100.
- Dosya, URL veya satır içi metin başına bir POST /v1/convert/{name} çağrısı
- Yanıtta 60 saniye içinde Markdown ya da yoklanacak bir dönüştürme
- Web uygulamasıyla aynı dönüştürme motoru
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
-H "x-api-key: mdai_…" \
-F file=@nist-cswp-29-csf-2.0.pdf
# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
-H "x-api-key: mdai_…" \
-H "content-type: application/json" \
-d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'
# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
-H "x-api-key: mdai_…"Belge dönüştürme API'si nasıl çalışır
Anahtardan Markdown'a üç adım. Her çağrı 60 saniyeye kadar bekler ve sonuçla yanıtlar; daha uzun veya çok dosyalı istekler bağlantıyı açık tutmak yerine 202 ve yoklanacak bir dönüştürme döndürür.
Bir API anahtarı oluşturun
Ayarlar → Geliştiriciler'de bir anahtar oluşturun (etkin bir abonelik gerekir) ve x-api-key başlığında gönderin.
POST /v1/convert/{name}
İlgili biçimin uç noktasına bir dosya, herkese açık bir URL veya satır içi metin gönderin. Çağrı başına bir girdi türü.
Markdown'ı kullanın
Çıktıyı yanıttan okuyun ya da bir 202'den sonra /v1/conversions/{id} üzerinde bekleyin.
Yanıt ve webhook'lar
Aşağıdaki yanıt, doğrulanmış DOCX ayrıştırıcı çıktısıyla API sözleşmesini örnekler; dönüştürme kimliği bir yer tutucudur. Tamamlanmış bir dönüştürme, maliyetini oluşturan kredilerle birlikte Markdown'ı döndürür. Bir 202, dönüştürmeye işaret eden bir Location başlığı taşır; ?wait= ile yoklayın, olaylarını akış olarak alın ya da bir webhook'un tamamlandığında size bildirmesine izin verin.
{
"id": "cnv_3f7c…",
"object": "conversion",
"name": "word",
"status": "completed",
"files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
"usage": { "credits_charged": 1 }
}POST https://your-app.example.com/webhooks
{
"type": "conversion.completed",
"data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}conversion.completed ve conversion.failed olaylarına abone olun; böylece yoklamak yerine uzun veya çok dosyalı bir dönüştürme tamamlandığı anda tepki verebilirsiniz. Teslimatlar Standard Webhooks başlıklarıyla imzalanır.
Belge ayrıştırma API'si ve Markdown dönüştürme API'si
Ekipler dosyalardan yapı çıkarmaya ihtiyaç duyduklarında bir belge ayrıştırma API'si, çıktı bir isteme veya bir kasaya yerleşmesi gerektiğinde ise bir Markdown dönüştürme API'si arar. Her iki ifade de bu hizmeti tanımlar. PDF'ten Markdown'a API'si ve URL'den Markdown'a API'si gibi biçime özgü sayfalar, o dönüştürücülere açılan bağlantılardır — aynı /v1/convert/{name} uç noktalarını kullanırlar.
Dönüştürme uç noktaları
POST /v1/convert/{name} — biçim başına bir uç nokta — bir dosya, URL veya metin alır ve Markdown, metin, HTML ya da sayfa başına çıktı döndürür.
API anahtarları
Hesap başına anahtarlar x-api-key başlığıyla gönderilir; böylece dönüştürme herhangi bir sunucuya veya betiğe uyar.
Birden çok dosya ve webhook'lar
Tek bir dönüştürme çağrısına birçok dosya gönderin ve tek bir dönüştürme alın; webhook'lar her conversion.completed veya conversion.failed olayını bildirir.
Markdown Render
POST /v1/convert/markdown/html veya /markdown/text, Markdown'ı kredi maliyeti olmadan tekrar HTML'e ya da düz metne çevirir.
Kullanım durumları
Ekipler bunu nereye bağlıyor
RAG veri alma
Parçalama ve gömmeden önce veri alma işlerinin içinde belgeleri dönüştürün.
Yapay zekâ ajanları
Ajanların, iş akışının ortasında rastgele dosyaları temiz metne dönüştürmesini sağlayın.
İçerik iş akışları
Markdown'ı otomatik olarak bir CMS'ye, dokümantasyon sitesine veya bilgi tabanına aktarın.
Dahili araçlar
Belge dönüştürmeyi hâlihazırda çalıştırdığınız ürünlere ve arka ofis araçlarına ekleyin.
Kimlik doğrulama, kullanım ve sınırlar
- API anahtarları hesabınıza aittir, yalnızca /v1 üzerinde çalışır ve x-api-key başlığıyla gönderilir — hesabın etkin bir Lite, Pro veya Max aboneliği olmalıdır
- Kullanım, web uygulamasıyla aynı kredilerden harcanır — standart ve OCR sayfaları sayfa başına 1 kredidir
- Plan hız sınırları Lite 20, Pro 40 ve Max 60 istek/dakikadır
- Her POST /v1/convert/{name} çağrısında Idempotency-Key; böylece bir yeniden deneme asla iki kez ücretlendirmez
- Her v1 uç noktası, istek alanı ve yanıtı, oluşturulan API referansında belgelenmiştir; hatalar, eşleşen hata kodu sayfasına çözümlenen bir type URI'siyle problem+json kullanır
Kılavuz
Tamamlanmayı ele alma
Bir belge dönüştürme API'si istemcisinde hem satır içi tamamlanmayı hem de eşzamansız işlemeyi ele alın. Başarılı bir gönderim tamamlanmış bir sonuç döndürebilir; HTTP 202 ise çalışmanın yanıttan sonra sürdüğünü gösterir. Dönüştürme kimliğini saklayın ve çıktıları okumadan önce belgelenen Location veya dönüştürme durumu uç noktasını kullanın. Yalnızca HTTP isteği başarılı oldu diye doğrudan varsayılan bir ilk çıktının içine indekslemeyin. Tamamlanmış bir dönüştürme de dosya düzeyinde hatalar içerebilir; bu yüzden çok kaynaklı bir istekte her dosyayı inceleyin. Döndürülen her sonucu uygulamanızın gönderdiği kaynağa bağlamak için yeterli bağlam saklayın. Bu, yavaş bir dönüştürmenin veya kısmi bir hatanın sonraki sisteminizde sessizce boş bir belgeye dönüşmesini önler.
İstek ve plan sınırları
Belge dönüştürme API'si hem isteklere hem de hesaplara sınırlar uygular. Bir multipart istek, toplam 100 MB sınırıyla 100 dosyaya kadar içerebilir. Bir URL isteği 20 kaynağa kadar kabul eder. Aboneliğiniz kredileri, depolamayı, dosya başına sınırları ve eşzamanlılığı ayrıca denetler. Bir Pro dosyası aboneliği tarafından izinli olabilirken tek bir multipart istek için çok büyük olabilir; bu durumda belgelenen parçalı yükleme akışını kullanın. Reddedilen bir isteği, en yüksek planın aktarım sınırlarını kaldırdığını varsayarak aşmaya çalışmayın. Hatayı okuyun ve kaynak boyutu için tasarlanmış girdi yöntemini kullanın.
Kaynak bağlamını koruma
Kendi kaynak kimliğinizi dönüştürme kimliğinin yanında saklayın; böylece bir sonuç onu gönderen işe kadar izlenebilir. API metadata alanı, çağıran tarafından sağlanan veriyi taşır; web sayfası başlıklarını, yazarları veya yayım tarihlerini çıkarma vaadi değildir. Uygulamanız bu bilgilere ihtiyaç duyuyorsa, bunları uygun ayrı bir adımda toplayın ve doğrulayın. Metnini okumadan önce bir çıktının satır içinde mi yoksa başvurulan bir artefakt üzerinden mi döndüğünü denetleyin; iş akışınızın denetim izine ihtiyacı olduğunda özgün belgeyi saklayın. Bir belge dönüştürme API'si içeriği sonraki aşama için hazırlar; içeriği kaynağıyla ilişkilendirmek ve ne kadar saklayacağına karar vermek ise uygulamanızın sorumluluğunda kalır.
Yayına almadan önce test
Belge dönüştürme API'sini üretim iş akışına entegre etmeden önce birden fazla başarılı küçük dosyayı deneyin. Eşzamansız tamamlanma gerektiren bir girdi, desteklenmeyen veya hasarlı bir dosya, karışık sonuçlu çok kaynaklı bir istek ve istemcinizin sınır hatası olarak ele alması gereken bir yanıt ekleyin. Kendi yeniden deneme mantığınızın kısmi bir hatadan sonra başarılı dosyaları yeniden göndermediğini doğrulayın. API kimlik bilgilerini sunucunuzda tutun ve tarayıcı koduna ya da herkese açık örneklere koymaktan kaçının. Sonraki getirmeyi veya model davranışını değerlendirmeden önce temsili kaynak türleri için gerçek Markdown'ı gözden geçirin. Aktarım hatalarını doğru ele alan bir istemci, yine de ortaya çıkan belgelerin yararlı olduğunu kanıtlamak için içerik düzeyinde denetimlere ihtiyaç duyar.
SSS
Belgeden Markdown'a API'si soruları
Belge dönüştürme API'sinde kimlik doğrulamayı nasıl yaparım?
Hesabınızda bir API anahtarı oluşturun ve `x-api-key` başlığında gönderin. Anahtarlar hesabınızla sınırlıdır.
Gerçek dönüştürme akışı nedir?
POST /v1/convert/{name} ile bir dosya, herkese açık bir URL veya metin gönderin. Belge bekleme penceresi içinde tamamlandığında Markdown aynı yanıtta döner; aksi hâlde 202 ve GET /v1/conversions/{id}?wait= ile üzerinde beklenecek bir dönüştürme alırsınız.
Dönüştürme eşzamanlı mı?
Varsayılan olarak bekleme penceresine kadar: POST /v1/convert/{name} bir sonucu bekler ve satır içinde döndürür; dönüştürme zamanında tamamlanamazsa bir Location ile 202 döndürür. Beklemeyi atlamak için Prefer: respond-async gönderin.
Hangi olaylara abone olabilirim?
Giden webhook'lar conversion.completed ve conversion.failed olaylarını destekler; böylece yoklamak yerine bir dönüştürme tamamlanır tamamlanmaz tepki verebilirsiniz.
Hangi planlar API erişimini içerir?
API erişimi ücretli planlarda sunulur. Güncel plan sınırları ve kredileri için fiyatlandırma sayfasına bakın.
API kullanımı nasıl faturalanır?
API dönüştürmeleri, web uygulamasıyla aynı kredi bakiyesinden harcanır. Standart ve OCR sayfaları sayfa başına 1 kredidir.
PDF'ten Markdown'a API'sini veya URL'den Markdown'a API'sini nerede bulurum?
Bu ifadeler ayrı ana bilgisayarlar değil, biçim açılış sayfalarıdır. PDF'ten Markdown'a API'si notlarını /pdf-to-markdown'da, URL'den Markdown'a API'si notlarını /url-to-markdown'da kullanın, sonra burada belgelenen aynı yükleme ve dönüştürme uç noktalarını çağırın.
API anahtarlarının istek sınırları nelerdir?
İstekler hesap başına sınırlandırılır: Lite 20, Pro 40 ve Max 60 istek/dakika.