Конвертируйте PDF в Markdown из своего кода
Подключите pdf2markdown к бэкенду, RAG-пайплайну или автоматизации. Тот же конвертер и те же лимиты, что и в веб-версии.
Быстрый старт
- 1Создайте API-ключ на странице API-ключей.
- 2Загрузите PDF: POST /convert/upload вернёт id конвертации.
- 3Опрашивайте GET /convert/status/{id} каждые 2–5 секунд, пока статус не станет done или failed.
- 4Скачайте результат: GET /convert/download/{id} вернёт .md (или .zip, если в PDF есть изображения).
Примеры
# 1. Upload
curl -s -X POST https://pdf2markdown.ru/api/v1/convert/upload \
-H "X-API-Key: $PDF2MARKDOWN_API_KEY" \
-F "file=@report.pdf;type=application/pdf" -F "format=md"
# → {"id":"<id>","status":"queued"}
# 2. Poll until "done"
curl -s https://pdf2markdown.ru/api/v1/convert/status/<id> -H "X-API-Key: $PDF2MARKDOWN_API_KEY"
# 3. Download (.md, or .zip when the PDF has images)
curl -s -OJ https://pdf2markdown.ru/api/v1/convert/download/<id> -H "X-API-Key: $PDF2MARKDOWN_API_KEY"Методы
Base URL: https://pdf2markdown.ru/api/v1
| Метод | Путь | Описание |
|---|---|---|
POST | /convert/upload | Загрузка PDF (multipart: file, format=md). Возвращает {id, status}. |
GET | /convert/status/{id} | Статус конвертации: queued, processing, done или failed (с текстом ошибки). |
GET | /convert/download/{id} | Файл результата: text/markdown или application/zip. |
GET | /convert/history | Ваши конвертации, ?page=&size=&status=. |
GET | /convert/limits | Ваш тариф, использованный лимит и ограничения. |
GET | /convert/batch/{batch_id} | Статус пакета и все результаты одним .zip. |
DELETE | /convert/{id} | Удалить конвертацию и её файлы. |
Авторизация
Передавайте ключ в заголовке X-API-Key (или Authorization: Bearer mk_…). Ключ работает только для /convert/*: им нельзя изменить аккаунт, оплату или другие ключи.
Лимиты
Запросы через API расходуют ваш тариф: месячный лимит и размер файла общие с веб-версией. Rate limit считается на ключ: 30 запросов в минуту на загрузку, скачивание и удаление, 120 в минуту на статус.
Форматы: Markdown и JSON для RAG
Каждая конвертация доступна в Markdown и в структурированном JSON: блоки с типом, страницей и путём по заголовкам (section), таблицы строками, изображения с подписями, формулы в LaTeX и готовые секции для чанкинга. Скачивание с ?format=json.
JSON доступен на тарифах Lite и Pro. Markdown — на всех.
{
"schema_version": 1,
"source": { "filename": "report.pdf", "pages": 12 },
"stats": { "blocks": 148, "tables": 3, "images": 2, "formulas": 5, "ocr_pages": [] },
"blocks": [
{ "type": "heading", "level": 1, "page": 1, "section": ["Annual report"],
"text": "Annual report", "markdown": "# Annual report" },
{ "type": "table", "page": 4, "section": ["Annual report", "Revenue"],
"rows": [["Region", "Q1"], ["Moscow", "120"]], "caption": "Table 2. Revenue",
"markdown": "| Region | Q1 |\n|---|---|\n| Moscow | 120 |" },
{ "type": "formula", "page": 7, "latex": "E = m c^{2}", "markdown": "$\nE = m c^{2}\n$" },
{ "type": "image", "page": 9, "image": "assets/page9-img1.png",
"caption": "Figure 3. Architecture" }
],
"sections": [
{ "title": "Revenue", "level": 2, "path": ["Annual report"],
"page_start": 4, "page_end": 5, "markdown": "## Revenue\n\n| Region | Q1 | ..." }
]
}Вебхуки (Pro)
Передайте callback_url при загрузке — мы пришлём POST, когда конвертация завершится. Для пакетов передайте ещё batch_id и batch_size: придёт одно событие batch.completed, когда готовы все файлы. Каждый запрос подписан: проверяйте X-Pdf2Markdown-Signature секретом вебхуков (страница API-ключей).
# 1. Upload with a callback (Pro). For batches add batch_id and batch_size.
curl -X POST https://pdf2markdown.ru/api/v1/convert/upload \
-H "X-API-Key: $PDF2MARKDOWN_API_KEY" \
-F "file=@report.pdf;type=application/pdf" \
-F "callback_url=https://your-app.example.com/pdf2markdown-webhook"
# 2. We POST: {"event": "conversion.completed", "conversion": {"id", "status", "download_url", ...}}
# Headers: X-Pdf2Markdown-Event, X-Pdf2Markdown-Timestamp, X-Pdf2Markdown-Signature: sha256=<hex>
# 3. Verify the signature (Python):
import hashlib, hmac, time
def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
if abs(time.time() - int(timestamp)) > 300: # reject replays
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256)
return hmac.compare_digest("sha256=" + expected.hexdigest(), signature)Сканы (OCR, Pro)
На Pro страницы без текстового слоя распознаются автоматически (русский и английский). На остальных тарифах такие файлы завершаются ошибкой scan_needs_ocr.
Ошибки
Ошибка всегда выглядит как {"detail": "…", "code": "…"}. Ориентируйтесь на code, а не на detail.
401 unauthorized 402 conversion_limit_reached · file_too_large 404 not_found 409 not_ready 410 expired 402 webhooks_not_allowed · batch_not_allowed 415 invalid_file_type 429 rate_limited (Retry-After)
Берегите ключ
- • Вызывайте API только со своего сервера: не встраивайте ключ во фронтенд или мобильное приложение.
- • Храните ключ в переменной окружения или менеджере секретов, а не в репозитории.
- • Заводите отдельный ключ на каждую интеграцию и сразу отзывайте ключ, если он мог утечь.
Все инструменты для PDF
API для разработчиков
Конвертация из вашего бэкенда, бота или RAG-пайплайна.