IDCard OCR

Extract ID CARD information from an image or photo. Currently only Thai ID Card is supported. Confidence score is scored from the OCR result.

info

Confidence score is -1.0 when the value of each validation field is False.

API Version

IDCard OCR

Extract ID CARD information from an image or photo. Currently only Thai ID Card is supported.

Response Definition

HTTP Status	Error Code	Error Message	Description
200	-	-	Document information extraction successfully.
206	`206`	`Partial Content`	The API was unable to retrieve information on some image or page content. In case request images or pages greater than one.
400	`400`	`Bad request`	Not a valid image request (must be .jpg, .jpeg, .png, .pdf) or invalid size, request schema. The API cannot retrieve information on any image.
413	`20000`	`The request image base64 is too large.`	The requested image size is larger than the specified image size.
422	`20001`	`The base64 image is incompatible.`	The Base64 image is incompatible and cannot be decoded.
500	`internal_server_error`	`Internal server error`	Some errors occurred inside the server.

Request Options

Option Key	Type	Description
`censor_field`	`List[str]`	Censor source image based on given input fields, e.g. `["id_number","title_name_surname_th"]`
`image_file_conversion`	`str`	Convert document to another format: `"jpeg"` \| `"origin"` \| `"pdf"` \| `"png"` \| `"tiff"`
`return_face`	`bool`	Detect face on ID card
`return_gender`	`bool`	Extract gender from title
`return_signed`	`bool`	Detect signature on top of document's images
`do_field_validation`	`bool`	Enable field validation
`return_datetime_iso`	`bool`	Enable date time ISO format for date time fields

Response Keys

Key	Type	Description
`status`	`str`	The summary status.
`error`	`List[dict]`	The list of errors which occurred during extracting information in each image or page.
`data`	`List[dict]`	The response dictionary for each individual request page or image.

Response Error Keys

Key	Type	Description
`object`	`str`	Show status `"error"`.
`code`	`str`	Error code corresponding to error.
`message`	`str`	Error detail.

Response Data Keys

Each field in the response data follows the Object Information V3 schema:

Key	Type	Description
`value`	`str`	The string value of the field.
`bboxes`	`List[List[List[int]]]`	The list of OCR bounding boxes in the document.
`bboxes_norm`	`List[List[List[float]]]`	The list of OCR bounding boxes in normalized scale [0, 1].
`confidence`	`float`	The OCR confidence level.

Data fields:

Key	Description
`id_number`	ID card number
`title_name_surname_th`	Full Thai name (title + name + surname)
`title_name_en`	English title and first name
`surname_en`	English surname
`dob_th`	Date of birth (Thai)
`dob_en`	Date of birth (English)
`religion`	Religion
`address_1`	Address line 1
`address_2`	Address line 2
`address_full`	Full address
`address_house_building_number`	House/building number
`address_street_address`	Street address
`address_sub_district`	Sub-district
`address_district`	District
`address_province`	Province
`address_postcode`	Postcode
`doi_th`	Date of issue (Thai)
`doi_en`	Date of issue (English)
`doe_th`	Date of expiry (Thai)
`doe_en`	Date of expiry (English)
`title_th`	Thai title
`name_th`	Thai first name
`surname_th`	Thai surname
`title_en`	English title
`name_en`	English first name

Optional Fields

Returned under the option key when the corresponding request option is enabled.

Key	Type	Description
`face`	`base64`	The extracted facial image from ID card.
`gender`	`str`	The gender prediction from ID card information.
`signed`	`bool`	Whether there is a signature over copied ID card documents.
`processed_image`	`base64`	Enabled when the optional `censor_field` input is provided.

Extract ID card information

POST https://api.aigen.online/aiscript/idcard/v3

Request Body

Name	Type	Description
`image`	`String`	Base64 image encoded string
`option`	`Optional[dict]`	Specify optional features like `{` `censor_field:[field_array]` `return_face: true,` `...` `}`

Responses

200: OK
206: Partial Content
400: Bad Request
413: Request Entity Too Large
422: Unprocessable Entity

View Response

{
  "status": "success",
  "error": [],
  "data": [
    {
      "id_number": {
        "bboxes": [[[857, 238], [1418, 239], [1416, 307], [855, 307]]],
        "bboxes_norm": [[[0.4357, 0.1803], [0.7209, 0.1811], [0.7199, 0.2326], [0.4347, 0.2326]]],
        "value": "0000000000000",
        "confidence": -1.0
      },
      "title_name_surname_th": {
        "bboxes": [[[589, 317], [1504, 318], [1502, 419], [587, 418]]],
        "bboxes_norm": [[[0.2994, 0.2402], [0.7646, 0.2409], [0.7636, 0.3174], [0.2984, 0.3167]]],
        "value": "นาย ตัวอย่าง บัตรประชาชน",
        "confidence": 0.9863
      },
      "title_name_en": {
        "bboxes": [[[761, 435], [1109, 436], [1108, 503], [760, 503]]],
        "bboxes_norm": [[[0.3869, 0.3295], [0.5638, 0.3303], [0.5633, 0.3811], [0.3864, 0.3811]]],
        "value": "MR. TUAYANG",
        "confidence": 0.9946
      },
      "surname_en": {
        "bboxes": [[[885, 510], [1277, 511], [1275, 575], [883, 574]]],
        "bboxes_norm": [[[0.4499, 0.3864], [0.6492, 0.3871], [0.6482, 0.4356], [0.4489, 0.4348]]],
        "value": "BUDPRACHACHON",
        "confidence": 0.999
      },
      "dob_th": {
        "bboxes": [[[830, 582], [1171, 583], [1169, 648], [829, 647]]],
        "bboxes_norm": [[[0.422, 0.4409], [0.5953, 0.4417], [0.5943, 0.4909], [0.4215, 0.4902]]],
        "value": "14 ก.พ. 2531",
        "confidence": 0.9961
      },
      "dob_en": {
        "bboxes": [[[963, 657], [1312, 658], [1311, 722], [962, 721]]],
        "bboxes_norm": [[[0.4896, 0.4977], [0.667, 0.4985], [0.6665, 0.547], [0.4891, 0.5462]]],
        "value": "14 Feb. 1988",
        "confidence": 0.9966
      },
      "religion": {},
      "address_1": {
        "bboxes": [[[281, 791], [1176, 794], [1174, 900], [279, 896]]],
        "bboxes_norm": [[[0.1429, 0.5992], [0.5979, 0.6015], [0.5968, 0.6818], [0.1418, 0.6788]]],
        "value": "ที่อยู่ 17/1 หมู่ที่ 9 ต.ตัวอย่าง อ. ตัวอย่าง",
        "confidence": 0.981
      },
      "address_2": {
        "bboxes": [[[282, 890], [506, 891], [505, 960], [281, 959]]],
        "bboxes_norm": [[[0.1434, 0.6742], [0.2572, 0.675], [0.2567, 0.7273], [0.1429, 0.7265]]],
        "value": "จ.ตัวอย่าง",
        "confidence": 0.9878
      },
      "address_full": {
        "bboxes": [
          [[281, 791], [1176, 794], [1174, 900], [279, 896]],
          [[282, 890], [506, 891], [505, 960], [281, 959]]
        ],
        "bboxes_norm": [
          [[0.1429, 0.5992], [0.5979, 0.6015], [0.5968, 0.6818], [0.1418, 0.6788]],
          [[0.1434, 0.6742], [0.2572, 0.675], [0.2567, 0.7273], [0.1429, 0.7265]]
        ],
        "value": "17/1 หมู่ที่ 9 ต.หัวไผ่ อ.เมืองอ่างทอง จ.อ่างทอง",
        "confidence": 0.969
      },
      "address_house_building_number": {
        "value": "17/1",
        "confidence": 0.9689
      },
      "address_street_address": {
        "value": "หมู่ที่ 9",
        "confidence": 0.9689
      },
      "address_sub_district": {
        "value": "ต.หัวไผ่",
        "confidence": 0.969
      },
      "address_district": {
        "value": "อ.เมืองอ่างทอง",
        "confidence": 0.969
      },
      "address_province": {
        "value": "จ.อ่างทอง",
        "confidence": 0.969
      },
      "address_postcode": {},
      "doi_th": {
        "bboxes": [[[283, 968], [532, 969], [531, 1017], [282, 1016]]],
        "bboxes_norm": [[[0.1439, 0.7333], [0.2705, 0.7341], [0.27, 0.7705], [0.1434, 0.7697]]],
        "value": "14 ก.พ. 2561",
        "confidence": 0.9946
      },
      "doi_en": {
        "bboxes": [[[285, 1059], [541, 1060], [540, 1111], [284, 1110]]],
        "bboxes_norm": [[[0.1449, 0.8023], [0.275, 0.803], [0.2745, 0.8417], [0.1444, 0.8409]]],
        "value": "14 Feb. 2011",
        "confidence": 0.9961
      },
      "doe_th": {
        "bboxes": [[[1043, 959], [1293, 960], [1292, 1010], [1042, 1008]]],
        "bboxes_norm": [[[0.5302, 0.7265], [0.6573, 0.7273], [0.6568, 0.7652], [0.5297, 0.7636]]],
        "value": "13 ก.พ. 2570",
        "confidence": 0.9966
      },
      "doe_en": {
        "bboxes": [[[1049, 1053], [1301, 1054], [1300, 1100], [1048, 1099]]],
        "bboxes_norm": [[[0.5333, 0.7977], [0.6614, 0.7985], [0.6609, 0.8333], [0.5328, 0.8326]]],
        "value": "13 Feb. 2017",
        "confidence": 0.9946
      },
      "title_th": {
        "value": "นาย",
        "confidence": 0.9863
      },
      "name_th": {
        "value": "ตัวอย่าง",
        "confidence": 0.9863
      },
      "surname_th": {
        "value": "บัตรประชาชน",
        "confidence": 0.9863
      },
      "title_en": {
        "value": "MR.",
        "confidence": 0.9946
      },
      "name_en": {
        "value": "TUAYANG",
        "confidence": 0.9946
      },
      "option": {
        "face": {},
        "gender": {},
        "signed": {},
        "processed_image": {}
      }
    }
  ]
}

View Response

{
  "status": "error",
  "error": [
    {
      "object": "error",
      "code": "400",
      "message": "Internal process error during extract image page: 2."
    },
    {
      "object": "error",
      "code": "206",
      "message": "Partial Content."
    }
  ],
  "data": [
    {
      "id_number": {
        "bboxes": [[[1039, 375], [1330, 364], [1331, 402], [1039, 412]]],
        "bboxes_norm": [[[0.4988, 0.1261], [0.6385, 0.1224], [0.639, 0.1352], [0.4988, 0.1386]]],
        "value": "0000000000000",
        "confidence": 0.9902
      },
      "...": "..."
    },
    {}
  ]
}

View Response

{
  "status": "error",
  "error": [
    {
      "object": "error",
      "code": "400",
      "message": "Internal process error during extract image page: 1."
    },
    {
      "object": "error",
      "code": "400",
      "message": "Bad request"
    }
  ],
  "data": [{}]
}

View Response

{
  "status": "error",
  "error": [
    {
      "object": "error",
      "code": 20000,
      "message": "The request image base64 is too large."
    }
  ],
  "data": []
}

View Response

{
  "status": "error",
  "error": [
    {
      "object": "error",
      "code": 20001,
      "message": "The base64 image is incompatible."
    }
  ],
  "data": []
}

Example Code

Python
Node.js
PHP
cURL

import requests

api = "https://api.aigen.online/aiscript/idcard/v3"
headers = {"x-aigen-key": "<key>"}
data = {
  "image": "base64_image",
  "option": {} #optional
}
res = requests.post(api, json=data, headers=headers)
print(res.json())

const axios = require("axios");

const api = "https://api.aigen.online/aiscript/idcard/v3";
const headers = { "x-aigen-key": "" };
const data = {
  image: "<base64_string>",
  option: {}, //optional
};
axios
  .post(api, data, { headers: headers })
  .then((res) => {
    console.log(res.data);
  })
  .catch((err) => {
    console.error(err.response.data);
  });

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.aigen.online/aiscript/idcard/v3',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "image": "<base64_string>",
     "option" : {}
}',
  CURLOPT_HTTPHEADER => array(
    'X-AIGEN-KEY: <aigen-key>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

curl --location 'https://api.aigen.online/aiscript/idcard/v3' \
--header 'X-AIGEN-KEY: <aigen-key>' \
--header 'Content-Type: application/json' \
--data '{
    "image": "<base64_string>",
    "option" : {}
}'

Response Definition​

Request Options​

Response Keys​

Response Error Keys​

Response Data Keys​

Optional Fields​

Extract ID card information​

Request Body​

Responses​

Example Code​

Response Definition

Request Options

Response Keys

Response Error Keys

Response Data Keys

Optional Fields

Extract ID card information

Request Body

Responses

Example Code