Key Extraction · API v3

การดึงผลลัพธ์

สถานะงานอยู่ที่ GET /api/v3/key-extract/jobs/:jobId — ไม่มีผลเต็ม เมื่อสถานะเป็น completed ค่อย GET /api/v3/key-extract/jobs/:jobId/result

สถานะงาน

01
queued
รอเข้าคิว
02
processing
กำลังประมวลผล
03
completed
เสร็จสมบูรณ์
04
failed
เกิดข้อผิดพลาด
05
cancelled
ยกเลิกแล้ว
06
expired
หมดอายุตาม retention

จาก queued/processing อาจไป cancelling แล้ว cancelled ก่อน completed client ควรมี default branch สำหรับสถานะใหม่ในอนาคต

Result schema

json
{
"job_id": "ext_01JBY7...",
"needs_review": true,
"data": {
"invoice_no": "IV-2026-001",
"vendor": { "name": "Example Co., Ltd.", "tax_id": "0105559999999" },
"line_items": [
{ "description": "A4 paper", "quantity": 2, "unit_price": 500.0, "amount": 1000.0 }
]
},
"field_metadata": {
"/invoice_no": {
"status": "verified",
"confidence": 0.98,
"regions": [
{ "page": 1, "bbox": [0.684, 0.072, 0.912, 0.104], "text": "IV-2026-001" }
]
},
"/line_items/0/amount": {
"status": "verified",
"confidence": 0.93,
"regions": [
{ "page": 1, "bbox": [0.811, 0.424, 0.928, 0.452], "text": "1,000.00" }
]
}
},
"pages": [
{ "page": 1, "input_index": 0, "page_in_input": 1, "file_id": "file_01J9...", "width": 1240, "height": 1754 }
],
"validation": { "missing_required": [], "below_threshold": [] },
"usage": { "pages_processed": 1, "credits_micros": 0 }
}

ฟิลด์ที่ควรอ่าน

พาธความหมาย
dataค่าที่ดึงได้ตาม schema — ไม่มีพิกัดปน
field_metadatastatus, confidence, regions ต่อใบ ตาม JSON Pointer
pages[]ขนาดพิกเซลต่อหน้า สำหรับแปลง bbox เป็นพิกเซลตอนเรนเดอร์
needs_reviewtrue ถ้ามีฟิลด์ต่ำกว่าเกณฑ์หรือ required หาย

JSON Pointer

ชนิดตัวอย่างคีย์
สเกลาร์/invoice_no
ซ้อนใน object/vendor/tax_id
เซลล์ในตาราง/line_items/0/amount

มี metadata เฉพาะใบ (leaf) ไม่มีรายการรวมทั้งตารางหรือทั้งแถว ฟิลด์ที่หาไม่เจอเป็น null ใน data และ status: "not_found" พร้อม regions: []

Bounding box

รูปแบบ

bbox คือ [x_min, y_min, x_max, y_max]ค่าเป็น float ช่วง 0–1 จุดกำเนิดมุมบนซ้ายของหน้าต้นฉบับ (หลังหมุนตาม EXIF/PDF แล้ว ก่อน deskew / crop ภายใน)

แปลงเป็นพิกเซลตอนวาด

javascript
function toPixels(bbox, pageWidth, pageHeight) {
const [x1, y1, x2, y2] = bbox;
return {
x: x1 * pageWidth,
y: y1 * pageHeight,
width: (x2 - x1) * pageWidth,
height: (y2 - y1) * pageHeight,
};
}
const meta = result.field_metadata["/invoice_no"];
const page = result.pages.find((p) => p.page === meta.regions[0].page);
const box = toPixels(meta.regions[0].bbox, page.width, page.height);

ฟิลด์หนึ่งอาจมีหลาย region รวมถึงคนละหน้า เมื่อ output.evidence เป็น none อาร์เรย์ regions จะว่างเสมอ แต่ status / confidence ยังมี

status ของฟิลด์

statusความหมาย
verifiedค่ายึดกับ region ต้นทางอย่างน้อยหนึ่งจุด
inferredอนุมานจากบริบท ไม่คาดหวัง span ตรงตัว
needs_reviewมีค่าแต่คะแนนหรือ grounding คลุมเครือ
not_foundไม่พบค่า — data ของฟิลด์นั้นเป็น null

เมื่อยังไม่พร้อม

เรียก /result ก่อนเสร็จได้ 409 result_not_readyหลังหมดอายุได้ 410 result_expiredแนะนำ poll แบบ exponential backoff สูงสุด 2–5 วินาที และเคารพ Retry-After ถ้ามี