OCRRouter

เอกสารประกอบการใช้งาน API

คู่มืออธิบายแนวคิดหลัก สำหรับ endpoints และพารามิเตอร์ทั้งหมดสามารถดูได้ที่เอกสารอ้างอิง API

เริ่มต้นใช้งานฉบับย่อ

สร้าง API key แล้วเริ่มส่งไฟล์ได้ทันที บัญชีใหม่รับฟรี 50 เครดิตเริ่มต้น

curl https://api.ocrrouter.ai/v1/ocr \
  -H "Authorization: Bearer $OCRROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "file_url": "https://example.com/invoice.pdf",
    "format": "markdown"
  }'

คำขอ

POST https://api.ocrrouter.ai/v1/ocr พร้อม body แบบ JSON และ header Authorization: Bearer

modelstringID ของโมเดล เช่น mistral/mistral-ocr หรือ auto
file_urlstringURL สาธารณะของไฟล์ PDF หรือรูปภาพ เลือกใช้อย่างใดอย่างหนึ่งระหว่าง file_url, file_base64 หรือ file_id
file_base64stringไฟล์ในรูปแบบ base64 ขนาดไม่เกิน 20 MB
file_idstringID ที่ได้รับจาก POST /v1/files สำหรับไฟล์ขนาดใหญ่
formatstringmarkdown (ค่าเริ่มต้น), json, text, html, csv, docx หรือ xlsx
pagesstringช่วงหน้าเอกสาร เช่น 1-5,8 ค่าเริ่มต้นคือแปลงทุกหน้า
fallbacksstring[]ลำดับของ Model IDs ที่จะลองใช้งานสำรอง หากโมเดลแรกทำงานล้มเหลว
routestringเมื่อเลือก model เป็น auto: quality (ค่าเริ่มต้น), cheapest หรือ fastest
filenamestringชื่อไฟล์ทางเลือกสำหรับแสดงในบันทึกประวัติการใช้งานของคุณ

Endpoints อื่นๆ:

  • GET /v1/models แสดงรายการโมเดลทั้งหมด ราคา และสถานะความพร้อมใช้งาน โดยไม่ต้องใช้คีย์
  • POST /v1/files รับการอัปโหลดแบบ multipart ในฟิลด์ file และส่งคืน file_id ซึ่งใช้งานได้ภายใน 24 ชั่วโมง
  • GET /v1/requests/:id เรียกดูผลลัพธ์ย้อนหลัง ใส่ ?format= เพื่อแปลงเป็นรูปแบบอื่นที่ต้องการได้
  • GET /v1/credits ตรวจสอบยอดคงเหลือและปริมาณการใช้งานของคีย์นี้
  • POST /v1/keys/temporary ขอรับคีย์ชั่วคราวพร้อม 50 เครดิต ไม่ต้องลงทะเบียน จำกัดวันละ 1 ครั้ง

รูปแบบผลลัพธ์

markdown

เอกสารทั้งฉบับในรูปแบบ Markdown โดยตารางจะเป็นรูปแบบ GitHub-flavoured tables, สูตรคำนวณจะครอบด้วย $...$ และคั่นแต่ละหน้าด้วย <!-- page:N -->

json

โครงสร้างรูปแบบเดียวกันจากทุกโมเดล: แบ่งตามหน้า (pages) แต่ละหน้ามี typed blocks ประเภทของบล็อกประกอบด้วย heading, paragraph, list, table, formula, image, header และ footer ส่วน bbox, confidence และขนาดหน้ากระดาษจะเป็น null หากโมเดลนั้นไม่ได้ส่งข้อมูลมา ซึ่งเป็นค่าปกติสำหรับโมเดลที่ให้บริการอยู่ในปัจจุบัน

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "json","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"pages": [{"index": 1,"width": null,"height": null,"blocks": [{"type": "heading","level": 1,"text": "Invoice INV-2041","bbox": null,"confidence": null},{"type": "paragraph","text": "Acme Supply Co.\n14 Harbour Street, Sydney NSW 2…","bbox": null,"confidence": null},{"type": "table","rows": [["Item", "Qty", "Unit price", "Amount"],["A4 paper, 5 reams", "4", "$24.00", "$96.00"]],"markdown": "| Item | Qty | Unit price | Amount |\n|---|---|-…","bbox": null,"confidence": null}]}],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

text, html, csv, docx, xlsx

ผลลัพธ์ Markdown พร้อมออบเจกต์ output ที่บรรจุไฟล์: format, filename, mime_type, encoding และ data โดย text, html และ csv จะเข้ารหัสเป็น UTF-8 (encoding: "utf8") ส่วน docx และ xlsx จะเป็น base64 (encoding: "base64") สำหรับ csv และ xlsx จะเก็บข้อมูลตาราง (1 แผ่นงานต่อ 1 ตาราง) หรือข้อความทีละบรรทัดในกรณีที่ไม่มีตาราง นอกจากนี้ยังสามารถใช้คำว่า txt แทน text ได้

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "docx","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"markdown": "<!-- page:1 -->\n# Invoice INV-2041\n…","pages": [{ "index": 1, "markdown": "# Invoice INV-2041\n…" }],"output": {"format": "docx","filename": "invoice.docx","mime_type": "application/vnd.openxmlformats-officedocument.w…","encoding": "base64","data": "UEsDBBQAAAAIA…"},"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

การเราต์และ fallbacks

ตั้งค่า model เป็น auto แล้วระบบจะเลือกโมเดลที่เหมาะสมที่สุดสำหรับแต่ละเอกสาร ใช้ route เพื่อระบุเกณฑ์ที่สำคัญ: cheapest (ประหยัดที่สุด), fastest (เร็วที่สุด) หรือ quality (คุณภาพสูงสุด)

กำหนด fallbacks เพื่อให้ระบบทำงานต่อเนื่องได้ไม่สะดุด หากโมเดลแรกเกิดข้อผิดพลาดหรือติดขีดจำกัดอัตราการเรียกใช้ โมเดลสำรองถัดไปจะทำงานทันที ข้อมูลตอบกลับจะระบุว่าโมเดลใดเป็นผู้ประมวลผล และคุณจะจ่ายเฉพาะค่าบริการของโมเดลนั้น

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

เครดิต

แต่ละโมเดลคิดราคาเป็นเครดิตต่อหน้า เงิน $1 ซื้อได้ 1,000 เครดิตและไม่มีวันหมดอายุ ทุกคำตอบจะส่งข้อมูล usage.credits กลับมาด้วย

  • คำขอที่ล้มเหลวและผลลัพธ์ที่ว่างเปล่าจะไม่คิดค่าบริการ
  • การส่งไฟล์เดิมไปยังโมเดลเดิมซ้ำจะดึงข้อมูลจากแคชมาแสดงฟรี
  • API key แต่ละชุดสามารถตั้งวงเงินจำกัดเครดิตแยกกันได้

ข้อผิดพลาด

400คำขอไม่ถูกต้องหรือประเภทไฟล์ไม่รองรับ
401ไม่มี API key หรือคีย์ถูกเพิกถอนแล้ว
402เครดิตไม่เพียงพอ หรือคีย์ใช้งานถึงขีดจำกัดเครดิตแล้ว
413ไฟล์มีขนาดใหญ่เกินขีดจำกัดของโมเดลนี้
429ส่งคำขอถี่เกินไป โปรดลองใหม่หลังจากเวลาที่ระบุใน header Retry-After
502ทุกโมเดลในลำดับ fallback ทำงานล้มเหลว คุณจะไม่ถูกเรียกเก็บเงิน
503โมเดลที่คุณเรียกใช้ยังไม่พร้อมให้บริการในขณะนี้

Agents, MCP และ CLI

Coding agents สามารถใช้งาน OCRRouter ได้ทันทีโดยไม่ต้องลงทะเบียน โดย CLI และ MCP server จะขอรับคีย์ชั่วคราวพร้อม 50 เครดิตในการใช้งานครั้งแรก และบันทึกไว้ที่ ~/.ocrrouter/config.json หรือตั้งค่า OCRROUTER_API_KEY เพื่อใช้คีย์ของคุณเอง

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

สรุปข้อมูลหน้านี้ในรูปแบบที่เครื่องประมวลผลได้อยู่ที่ /llms.txt

คำถามที่พบบ่อย