API Reference
OCR v3 — Async
สร้างงานแล้วได้ jobId ทันที ประมวลผลพื้นหลัง สูงสุด 1,000 หน้า / ไฟล์ 10 MBaction เป็น transcribe หรือ extractor
ต้องการ bounding box?
extractor ของ OCR v3 ไม่คืนตำแหน่งบนเอกสาร ใช้ Key Extraction v3
| Method | Path | รายละเอียด |
|---|---|---|
| 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 | ลบงาน |
สร้างงาน
POST
https://backend.aksonocr.com/api/v3/ocrjson
{"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 เมื่องานเข้าสู่สถานะปลายทาง |
customFields | extractor | อาร์เรย์ { key, description, example } |
templateId | extractor | เทมเพลตจาก 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 และดึงผล
GET
https://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.1Content-Type: application/jsonX-Webhook-Event: ocr_job.completedX-OCR-Job-Id: 1d0782b4-8c75-49e6-b646-4cfa0f16acd1X-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"}}
| ฟิลด์ | รายละเอียด |
|---|---|
event | ocr_job.completed หรือ ocr_job.failed |
data.result_url | signed 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 | เกินลิมิต |