BetaPDF Developer API

Bắt đầu nhanh

Lấy API key, gửi PDF hoặc ảnh chụp, nhận Markdown. Ba dòng lệnh.

# Accepts PDF (≤10 pages) or image (jpg/png/webp, ≤20MB)
curl -X POST https://betapdf.com/api/v1/parse \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@input.pdf"
# Or:  -F "file=@photo.jpg"

Xác thực

Mọi request cần Bearer token. API mở cho gói Pro ($9.99/tháng, 1.000 trang) và Business ($29.99/tháng, 5.000 trang) — gói Free KHÔNG tạo được key. Lấy key tại /account/api-keys sau khi nâng cấp. Plaintext chỉ hiện MỘT lần khi tạo — lưu như mật khẩu.

Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

POST /v1/parse — Đồng bộ

Dùng cho PDF ≤ 10 trang hoặc 1 ảnh (jpg/png/webp). Block cho đến khi xong (~7-30s). Trả toàn bộ kết quả inline. PDF lớn hơn dùng endpoint async.

# Accepts PDF (≤10 pages) or image (jpg/png/webp, ≤20MB)
curl -X POST https://betapdf.com/api/v1/parse \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@input.pdf"
# Or:  -F "file=@photo.jpg"

POST /v1/parse/jobs — Bất đồng bộ

Trả 202 + job_id ngay. Dùng cho PDF lên đến 50 trang (ảnh cũng dùng được nhưng sync nhanh hơn). Poll GET /v1/parse/jobs/{id}; lấy kết quả GET /v1/parse/jobs/{id}/result khi status=completed.

# Accepts PDF (≤50 pages) or image (jpg/png/webp, ≤20MB)
curl -X POST https://betapdf.com/api/v1/parse/jobs \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@input.pdf"

curl https://betapdf.com/api/v1/parse/jobs/JOB_ID \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"

curl https://betapdf.com/api/v1/parse/jobs/JOB_ID/result \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"

GET /v1/usage

Xem số trang đã dùng tháng này và quota còn lại.

curl https://betapdf.com/api/v1/usage \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"

POST /v1/classify — Phân loại danh mục (tiếng Việt)

Phân loại title sản phẩm tiếng Việt thành category_id (46 nhóm lá). JSON in/out — không cần upload file. Tối đa 256 title/request. Mỗi kết quả có confidence và level: leaf (tin cậy cao), root (trung bình — lùi về nhóm cha), hoặc null (thấp — category_id là null). Tính 1 credit / 10.000 title.

# Phân loại title sản phẩm tiếng Việt → category_id (46 nhóm)
curl -X POST https://betapdf.com/api/v1/classify \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"titles":["Nước hoa nữ Chanel Coco 50ml","Tã dán Bobby M 64 miếng"]}'

{
  "results": [
    { "title": "Nước hoa nữ Chanel Coco 50ml",
      "slug": "nuoc-hoa", "category_id": "222",
      "confidence": 0.96, "level": "leaf" },
    { "title": "Tã dán Bobby M 64 miếng",
      "slug": "ta-bim", "category_id": "226",
      "confidence": 1.00, "level": "leaf" }
  ]
}
// level: leaf (conf cao) | root (trung bình, lùi nhóm cha) | null (thấp, category_id=null)

POST /v1/classify/jobs — Async (batch lớn)

Gửi tới 100.000 title trong 1 job — trả 202 + job_id ngay. Poll GET /v1/classify/jobs/{id} xem {status, total, done}; lấy GET /v1/classify/jobs/{id}/result khi status=done. Job giữ 6 giờ. Dùng thay /classify khi có hàng nghìn title (vd backfill toàn bộ catalog).

# Batch lớn (tới 100.000 title/job) → trả 202 + job_id
curl -X POST https://betapdf.com/api/v1/classify/jobs \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"titles":["Nước hoa nữ Chanel Coco 50ml", "... (nhiều nghìn title)"]}'

curl https://betapdf.com/api/v1/classify/jobs/JOB_ID \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"
# → {"status":"processing"|"done"|"failed", "total":50000, "done":32768}

curl https://betapdf.com/api/v1/classify/jobs/JOB_ID/result \
  -H "Authorization: Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"
# → {"results":[{title,slug,category_id,confidence,level}, ...]}   (409 nếu chưa xong)

GET /v1/categories

Trả toàn bộ taxonomy model có thể xuất — 46 nhóm lá + 12 gốc, mỗi cái có slug và category_id. Không cần key.

# Toàn bộ taxonomy (46 leaf + 12 root) — KHÔNG cần key
curl https://betapdf.com/api/v1/categories
# → { "leaves": [{slug, category_id, root_id, name}, ...], "roots": [{category_id, name}, ...] }

Shape Response

{
  "markdown": "# Heading\n\nParagraph text...\n",
  "chunks": [
    {
      "id": "a1b6...",
      "type": "title",      // title | paragraph | table | figure | formula
      "markdown": "Heading",
      "grounding": {
        "page": 0,
        "box":            {"left": 386, "top": 51, "right": 687, "bottom": 82},
        "box_normalized": {"left": 0.386, "top": 0.051, "right": 0.687, "bottom": 0.082}
      }
    },
    {
      "id": "f2c3...",
      "type": "table",
      "markdown": "<table><tr><td>STT</td><td>Item</td></tr>...</table>",
      "grounding": {
        "page": 1,
        "box":            {"left": 23, "top": 250, "right": 977, "bottom": 720},
        "box_normalized": {"left": 0.023, "top": 0.25, "right": 0.977, "bottom": 0.72}
      }
    }
  ],
  "metadata": {
    "filename": "input.pdf",
    "page_count": 9,
    "duration_ms": 22458,
    "credits_used": 9,
    "job_id": "994dc1f9-d20c-4384-8e3c-f99b8e59c524",
    "version": "2026.05",
    "pages": [
      { "page_no": 0, "width": 595.3, "height": 841.9, "unit": "pdf_point",
        "bbox_width": 1000.0, "bbox_height": 1000.0 }
    ]
  }
}

Taxonomy danh mục (46 lá, 12 gốc)

Mọi kết quả classify trả về một trong các slug / category_id dưới đây. Confidence trung bình → lùi về category_id gốc (100–111); confidence rất thấp → category_id null.

Code mẫu

Python

import httpx

with httpx.Client(timeout=90) as c, open("input.pdf", "rb") as f:
    r = c.post(
        "https://betapdf.com/api/v1/parse",
        headers={"Authorization": "Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
        files={"file": ("input.pdf", f, "application/pdf")},
    )
data = r.json()
print(data["markdown"])
for chunk in data["chunks"]:
    print(chunk["type"], chunk["grounding"]["page"], chunk["markdown"][:60])

Python (async)

import httpx, time

KEY = "beta_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# 1. submit
with httpx.Client(timeout=60) as c, open("input.pdf", "rb") as f:
    r = c.post(
        "https://betapdf.com/api/v1/parse/jobs",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": ("input.pdf", f, "application/pdf")},
    )
job_id = r.json()["job_id"]

# 2. poll
while True:
    s = httpx.get(
        f"https://betapdf.com/api/v1/parse/jobs/{job_id}",
        headers={"Authorization": f"Bearer {KEY}"},
    ).json()
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(3)

# 3. result
if s["status"] == "completed":
    r = httpx.get(
        f"https://betapdf.com/api/v1/parse/jobs/{job_id}/result",
        headers={"Authorization": f"Bearer {KEY}"},
    )
    print(r.json()["markdown"])

Node.js / TypeScript

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("input.pdf")]), "input.pdf");

const r = await fetch("https://betapdf.com/api/v1/parse", {
  method: "POST",
  headers: { "Authorization": "Bearer beta_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
  body: form,
});
const data = await r.json();
console.log(data.markdown);
data.chunks.forEach(c => console.log(c.type, c.grounding?.page, c.markdown.slice(0, 60)));

Lưu trữ & Tải lại kết quả

File ZIP kết quả được giữ trên server để bạn tải lại trong khoảng thời gian theo gói: Free 6 giờ, Pro 7 ngày, Business 14 ngày. Lấy lại bằng GET /v1/parse/jobs/{id}/download (trả 410 EXPIRED khi quá hạn). DELETE /v1/parse/jobs/{id} cho phép tự xóa theo yêu cầu GDPR. Upload từ web ẩn danh luôn dùng cửa sổ 6 giờ.

Quota & Giới hạn

Pro: 1.000 trang/tháng. Business: 5.000 trang/tháng. Cả hai gói: 30 request/phút mỗi key. PDF tối đa 100MB (sync ≤10 trang, async ≤50 trang); ảnh (jpg/png/webp) tối đa 20MB, tính 1 trang. Hard cap — v1 không tính overage.

Mã lỗi

Vì sao BetaPDF

• ⚡ Nhanh hơn 15× so với phiên bản cũ. ~22-30s cho PDF tiếng Việt 9 trang (vLLM trên GB10).
• 🇻🇳 Giữ dấu tiếng Việt 99.7% trên cả PDF số và PDF scan 300 DPI.
• 💰 Từ $9.99/tháng (Pro) hoặc $29.99/tháng (Business). So với Landing AI ADE Team $250/tháng.
• 🔁 Hỗ trợ cả sync và async. Cùng shape JSON (markdown + chunks + metadata).