API
API chuyển đổi tài liệu
API chuyển đổi tài liệu là một API HTTPS nhận file, URL hoặc HTML trong một lệnh gọi POST /v1/convert/{name} duy nhất và trả về Markdown.
Dùng thử ẩn danh nhận file tối đa 10 MB và 25 trang, với 3 lượt chuyển đổi mỗi IP mỗi giờ và 10 mỗi ngày. Lite bắt đầu từ $20 mỗi tháng với file tối đa 100 MB. Pro là $50 mỗi tháng; Max là $100 mỗi tháng.
- Một lệnh gọi POST /v1/convert/{name} cho mỗi file, URL hoặc văn bản nội tuyến
- Markdown trong phản hồi trong 60 giây, hoặc một chuyển đổi để thăm dò
- Cùng engine chuyển đổi như ứng dụng 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_…"API chuyển đổi tài liệu hoạt động thế nào
Ba bước từ khóa đến Markdown. Mỗi lệnh gọi chờ tối đa 60 giây và trả lời bằng kết quả; các yêu cầu dài hơn hoặc nhiều file trả về 202 kèm một chuyển đổi để thăm dò thay vì giữ kết nối.
Tạo khóa API
Tạo một khóa trong Cài đặt → Nhà phát triển (cần gói đăng ký đang hoạt động) và gửi nó trong header x-api-key.
POST /v1/convert/{name}
Gửi một file, một URL công khai hoặc văn bản nội tuyến đến endpoint của định dạng đó. Mỗi lệnh gọi chỉ một loại đầu vào.
Dùng Markdown
Đọc đầu ra từ phản hồi, hoặc chờ ở /v1/conversions/{id} sau một mã 202.
Phản hồi và webhook
Phản hồi dưới đây minh họa hợp đồng API bằng đầu ra DOCX đã kiểm chứng của bộ phân tích; mã định danh chuyển đổi là chỗ giữ chỗ. Một chuyển đổi đã xong trả về Markdown kèm số tín dụng đã tiêu. Một mã 202 mang header Location trỏ đến chuyển đổi; hãy thăm dò bằng ?wait=, phát luồng sự kiện của nó, hoặc để một webhook báo cho bạn khi nó kết thúc.
{
"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" }
}Hãy đăng ký conversion.completed và conversion.failed để có thể phản ứng ngay khi một chuyển đổi dài hoặc nhiều file kết thúc thay vì thăm dò. Các lần gửi được ký bằng header Standard Webhooks.
API phân tích tài liệu và Markdown API
Các nhóm tìm một API phân tích tài liệu khi cần lấy cấu trúc ra khỏi file, và một Markdown API khi đầu ra phải nằm trong prompt hoặc một kho lưu trữ. Cả hai cách nói đều mô tả dịch vụ này. Các trang riêng theo định dạng như api pdf sang markdown và api url sang markdown là điểm neo đến những công cụ chuyển đổi đó — chúng dùng cùng các endpoint /v1/convert/{name}.
Các endpoint chuyển đổi
POST /v1/convert/{name} — một endpoint cho mỗi định dạng — nhận file, URL hoặc văn bản và trả về Markdown, văn bản, HTML hoặc đầu ra từng trang.
Khóa API
Khóa theo tài khoản gửi qua header x-api-key, để chuyển đổi khớp với mọi máy chủ hay script.
Nhiều file và webhook
Gửi nhiều file trong một lệnh gọi chuyển đổi và nhận về một chuyển đổi; webhook báo cáo từng conversion.completed hoặc conversion.failed.
Markdown Render
POST /v1/convert/markdown/html hoặc /markdown/text biến Markdown trở lại HTML hoặc văn bản thuần mà không tốn tín dụng.
Trường hợp sử dụng
Nơi các nhóm tích hợp nó
Nạp dữ liệu cho RAG
Chuyển đổi tài liệu bên trong các job nạp dữ liệu trước khi chia đoạn và nhúng.
Agent AI
Để agent biến các file bất kỳ thành văn bản sạch ngay giữa pipeline.
Pipeline nội dung
Đưa Markdown vào CMS, site tài liệu hoặc cơ sở tri thức một cách tự động.
Công cụ nội bộ
Thêm chuyển đổi tài liệu vào các sản phẩm và công cụ nội bộ bạn đang vận hành.
Xác thực, mức sử dụng và giới hạn
- Khóa API thuộc về tài khoản của bạn, chỉ hoạt động trên /v1 và được gửi trong header x-api-key — tài khoản cần một gói đăng ký Lite, Pro hoặc Max đang hoạt động
- Mức sử dụng dùng chung tín dụng với ứng dụng web — trang tiêu chuẩn và trang OCR tốn 1 tín dụng mỗi trang
- Giới hạn tốc độ theo gói là Lite 20, Pro 40 và Max 60 yêu cầu mỗi phút
- Idempotency-Key trên mọi lệnh gọi POST /v1/convert/{name}, để một lần thử lại không bao giờ tính phí hai lần
- Mọi endpoint v1, trường yêu cầu và phản hồi đều được ghi trong tài liệu tham chiếu API được tạo tự động; các lỗi dùng problem+json với URI type trỏ đến trang mã lỗi tương ứng
Hướng dẫn
Xử lý hoàn tất
Hãy xử lý cả hoàn tất nội tuyến lẫn xử lý bất đồng bộ trong một client API chuyển đổi tài liệu. Một lần gửi thành công có thể trả về kết quả đã hoàn tất, còn HTTP 202 cho biết công việc vẫn tiếp diễn sau phản hồi. Hãy giữ mã định danh chuyển đổi và dùng endpoint Location hoặc trạng thái chuyển đổi được tài liệu hóa trước khi đọc đầu ra. Đừng đánh chỉ mục thẳng vào một đầu ra đầu tiên được cho là có chỉ vì yêu cầu HTTP đã thành công. Một chuyển đổi hoàn tất cũng có thể chứa lỗi ở cấp file, nên hãy kiểm tra từng file trong một yêu cầu nhiều nguồn. Hãy lưu đủ ngữ cảnh để nối mọi kết quả trả về với nguồn mà ứng dụng của bạn đã gửi. Cách này ngăn một chuyển đổi chậm hay một lỗi cục bộ âm thầm trở thành một tài liệu rỗng trong hệ thống hạ nguồn.
Giới hạn yêu cầu so với giới hạn gói
API chuyển đổi tài liệu áp dụng giới hạn cho cả yêu cầu lẫn tài khoản. Một yêu cầu multipart có thể gồm tối đa 100 file với giới hạn tổng 100 MB. Một yêu cầu URL nhận tối đa 20 nguồn. Gói đăng ký của bạn kiểm soát riêng tín dụng, lưu trữ, giới hạn mỗi file và độ đồng thời. Một file thuộc gói Pro có thể được gói cho phép nhưng lại quá lớn cho một yêu cầu multipart duy nhất; hãy dùng quy trình tải lên theo phần được tài liệu hóa cho trường hợp đó. Đừng lách một yêu cầu bị từ chối bằng cách cho rằng gói cao nhất xóa bỏ giới hạn vận chuyển. Hãy đọc lỗi và dùng phương thức đầu vào dành cho kích thước nguồn đó.
Giữ ngữ cảnh nguồn
Hãy giữ mã định danh nguồn của riêng bạn bên cạnh mã định danh chuyển đổi để một kết quả có thể được truy vết về job đã gửi nó. Trường metadata của API mang dữ liệu do bên gọi cung cấp; nó không phải lời hứa trích xuất tiêu đề trang, tác giả hay ngày công bố. Nếu ứng dụng của bạn cần những dữ kiện đó, hãy thu thập và kiểm chứng chúng trong một bước riêng phù hợp. Trước khi đọc văn bản của một đầu ra, hãy kiểm tra xem nó được trả về nội tuyến hay qua một sản phẩm được tham chiếu, và giữ tài liệu gốc khi quy trình của bạn cần dấu vết kiểm toán. Một API chuyển đổi tài liệu chuẩn bị nội dung cho giai đoạn kế tiếp, còn ứng dụng của bạn vẫn chịu trách nhiệm gắn nội dung đó với nguồn của nó và quyết định giữ bao lâu.
Kiểm thử trước khi ra mắt
Hãy thử nhiều hơn một file nhỏ thành công trước khi tích hợp API chuyển đổi tài liệu vào một quy trình sản xuất. Hãy đưa vào một đầu vào cần hoàn tất bất đồng bộ, một file không được hỗ trợ hoặc hỏng, một yêu cầu nhiều nguồn với kết quả hỗn hợp và một phản hồi mà client của bạn phải coi là lỗi giới hạn. Hãy xác minh rằng logic thử lại của bạn không gửi lại những file đã thành công sau một lỗi cục bộ. Hãy giữ thông tin xác thực API trên máy chủ và tránh đặt chúng trong mã trình duyệt hay ví dụ công khai. Hãy xem Markdown thật của những loại nguồn đại diện trước khi đánh giá truy xuất hay hành vi model hạ nguồn. Một client xử lý đúng lỗi vận chuyển vẫn cần các bước kiểm tra ở cấp nội dung để chứng minh những tài liệu thu được là hữu ích.
FAQ
Câu hỏi về API chuyển tài liệu sang Markdown
Tôi xác thực với API chuyển đổi tài liệu thế nào?
Hãy tạo một khóa API trong tài khoản của bạn và gửi nó trong header `x-api-key`. Khóa được giới hạn theo tài khoản của bạn.
Luồng chuyển đổi thực tế là gì?
POST /v1/convert/{name} với một file, một URL công khai hoặc văn bản. Markdown trả về trong cùng phản hồi khi tài liệu xong trong cửa sổ chờ; nếu không, bạn nhận 202 và một chuyển đổi để chờ bằng GET /v1/conversions/{id}?wait=.
Chuyển đổi có đồng bộ không?
Theo mặc định, tối đa đến cửa sổ chờ: POST /v1/convert/{name} chờ một kết quả và trả về nội tuyến, hoặc trả về 202 kèm Location khi chuyển đổi không thể xong kịp. Gửi Prefer: respond-async để bỏ qua việc chờ.
Tôi có thể đăng ký những sự kiện nào?
Webhook gửi ra hỗ trợ conversion.completed và conversion.failed, để bạn phản ứng ngay khi một chuyển đổi kết thúc thay vì thăm dò.
Những gói nào bao gồm truy cập API?
Truy cập API có trên các gói trả phí. Xem trang bảng giá để biết giới hạn và tín dụng hiện tại của từng gói.
Mức sử dụng API được tính phí thế nào?
Chuyển đổi qua API trừ vào cùng số dư tín dụng như ứng dụng web. Trang tiêu chuẩn và trang OCR tốn 1 tín dụng mỗi trang.
Tôi tìm api pdf sang markdown hay api url sang markdown ở đâu?
Những cụm đó là các trang theo định dạng, không phải máy chủ riêng. Hãy dùng ghi chú api pdf sang markdown trên /pdf-to-markdown và ghi chú api url sang markdown trên /url-to-markdown, rồi gọi cùng các endpoint tải lên và chuyển đổi được ghi ở đây.
Giới hạn tốc độ của khóa API là gì?
Các yêu cầu được giới hạn theo tài khoản: Lite 20, Pro 40 và Max 60 yêu cầu mỗi phút.
Chuyển file đầu tiên của bạn sang Markdown.
Dùng thử miễn phí — không cần đăng ký.