API Reference · Key Extraction v3

Jobs

หนึ่งงาน = หนึ่งเอกสารเชิงตรรกะ inputs[] คือหน้า/ส่วนเรียงตามลำดับ ไม่ใช่หลายเอกสารในคำขอเดียว

Create job

POSThttps://backend.aksonocr.com/api/v3/key-extract/jobs
ค่า
HTTP202 + header Location
AuthX-API-Key
IdempotencyIdempotency-Key (จำเป็น)

Headers

Headerจำเป็นรายละเอียด
X-API-Keyใช่คีย์จาก Dashboard
Idempotency-Keyใช่1–255 ตัวอักษร ขอบเขตต่อ tenant + endpoint

Idempotency

คีย์เดิม + body เดิม คืนงานเดิมโดยไม่คิดเงินซ้ำ คีย์เดิม + body ต่างได้ 409 idempotency_conflict

Body

ฟิลด์ชนิดจำเป็นรายละเอียด
inputsobject[]ใช่อย่างน้อย 1 สูงสุด 50 ตามลำดับหน้า
inputs[].file_idstringใช่จาก POST /files
inputs[].pagesinteger[]ไม่หน้า PDF 1-based ไม่ซ้ำ ห้ามใช้กับรูป
data_schemaobjectXORJSON Schema subset — รากเป็น object
templateobjectXOR{ id, version? } ถ้าไม่ระบุ version จะล็อก latest ตอนรับงาน
instructionsstringไม่≤ 10,000 ตัวอักษร ห้ามเปลี่ยน schema
output.evidenceenumไม่bbox (ค่าเริ่มต้น) | none
review_thresholdnumberไม่0–1 ค่าเริ่มต้น 0.8
client_referencestringไม่สะท้อนกลับ ไม่ส่งเข้าโมเดล ≤ 255
webhook_idstringไม่สงวนไว้ — ยังไม่ส่ง notification
retention_hoursintegerไม่1–168 ค่าเริ่มต้น 24
ส่ง template หรือ data_schema อย่างใดอย่างหนึ่ง ฟิลด์ที่ไม่รู้จักจะถูกปฏิเสธ
import requests
job = requests.post(
"https://backend.aksonocr.com/api/v3/key-extract/jobs",
headers={
"X-API-Key": "<YOUR_API_KEY>",
"Idempotency-Key": "invoice-2026-001",
},
json={
"inputs": [{"file_id": "file_01J9..."}],
"data_schema": {
"type": "object",
"additionalProperties": False,
"properties": {
"invoice_no": {"type": "string"},
"total": {"type": "number"},
},
},
"output": {"evidence": "bbox"},
},
)
job.raise_for_status()
print(job.json()["id"], job.headers.get("Location"))

Response 202

json
{
"id": "ext_01JBY7...",
"status": "queued",
"client_reference": "invoice-2026-001",
"created_at": "2026-09-06T10:00:00Z",
"configuration": {
"template": null,
"schema_sha256": "5d3a...",
"output": { "evidence": "bbox" },
"review_threshold": 0.8
},
"links": {
"self": "/api/v3/key-extract/jobs/ext_01JBY7...",
"result": "/api/v3/key-extract/jobs/ext_01JBY7.../result"
},
"request_id": "req_01J..."
}

Get job (poll)

GEThttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}

คืนสถานะและความคืบหน้าเท่านั้น ไม่มีผลเต็ม แนะนำ backoff 2–5 วินาที เคารพ Retry-After

json
{
"id": "ext_01JBY7...",
"status": "processing",
"progress": { "pages_total": 3, "pages_completed": 2 },
"created_at": "2026-09-06T10:00:00Z",
"started_at": "2026-09-06T10:00:01Z",
"completed_at": null,
"expires_at": "2026-09-07T10:00:00Z",
"links": {
"self": "/api/v3/key-extract/jobs/ext_01JBY7...",
"result": "/api/v3/key-extract/jobs/ext_01JBY7.../result"
},
"request_id": "req_01J..."
}
statusความหมาย
queuedรอเข้าคิว
processingกำลังประมวลผล
cancellingกำลังยกเลิก
completedเสร็จ — ดึง /result ได้
failedล้มเหลว — อ่าน error
cancelledยกเลิกแล้ว
expiredหมดอายุตาม retention
client ควรมี default branch สำหรับสถานะใหม่ งาน failed มี error.code / message / retryable

List jobs

GEThttps://backend.aksonocr.com/api/v3/key-extract/jobs
Queryชนิดรายละเอียด
statusenumกรองตามสถานะงาน
cursorstringopaque cursor จากหน้าก่อน
limitinteger1–100 ค่าเริ่มต้น 20
json
{
"data": [{ "id": "ext_01JBY7...", "status": "completed" }],
"has_more": true,
"next_cursor": "cur_01J...",
"request_id": "req_01J..."
}

Cancel job

POSThttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}/cancel

Best-effort ได้ 202 ถ้ายกเลิกจาก queued/processing งานที่จบแล้วได้ 409 already_terminal

Delete job

DELETEhttps://backend.aksonocr.com/api/v3/key-extract/jobs/{job_id}

204 ลบผลและปล่อย lease ของไฟล์ในงานนี้ ไม่ลบไฟล์ที่งานอื่นยังใช้อยู่

Errors

HTTPcode
400invalid_request, input_conflict
404job_not_found, file_not_found, template_not_found
409idempotency_conflict, already_terminal, template_archived
410file_expired
413page_limit_exceeded, payload_too_large
422invalid_schema, unreadable_document
429rate_limited — งานค้างเกิน 10, เกิน 60 งาน/นาที หรือเกิน 5,000 หน้า/24 ชม.
503temporarily_unavailable