API Reference

OCR v3 — Async

สร้างงานแล้วได้ jobId ทันที ประมวลผลพื้นหลัง สูงสุด 1,000 หน้า / ไฟล์ 10 MBaction เป็น transcribe หรือ extractor

ต้องการ bounding box?

extractor ของ OCR v3 ไม่คืนตำแหน่งบนเอกสาร ใช้ Key Extraction v3
MethodPathรายละเอียด
POST/api/v3/ocrสร้างงานจาก JSON (URL หรือ base64) · 202
POST/api/v3/uploadสร้างงานจากไฟล์ multipart · 202
GET/api/v3/ocr/status/:jobIdสถานะ
GET/api/v3/ocr/result/:jobIdผลเมื่อเสร็จ · ?page=&limit= แบ่งหน้า (limit 1–100)
POST/api/v3/ocr/cancel/:jobIdยกเลิก
DELETE/api/v3/ocr/:jobIdลบงาน

สร้างงาน

POSThttps://backend.aksonocr.com/api/v3/ocr
json
{
"action": "transcribe",
"model": "AksonOCR-1.0",
"document": {
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
"webhookUrl": "https://example.com/hooks/ocr"
}
ฟิลด์จำเป็นรายละเอียด
documentใช่type: image_url | document_url (URL หรือ data URI base64)
modelใช่AksonOCR-1.0 | AksonOCR-preview | AksonOCR-handwriting
actionใช่transcribe หรือ extractor
modeไม่normal (ค่าเริ่มต้น)
pagesไม่PDF: เลขหน้าที่ต้องการ เริ่มที่ 0 เช่น [0, 1]
wordConfidenceไม่true = เพิ่ม pages[].words พร้อม confidence รายคำ
webhookUrlไม่HTTPS เมื่องานเข้าสู่สถานะปลายทาง
customFieldsextractorอาร์เรย์ { key, description, example }
templateIdextractorเทมเพลตจาก Dashboard

Response 202

json
{
"jobId": "1d0782b4-8c75-49e6-b646-4cfa0f16acd1",
"status": "pending",
"action": "transcribe",
"mode": "normal",
"model": "AksonOCR-1.0",
"createdAt": "2026-11-17T09:11:09.318Z"
}

Poll และดึงผล

GEThttps://backend.aksonocr.com/api/v3/ocr/status/{jobId}

สถานะ pending → processing → completed (หรือ failed / cancelled) หยุด poll เมื่อเป็นสถานะปลายทาง แล้วเรียก /api/v3/ocr/result/{jobId} ตัวอย่างผลจริงอยู่ที่ ตัวอย่าง Full Page OCR

bash
curl -sS "https://backend.aksonocr.com/api/v3/ocr/status/$JOB_ID" \
-H 'X-API-Key: <YOUR_API_KEY>'
curl -sS "https://backend.aksonocr.com/api/v3/ocr/result/$JOB_ID" \
-H 'X-API-Key: <YOUR_API_KEY>'

action: extractor

คืน pages[].structuredData ตาม customFields หรือ templateId ไม่มี bbox — ดู Key Extraction v3 ถ้าต้องการกรอบบนหน้า

json
{
"action": "extractor",
"model": "AksonOCR-1.0",
"document": { "type": "image_url", "image_url": "https://example.com/invoice.jpg" },
"customFields": [
{ "key": "เลขที่ใบแจ้งหนี้", "description": "Invoice number" },
{ "key": "ยอดรวม", "description": "Grand total including VAT" }
]
}

Webhook

ถ้าส่ง webhookUrl ระบบจะ POST JSON ไปที่ URL นั้นเมื่องาน completed หรือ failed (งานที่ cancel ไม่ส่ง) ถ้า endpoint ตอบไม่สำเร็จจะลองใหม่ทุก 5 นาที สูงสุด 5 ครั้ง ตอบ 2xx ภายใน 30 วินาที แล้วค่อยประมวลผลต่อแบบ background

http
POST /hooks/ocr HTTP/1.1
Content-Type: application/json
X-Webhook-Event: ocr_job.completed
X-OCR-Job-Id: 1d0782b4-8c75-49e6-b646-4cfa0f16acd1
X-Webhook-Signature: sha256=…
json
{
"event": "ocr_job.completed",
"timestamp": "2026-11-17T09:11:13.002Z",
"data": {
"job_id": "1d0782b4-8c75-49e6-b646-4cfa0f16acd1",
"action": "transcribe",
"status": "completed",
"mode": "normal",
"model": "AksonOCR-1.0",
"total_pages": 1,
"processed_pages": 1,
"credit_cost": 1,
"result_url": "https://storage.googleapis.com/…",
"result_url_expires_at": "2026-11-17T10:11:13.000Z",
"error": null,
"created_at": "2026-11-17T09:11:09.318Z",
"completed_at": "2026-11-17T09:11:12.940Z"
}
}
ฟิลด์รายละเอียด
eventocr_job.completed หรือ ocr_job.failed
data.result_urlsigned URL ของผลเต็ม อายุ 1 ชั่วโมง — หรือเรียก /api/v3/ocr/result/{jobId} แทน
data.errorข้อความเมื่อ failed

ยืนยันก่อนเชื่อ

ถือ webhook เป็นสัญญาณว่างานจบ แล้วเรียก GET /api/v3/ocr/status/{jobId} ด้วย API key ของคุณเพื่อยืนยันสถานะก่อนใช้ผล ระบบอาจส่งซ้ำ ให้ handler idempotent ตาม X-OCR-Job-Id

อายุงาน

  • เก็บงานและผล 7,200 ชั่วโมง (ประมาณ 300 วัน) หลังสร้าง — ลบเองได้ทุกเมื่อด้วย DELETE /api/v3/ocr/{jobId}
  • งานหมดอายุถูกลบทุกชั่วโมง
  • signed URL ของผลมีอายุ 1 ชั่วโมง และต่อเมื่อเรียก status/result

HTTP

HTTPความหมาย
202รับงานเข้าคิว
200อ่านสถานะ / ผล / ยกเลิก
402เครดิตไม่พอ
404ไม่พบงาน
429เกินลิมิต