API
API konversi dokumen
API konversi dokumen adalah API HTTPS yang menerima file, URL, atau HTML dalam satu panggilan POST /v1/convert/{name} dan mengembalikan Markdown.
Uji anonim menerima file hingga 10 MB dan 25 halaman, dengan 3 konversi per IP per jam dan 10 per hari. Lite mulai dari $20 per bulan dengan file hingga 100 MB. Pro berharga $50 per bulan; Max berharga $100 per bulan.
- Satu panggilan POST /v1/convert/{name} per file, URL, atau teks inline
- Markdown di respons dalam 60 detik, atau konversi yang bisa di-polling
- Mesin konversi yang sama dengan aplikasi web
# 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_…"Cara kerja API konversi dokumen
Tiga langkah dari kunci hingga Markdown. Setiap panggilan menunggu hingga 60 detik dan membalas dengan hasilnya; permintaan yang lebih lama atau berisi banyak file mengembalikan 202 dan konversi untuk di-polling alih-alih menahan koneksi tetap terbuka.
Buat kunci API
Buat kunci di Pengaturan → Pengembang (butuh langganan aktif) dan kirimkan di header x-api-key.
POST /v1/convert/{name}
Kirim file, URL publik, atau teks inline ke endpoint format tersebut. Satu jenis masukan per panggilan.
Pakai Markdown-nya
Baca keluaran dari respons, atau tunggu /v1/conversions/{id} setelah 202.
Respons dan webhook
Respons di bawah menggambarkan kontrak API dengan memakai keluaran parser DOCX yang terverifikasi; pengenal konversinya adalah placeholder. Konversi yang selesai mengembalikan Markdown beserta kredit yang dihabiskannya. Kode 202 membawa header Location ke konversi tersebut; polling dengan ?wait=, streaming peristiwanya, atau biarkan webhook memberi tahu Anda saat selesai.
{
"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" }
}Berlangganan conversion.completed dan conversion.failed agar Anda bisa bereaksi tepat saat konversi panjang atau multi-file selesai, alih-alih melakukan polling. Pengirimannya ditandatangani dengan header Standard Webhooks.
API penguraian dokumen dan API Markdown
Tim mencari API penguraian dokumen saat perlu mengekstrak struktur dari file, dan API konversi Markdown saat keluarannya harus berakhir di prompt atau penyimpanan. Kedua ungkapan itu menggambarkan layanan ini. Halaman khusus format, seperti api PDF ke markdown dan api URL ke markdown, adalah jangkar ke konverter tersebut: keduanya memakai endpoint /v1/convert/{name} yang sama.
Endpoint konversi
POST /v1/convert/{name} —satu endpoint per format— menerima file, URL, atau teks dan mengembalikan Markdown, teks, HTML, atau keluaran per halaman.
Kunci API
Kunci per akun yang dikirim lewat header x-api-key, sehingga konversi bisa dipasang di server atau skrip mana pun.
Banyak file dan webhook
Kirim banyak file ke satu panggilan konversi dan terima satu konversi; webhook memberi tahu setiap conversion.completed atau conversion.failed.
Markdown Render
POST /v1/convert/markdown/html atau /markdown/text mengubah Markdown kembali ke HTML atau teks biasa tanpa biaya kredit.
Kasus penggunaan
Di mana tim mengintegrasikannya
Pengambilan data untuk RAG
Konversi dokumen di dalam pekerjaan pengambilan data sebelum memotong dan menyematkannya.
Agen AI
Biarkan agen mengubah file sembarang menjadi teks bersih di tengah proses.
Alur konten
Masukkan Markdown ke CMS, situs dokumentasi, atau basis pengetahuan secara otomatis.
Alat internal
Tambahkan konversi dokumen ke produk dan alat internal yang sudah Anda pakai.
Autentikasi, penggunaan, dan batas
- Kunci API milik akun Anda, hanya berfungsi di /v1 dan dikirim lewat header x-api-key; akunnya perlu langganan Lite, Pro, atau Max yang aktif
- Penggunaannya menghabiskan kredit yang sama dengan aplikasi web: halaman standar dan OCR biayanya 1 kredit per halaman
- Batas permintaan per paket adalah Lite 20, Pro 40, dan Max 60 permintaan per menit
- Idempotency-Key pada setiap panggilan POST /v1/convert/{name}, agar percobaan ulang tidak pernah menagih dua kali
- Semua endpoint v1, bidang permintaan, dan respons didokumentasikan di referensi API yang dihasilkan; kegagalan memakai problem+json dengan URI type yang mengarah ke halaman kode kesalahan terkait
Panduan
Menangani penyelesaian
Tangani penyelesaian inline maupun pemrosesan asinkron di dalam klien API konversi dokumen. Pengiriman yang berhasil bisa mengembalikan hasil yang sudah selesai, sedangkan HTTP 202 menandakan pekerjaan berlanjut setelah respons. Simpan pengenal konversi dan pakai endpoint Location atau status konversi yang terdokumentasi sebelum membaca keluarannya. Jangan mengindeks langsung ke dugaan keluaran pertama hanya karena permintaan HTTP-nya berhasil. Konversi yang selesai juga bisa memuat kegagalan tingkat file, jadi periksa setiap file dalam permintaan dengan banyak sumber. Simpan konteks yang cukup untuk menghubungkan setiap hasil yang dikembalikan dengan sumber yang dikirim aplikasi Anda. Dengan begitu Anda mencegah konversi yang lambat atau kegagalan sebagian diam-diam menjadi dokumen kosong di dalam sistem Anda.
Batas permintaan vs batas paket
API konversi dokumen menerapkan batas pada permintaan sekaligus akun. Permintaan multipart bisa memuat hingga 100 file dengan batas gabungan 100 MB. Permintaan lewat URL menerima hingga 20 sumber. Langganan Anda mengendalikan kredit, penyimpanan, batas per file, dan konkurensi secara terpisah. File yang layak untuk paket Pro bisa saja diizinkan oleh langganannya sekaligus terlalu besar untuk satu permintaan multipart; untuk kasus itu gunakan alur unggahan bertahap yang terdokumentasi. Jangan mengakali permintaan yang ditolak dengan menganggap paket yang lebih tinggi menghapus batas transportasi. Baca kesalahannya dan gunakan metode masukan yang dimaksudkan untuk ukuran sumber tersebut.
Mempertahankan konteks sumber
Simpan pengenal sumber Anda sendiri di samping pengenal konversi, agar suatu hasil bisa dilacak hingga pekerjaan yang mengirimnya. Bidang metadata API membawa data yang disediakan pemanggil; ini bukan janji untuk mengekstrak judul halaman, penulis, atau tanggal terbit. Jika aplikasi Anda memerlukan data itu, kumpulkan dan verifikasi di langkah terpisah yang sesuai. Sebelum membaca teksnya, periksa apakah keluaran dikembalikan secara inline atau lewat artefak yang direferensikan, dan simpan dokumen aslinya saat alur Anda memerlukan jejak audit. API konversi dokumen menyiapkan konten untuk tahap berikutnya, sedangkan aplikasi Anda tetap bertanggung jawab mengaitkan konten itu dengan asalnya dan memutuskan berapa lama menyimpannya.
Menguji sebelum peluncuran
Uji lebih dari satu file kecil yang benar sebelum mengintegrasikan API konversi dokumen ke alur produksi. Sertakan masukan yang memerlukan penyelesaian asinkron, file yang tidak didukung atau rusak, permintaan dengan banyak sumber dan hasil campuran, serta respons yang harus ditangani klien Anda sebagai kesalahan batas. Pastikan logika percobaan ulang Anda sendiri tidak mengirim ulang file yang benar setelah kegagalan sebagian. Simpan kredensial API di server Anda dan hindari menaruhnya di kode browser atau contoh publik. Tinjau Markdown sebenarnya dari jenis sumber yang representatif sebelum menilai pengambilan atau perilaku model setelahnya. Klien yang menangani kesalahan transportasi dengan baik tetap memerlukan pemeriksaan tingkat konten untuk membuktikan dokumen yang dihasilkan berguna.
FAQ
Pertanyaan tentang API dokumen ke Markdown
Bagaimana cara saya mengautentikasi di API konversi dokumen?
Buat kunci API di akun Anda dan kirimkan pada header `x-api-key`. Kunci dibatasi untuk akun Anda.
Bagaimana alur konversi sebenarnya?
POST /v1/convert/{name} dengan file, URL publik, atau teks. Markdown kembali di respons yang sama saat dokumen selesai dalam jendela tunggu; jika tidak, Anda menerima 202 dan konversi yang bisa ditunggu dengan GET /v1/conversions/{id}?wait=.
Apakah konversinya sinkron?
Secara default, hingga jendela tunggu: POST /v1/convert/{name} menunggu hasil dan mengembalikannya inline, atau mengembalikan 202 dengan Location saat konversi tidak bisa selesai tepat waktu. Kirim Prefer: respond-async untuk melewati penantian.
Peristiwa apa saja yang bisa saya langgani?
Webhook keluar mendukung conversion.completed dan conversion.failed, sehingga Anda bereaksi begitu konversi selesai alih-alih melakukan polling.
Paket mana yang menyertakan akses API?
Akses API tersedia di paket berbayar. Lihat halaman harga untuk batas dan kredit terkini tiap paket.
Bagaimana penggunaan API ditagih?
Konversi lewat API diambil dari saldo kredit yang sama dengan aplikasi web. Halaman standar dan OCR biayanya 1 kredit per halaman.
Di mana saya menemukan api PDF ke markdown atau api URL ke markdown?
Ungkapan itu adalah halaman format, bukan host tambahan. Pakai catatan api PDF ke markdown di /pdf-to-markdown dan catatan api URL ke markdown di /url-to-markdown, lalu panggil endpoint unggahan dan konversi yang sama seperti yang didokumentasikan di sini.
Apa batas permintaan untuk kunci API?
Permintaan dibatasi per akun: Lite 20, Pro 40, dan Max 60 permintaan per menit.
Konversi file pertama Anda ke Markdown.
Gratis untuk dicoba — tanpa perlu mendaftar.