Extract

Extract structured data fields from documents using a vision-language model. Returns named entities and line items.

Cost$0.05/page

Latency~2s

hyperbots_vlm_extract

Step 1: Upload your document — call POST /v1/documents/upload to get a document_key

Request

Headers

Name	Type	Required	Description
`X-API-Key`	`string`	required	Your HyperAPI key (hk_live_* or hk_test_*).
`X-Async`	`string`	optional	Set to "true" to process asynchronously and receive a job ID.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).

Query Parameters

Name	Type	Default	Description
`ocr_engine`	`string`	`paddle`	OCR engine to use for text extraction.
`mode`	`string`	`default`	Extraction mode controlling which fields are targeted.

Code examples

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/extract?ocr_engine=paddle&mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/extract?ocr_engine=paddle&mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

Response

200 OK

application/json

JSON

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      { "description": "Widget A", "quantity": 10, "unit_price": "100.00", "total": "1,000.00" },
      { "description": "Shipping", "quantity": 1, "unit_price": "250.00", "total": "250.00" }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      { "description": "Widget A", "quantity": 10, "unit_price": "100.00", "total": "1,000.00" },
      { "description": "Shipping", "quantity": 1, "unit_price": "250.00", "total": "250.00" }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}