logo

API v2

Authentication mechanism

We use Basic Authentication to grant access to the API.

How it works:

  1. API access key is a pair:
  • username (api_key): a unique identifier (UUID) of the API access key.

  • password (api_secret): a secret key of the API access key.

    Computer Vision Vietnam team will create username and password for each customers before integration.

  1. Client send a request:

    The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password. For example, demo:p@55w0rd the client would send

    Authorization: Basic ZGVtbzpwQDU1dzByZA==

Interaction Flows

Flow 1: OCR

ocr

Flow 2: Face Matching

face matching

face search

List of APIs

OCR

OCR service is an AI system that allows to extract information from identity cards, identity cards of Vietnamese citizens, driver's licenses, passports, and vehicle registration. The system identifies both the front and back of the identity card and citizenship card. Currently supports driver's license, passport, ID card, and vehicle registration.

1. Extract information from both sides of ID card using image url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ekyc/cards

Params:

KeyValueDescription
img1https://example.com/front.pngurl of the id card’s front side
img2https://example.com/back.pngurl of the id card’s back side
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
front_url = 'sample front url'
back_url = 'sample back url'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ekyc/cards?img1=%s&img2=%s&format_type=%s&get_thumb=%s"
% (front_url, back_url, 'url', 'false'),
auth=(api_key, api_secret))
print(response.json())

2. Extract information from both sides of ID card using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/cardsmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

KeyTypeValueDescription
img1fileexample_front.jpgimage file of the id card’s front side
img2fileexample_back.jpgimage file of the id card’s back side

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
front_path = '/path/to/your/example_front.jpg'
back_path = '/path/to/your/example_back.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/cards?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img1': open(front_path, 'rb'), 'img2' : open(back_path, 'rb')})
print(response.json())

3. Extract information from both sides of ID card using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/cardsapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

{
"img1": "iVBORw0KGgoAAAANSU...", // base64 string of front image
"img2": "iVBORw0KGgoAAAANSU..." // base64 string of back image
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_front_path = "/path/to/your/img_front.jpg"
img_back_path = "/path/to/your/img_back.jpg"
encode_front = get_byte_img(Image.open(img_front_path))
encode_back = get_byte_img(Image.open(img_back_path))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/cards?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img1' : encode_front, "img2" : encode_back})
print(response.json())

4. Extract information from an image that contains multiple sides of id card or passport, using image url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ocr/card

Params:

KeyValueDescription
imghttps://example.com/image.pngUrl of input image
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_url = 'https://example.com/image.png'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ocr/card?img=%s&format_type=%s&get_thumb=%s"
% (image_url, 'url', 'false'),
auth=(api_key, api_secret))
print(response.json())

5. Extract information from an image that contains multiple sides of id card or passport, using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/cardmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

KeyTypeValueDescription
imgfileexample.jpgimage file taken from id card

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_path = '/path/to/your/example.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/card?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img': open(image_path, 'rb')})
print(response.json())

6. Extract information from an image that contains multiple sides of id card or passport, using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/cardapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

{
"img": "iVBORw0KGgoAAAANSU...", // base64 string of the image
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_path = "/path/to/your/image.jpg"
encode_img = get_byte_img(Image.open(img_path))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/card?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img' : encode_img})
print(response.json())

7. Extract information from an id card image of any type, using image url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ekyc/card

Params:

KeyValueDescription
imghttps://example.com/image.pngUrl of id card image of any type
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_url = 'https://example.com/image.png'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ekyc/card?url=%s&format_type=%s&get_thumb=%s"
% (image_url, 'url', 'false'),
auth=(api_key, api_secret))
print(response.json())

8. Extract information from an id card image of any type, using image file or PDF file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/cardmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

KeyTypeValueDescription
imgfileexample.jpgimage file taken from id card

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_path = '/path/to/your/example.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/card?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img': open(image_path, 'rb')})
print(response.json())

9. Extract information from an id card image of any type, using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/cardapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the id card

Body:

{
"img": "iVBORw0KGgoAAAANSU..." // base64 string of id card
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_name = "path_img"
encode_cmt = get_byte_img(Image.open(img_name))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/card?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img' : encode_cmt})
print(response.json())

10. Extract information from driver’s license using image url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ocr/driving_license

Params:

KeyValueDescription
imghttps://example.com/blx.pngimage url of driver’s license
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the driving license

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_url = 'https://daotaothanhcong.com/wp-content/uploads/2019/10/bang-lai-xe-b1-co-thoi-han-bao-lau.jpg'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ocr/driving_license?img=%s&format_type=url&get_thumb=false" % image_url,
auth=(api_key, api_secret))
print(response.json())

11. Extract information from driver’s license using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/driving_licensemultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the driving license

Body:

KeyTypeValueDescription
imgfileexample_blx.jpgimage file of driver's license

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_path = '/path/to/your/image.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/driving_license?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img': open(image_path, 'rb')})
print(response.json())

12. Extract information from driver’s license using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/driving_licenseapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the driving license

Body:

{
"img": "iVBORw0KGgoAAAANSU..." // base64 string of driving license
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_name = "path_img"
encode_cmt = get_byte_img(Image.open(img_name))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/driving_license?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img' : encode_cmt})
print(response.json())

13. Extract information from both sides of vehicle registration using url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrations

Params:

KeyValueDescription
img1https://example.com/front.pngFront side image of the vehicle registration
img2https://example.com/back.pngBack side image of the vehicle registration
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
front_url = 'sample front url'
back_url = 'sample back url'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrations?img1=%s&img2=%s&format_type=%s&get_thumb=%s"
% (front_url, back_url, 'url', 'false'),
auth=(api_key, api_secret))
print(response.json())

14. Extract information from both sides of vehicle registration using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrationsmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Body:

KeyTypeValueDescription
img1fileexample_front.jpgfront side image of the vehicle registration
img2fileexample_back.jpgback side image of the vehicle registration

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
front_path = '/path/to/your/example_front.jpg'
back_path = '/path/to/your/example_back.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrations?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img1': open(front_path, 'rb'), 'img2' : open(back_path, 'rb')})
print(response.json())

15. Extract information from both sides of vehicle registration using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrationsapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Body:

{
"img1": "iVBORw0KGgoAAAANSU...", // base64 string of front side
"img2": "iVBORw0KGgoAAAANSU..." // base64 string of back side
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_front_path = "/path/to/your/img_front.jpg"
img_back_path = "/path/to/your/img_back.jpg"
encode_front = get_byte_img(Image.open(img_front_path))
encode_back = get_byte_img(Image.open(img_back_path))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrations?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img1' : encode_front, "img2" : encode_back})
print(response.json())

16. Extract information from an image of vehicle registration of any type using url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registration

Params:

KeyValueDescription
imghttps://example.com/image.pngimage of the vehicle registration
format_typeurlparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_url = 'https://example.com/image.png'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registration?url=%s&format_type=%s&get_thumb=%s"
% (image_url, 'url', 'false'),
auth=(api_key, api_secret))
print(response.json())

17. Extract information from an image of vehicle registration of any type using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrationmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Body:

KeyTypeValueDescription
imgfileexample.jpgimage of the vehicle registration

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_path = '/path/to/your/example.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registration?format_type=file&get_thumb=false",
auth=(api_key, api_secret),
files={'img': open(image_path, 'rb')})
print(response.json())

18. Extract information from an image of vehicle registration of any type using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/vehicle_registrationapplication/json

Params:

KeyValueDescription
format_typebase64parameter for the type of input data passed, possible values: url, file, base64
get_thumbtrue/falseoption to return the aligned image of the vehicle registration

Body:

{
"img": "iVBORw0KGgoAAAANSU..." // base64 string of the vehicle registration
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_name = "path_img"
encode_cmt = get_byte_img(Image.open(img_name))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/vehicle_registration?format_type=base64&get_thumb=false",
auth=(api_key, api_secret),
json={'img' : encode_cmt})
print(response.json())

19. Extract information from an image of document using image url as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ocr/scan

Params:

KeyValueDescription
imghttps://example.com/image.pngurl of the document image
format_typeurlparameter for the type of input data passed, possible values: url, file, base64

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_url = 'https://example.com/image.png'
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/ocr/scan?img=%s&format_type=url" % image_url,
auth=(api_key, api_secret))
print(response.json())

20. Extract information from an image of document using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ocr/scanmultipart/form-data

Params:

KeyValueDescription
format_typefileparameter for the type of input data passed, possible value: url, file, base64

Body:

KeyTypeValueDescription
imgfileexample.jpgimage file of the document

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
image_path = '/path/to/your/example.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ocr/scan?format_type=file",
auth=(api_key, api_secret),
files={'img': open(image_path, 'rb')})
print(response.json())

21. Response data

The response data is a JSON containing the following fields:

{
"data": [xxxx],
"errorCode": string,
"errorMessage": string
}

In case of recognizing 1 id card image of any type, data is returned as follow:

{
"info": [xxxx],
"valid": [xxxx],
"invalidMessage": [xxxx],
"type": [xxxx]
}

Note: In case the input data contains multiple sides of an id card, or extracting information from driver’s license and vehicle registration, valid and invalidMessage fields are not present.

In case of recognizing multiple images of id cards, the field “data” in result json will be a list containing the fields above.

In case of recognizing image of document, the result is returned as follow:

{
"result": [xxxx], // array of lines in the document
"time": [xxxx], // processing time
}

type: Type of id card to which information is extracted.

  • 9_id_card_front: front side of old id card.
  • 12_id_card_front: front side of new id card.
  • 9_id_card_back: back side of old id card.
  • 12_id_card_back: back side of new id card.
  • driving_license: driver’s license.
  • passport: the document is a passport.
  • vehicle_registration_front: the front side of the registration.
  • vehicle_registration_back: the back side of the registration.

info: Include information extracted from the input image, with each type of id card there will be different information returned.

Front side of 9 digits id card:

  • id: id number.
  • name: full name.
  • dob: date of birth.
  • hometown: hometown address.
  • address: permanent address.
  • address_town_code: code of city/town in address.
  • address_district_code: code of district in address.
  • address_ward_code: code of ward in address.
  • hometown_town_code: code of city/town in hometown address.
  • hometown_district_code: code of district in hometown address.
  • hometown_ward_code: code of ward in hometown address.
  • address_town: name of city/town in address.
  • address_district: name of district in address.
  • address_ward: name of ward in address.
  • hometown_town: name of city/town in hometown address.
  • hometown_district: name of district in hometown address.
  • hometown_ward: name of ward in hometown address.
  • image: cropped and aligned image.
  • id_confidence: the confidence score of information extracted in id.
  • name_confidence: the confidence score of information extracted in name.
  • dob_confidence: the confidence score of information extracted in dob.
  • hometown_confidence: the confidence score of information extracted in hometown.
  • address_confidence: the confidence score of information extracted in address.

Front side of 12 digits id card:

  • id: id number.
  • name: full name.
  • dob: date of birth.
  • hometown: hometown address.
  • gender: gender of the person.
  • due_date: the expiration date of the id card.
  • nationality: the nationality of the person.
  • ethnicity: the ethnicity of the person.
  • address: permanent address.
  • address_town_code: code of city/town in address.
  • address_district_code: code of district in address.
  • address_ward_code: code of ward in address.
  • hometown_town_code: code of city/town in hometown address.
  • hometown_district_code: code of district in hometown address.
  • hometown_ward_code: code of ward in hometown address.
  • address_town: name of city/town in address.
  • address_district: name of district in address.
  • address_ward: name of ward in address.
  • hometown_town: name of city/town in hometown address.
  • hometown_district: name of district in hometown address.
  • hometown_ward: name of ward in hometown address.
  • image: cropped and aligned image.
  • id_confidence: the confidence score of information extracted in id.
  • name_confidence: the confidence score of information extracted in name.
  • dob_confidence: the confidence score of information extracted in dob.
  • hometown_confidence: the confidence score of information extracted in hometown.
  • gender_confidence: the confidence score of information extracted in gender.
  • due_date_confidence: the confidence score of information extracted in due_date.
  • nationality_confidence: the confidence score of information extracted in nationality.
  • ethnicity_confidence: the confidence score of information extracted in ethnicity.
  • address_confidence: the confidence score of information extracted in thường address.

Back side of 9 digits id card:

  • ethnicity: the ethnicity of the person.
  • issue_date: the issue date of the document.
  • religious: the religious of the person.
  • issued_at: the issue place of the document.
  • image: cropped and aligned image.
  • issue_date_confidence: the confidence score of information extracted in issue_date.
  • issued_at_confidence: the confidence score of information extracted in issued_at.
  • religious_confidence: the confidence score of information extracted in religious.
  • ethnicity_confidence: the confidence score of information extracted in ethnicity.

Back side of 12 digits id card:

  • issue_date: the issue date of the document.
  • issued_at: the issue place of the document.
  • image: cropped and aligned image.
  • issue_date_confidence: the confidence score of information extracted in issue_date.
  • issued_at_confidence: the confidence score of information extracted in issued_at.

Driver’s license:

  • id: id number.
  • name: full name.
  • dob: date of birth.
  • class: type of driver’s license.
  • nationality: the nationality of the driver.
  • issue_date: the issue date of the driving license.
  • due_date: the expiration date of the driving license.
  • address: the address of the driver.
  • image: cropped and aligned image.

Passport:

  • id: passport id.
  • sur_name: last name of the person.
  • given_name: first name of the person.
  • dob: date of birth.
  • gender: gender of the person.
  • country: country of issue.
  • nationality: nationality of the person.
  • due_date: expiration date of the passport.
  • person_number: id card number of the person.
  • image: cropped and aligned image.
  • confidence: the confidence score of information extracted in passport.

Front side of vehicle registration:

  • name: owner’s name.
  • address: owner’s address.
  • id: id of the registration.
  • plate: plate number.
  • issued_at: place of issue of the registration.
  • image: cropped and aligned image.

Back side of vehicle registration:

  • name: owner’s name.
  • address: owner’s address.
  • engine: engine number.
  • chassis: chassis number.
  • brand: brand of the vehicle.
  • model: model number.
  • color: color of the vehicle.
  • capacity: engine capacity.
  • issued_at: place of issue of the registration.
  • last_issue_date: last issue date of the registration.
  • first_issue_date: first issue date of the registration.
  • plate: plate number.
  • image: cropped and aligned image.

Error codes:

Error codeMessageDescription
0SuccessRequest success
1The photo does not contain contentInput image does not have id card to extract
2Url is unavailableDownload image from the url failed
3Incorrect image formatCannot open the uploaded image
4Out of requestsThe user has run out of requests
5Incorrect Api_key or api_secretWrong authentication information
6Incorrect format typeValue of format_type does not match with the input data type

Face Matching

Matching service is an AI system that allows comparing the similarities between the faces on the identification cards with the faces captured of the same person.

1. Match faces on id card and portrait image using urls as input

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/ekyc/face_matching

Params:

KeyValueDescription
img1https://example.com/card.pngimage of id card or portrait image
img2https://example.com/portrait.pngportrait image
type1portrait/cardparameter for the type of img1, possible values: portrait, card
format_typeurlparameter for the type of input data passed, possible values: url, file, base64

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_card = 'link_url_img_card'
img_portrait = 'link_url_portrait'
response = requests.get("https://cloud.computervision.com.vn/api/v2/ekyc/face_matching?img1=%s&img2=%s&type1=%s&format_type=%s"
% (img_card, img_portrait, 'card', 'url'),
auth=(api_key, api_secret))
print(response.json())

2. Match faces on id card and portrait image using image file as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/face_matchingmultipart/form-data

Params:

KeyValueDescription
type1portrait/cardparameter for the type of img1, possible values: portrait, card
format_typefileparameter for the type of input data passed, possible values: url, file, base64

Body:

KeyTypeValueDescription
img1fileexample_card.jpgimage of id card or portrait image
img2fileexample_portrait.jpgportrait image

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_card_path = '/path/to/your/img_card.jpg'
img_portrait_path = '/path/to/your/img_portrait.jpg'
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/face_matching?type1=%s&format_type=%s"
% ('card', 'file'),
auth=(api_key, api_secret),
files={'img1': open(img_card_path, 'rb'), 'img2': open(img_portrait_path, 'rb')})
print(response.json())

3. Match faces on id card and portrait image using json as input

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/ekyc/face_matchingapplication/json

Params:

KeyValueDescription
type1portrait/cardparameter for the type of img1, possible values: portrait, card
format_typebase64parameter for the type of input data passed, possible values: url, file, base64

Body:

{
"img1": "iVBORw0KGgoAAAANSU...", // base64 string of the image file
"img2": "iVBORw0KGgoAAAANSU...", // base64 string of the image file
}

Demo Python:

import base64
import io
import requests
from PIL import Image
def get_byte_img(img):
img_byte_arr = io.BytesIO()
img.save(img_byte_arr, format='PNG')
encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
return encoded_img
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
img_card_path = '/path/to/your/img_card.jpg'
img_portrait_path = '/path/to/your/img_portrait.jpg'
encode_card = get_byte_img(Image.open(img_card_path))
encode_portrait = get_byte_img(Image.open(img_portrait_path))
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/ekyc/face_matching?type1=%s&format_type=%s"
% ('card', 'base64'),
auth=(api_key, api_secret),
json={'img1' : encode_card, "img2" : encode_portrait})
print(response.json())

4. Response data

For the service that matches the portrait photo with the photo in the id card, the response will be a JSON with the following format:

{
"data": {
"matching": string, // the matching percentage
"face1": string, // base64 string of the face image
"face2": string, // base64 string of the face image
"valid": string, // False if the input image is fuzzy, obscured or has signs of tampering, otherwise True
"invalidMessage": string, // if the input image has signs of tampering
"match": string, // 1 if matching percent is greater than 75, 0 if percent matching is within the range of [65, 75], otherwise -1
},
"errorCode": string,
"errorMessage": string
}

Error codes:

Error codeMessageDescription
0SuccessRequest success
1The photo does not contain contentInput image does not have id card to extract
2Url is unavailableDownload image from the url failed
3Incorrect image formatCannot open the uploaded image
4Out of requestsThe user has run out of requests
5Incorrect Api_key or api_secretWrong authentication information
6Incorrect format typeValue of format_type does not match with the input data type

1. View all images

API:

MethodURL
GEThttps://cloud.computervision.com.vn/api/v2/face_search/images

Params:

KeyValueDescription
offset100number of records to skip
limit50maximum number of records

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
offset = 100
limit = 50
response = requests.get(
"https://cloud.computervision.com.vn/api/v2/face_search/images?offset=%s&limit=%s"
% (offset, limit),
auth = (api_key, api_secret)
)
print(response.json())

2. Search faces

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/face_search/searchapplication/json

Body:

{
"image": {
"base64": string
}
}

Where:

KeyTypeRequiredDescription
imageImageDatayesthe input image used to search
base64stringyesbase64 string of the input image

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
payload = "{\"image\":{\"base64\":\"iVBORw0KGgoAAAANSU...\"}}"
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/face_search/search",
auth=(api_key, api_secret),
data = payload
print(response.json())

3. Insert image

API:

MethodURLcontent-type
POSThttps://cloud.computervision.com.vn/api/v2/face_search/imagesapplication/json

Body:

{
"image": {
"base64": string,
"metadata": json
}
}

Where:

KeyTypeRequiredDescription
imageImageDatayesthe input image
base64stringyesbase64 string of the input image
metadatadictionarynoany key-value pairs to insert along with the input image, key user, encoding, _id are reserved and cannot be used

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
payload = "{\"image\":{\"base64\":\"iVBORw0KGgoAAAANSU...\"}}"
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/face_search/images",
auth=(api_key, api_secret),
data = payload
print(response.json())

4. Edit metadata

API:

MethodURLcontent-type
PUThttps://cloud.computervision.com.vn/api/v2/face_search/images/<image_id>application/json

Body:

{
"image_id": 123456,
"metadata": {
"name": "example",
"label": "for bar"
...
}
}
KeyRequiredDescription
metadatanoany key-value pairs to insert along with the input image, key user, encoding, _id are reserved and cannot be used

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
payload = "{\"image_id\":123456,\"metadata\":{\"name\":\"example\",\"label\":\"for bar\"}}"
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/face_search/images/<image_id>",
data = payload,
auth = (api_key, api_secret)
)
print(response.json())

5. Delete images

API:

MethodURLcontent-type
DELETEhttps://cloud.computervision.com.vn/api/v2/face_search/imagesapplication/json

Body:

{
"ids": [
123456, // id of image to delete
987654, // id of image to delete
...
]
}

Demo Python:

import requests
api_key = '<replace-with-your-api-key>'
api_secret = '<replace-with-your-api-secret>'
payload = "{\"ids\":[<image-id-you-want-to-delete>,<image-id-you-want-to-delete>,...]}"
response = requests.post(
"https://cloud.computervision.com.vn/api/v2/face_search/images",
data = payload,
auth = (api_key, api_secret)
)
print(response.json())

6. Response data

The response will be a JSON with the following format:

{
"result": [xxxx],
"status_code": int,
"message": string,
}

Different api will return different results.

View images:

  • result: the array contains the images returned, each containing the image id and the corresponding metadata

Search face:

  • result: the array contains the images returned, each containing the image id and the corresponding metadata

Insert image:

  • result: json containing the information of the newly added image

Delete images:

  • result: None

Error codes:

Error codeMessage
0Success
1Incorrect image format
2Url is unavailable
3The photo does not contain content
4Incorrect Api_key or api_secret
5Out of requests
6Error when processing the request
7Incorrect Id