NAV

Introduction

Hey there! Welcome to the documentation for Gemini. You will find guidance on how to integrate the Gemini component into your website.

The Gemini component is a javascript application that is integrated in your web application. You need to modify both your backend and frontend systems to properly integrate it.

Authentication

You will find your API Key on your profile. Store this key safely and do not share it. In particular, the API Key should never published on a HTML page.

The requests that your backend performs against our server must be authenticated with the API Key by adding the HTTP Header X-Api-Key to the HTTP requests.

Integration of the Gemini Component

Integrating the Gemini component into your application requires modification in both your backend and frontend. In this section, we go step by step explaining the necessary steps.

We maintain at GitHub a full working example of a very minimal site containing just the Gemini component: gemini-app-integration. Be sure to check it out.

Embedding the Gemini Component in your Front End

The simplest way to integrate the Gemini application into your web application is to embed the following form on one of your web page.

<form action="<your-action>" method="post">
  <script src="https://static.gemini-app.ai/app/gemini.js"
          type="text/javascript"
          class="gemini-button"
          data-api-token="<your-token>"
          data-api-iframe-path="<path/to/iframe>">
</form>

Pay attention to the following.

The placeholders <your-action>, <your-token> and <path/to/iframe> have to be filled by your backend and this is the subject of the backend integration.

Integrating Gemini in your Backend

To integrate the Gemini component, your backend must fill the three placeholders<your-action>, <your-token> and <path/to/iframe> of the form you embedded in your website as explained in the previous section.

Token

The Gemini component that you have embedded in the form above will interact with the user to take pictures of both her face and id and will communicate with our servers to perform the matching operation.

To authorise the Gemini component to perform the matching operation, you generate with your API Key a one-time token for the Gemini component. The generation of the one-time token counts against the API limits of your plan and must be done for one every rendering of your page.

To generate a one time token, you POST on the api endpoint https://token.v2.api.gemini-app.ai/token. The result of the call is a JSON document with a token attribute. Its value should be put in the placeholder<your-token>of the script tag.

{
    "token": "52774829-3272-4881-ad04-d53c730e3c9b"
}

The following python code snippet show how to acquire a token.

request = urllib.request.Request(url='https://token.v2.api.gemini-app.ai/token',
                                 method='POST',
                                 headers={'X-Api-Key': X_API_KEY})
with req.urlopen(request) as f:
    token = json.loads(f.read())['token']

IFrame path

The gemini script gemini.js that is embedded in the form above will create an iframe inside the form to display the gemini component. The content of the iFrame for the gemini component can be found at https://static.gemini-app.ai/app/gemini_app.html.

To start the matching process, the gemini application will need access to the camera. Modern browsers do not allow the camera if the request comes from within an iframe from a different origin.

For this reason, you must must serve the content of that iframe from your own servers. We suggest to implement a GET route path/to/iframe in your backend that will serve the content of the iframe and put that route in the placeholder <path/to/iframe> in the form above. You can simply proxy the content of https://static.gemini-app.ai/app/gemini_app.html. The follow python code snippet illustrates the iFrame serving with a werkzeug Response object.

with urllib.request.urlopen("https://static.gemini-app.ai/app/gemini_app.html") as f:
    return Response(response=iframe = f.read().decode("utf-8"),
                    mimetype='text/html',
                    status=200)

Form Action

Finally, the Gemini component will submit the result of the matching via a POST the results of the match on the action defined in your form.

The form has a field request_id containing the id of the request and a field match_status containing either match if the match is successful and no_match if the match is not successful.

You must validate the match status send by the Gemini Component against our servers using the id of the request. For this, you GET on the api endpoint https://info.v2.api.gemini-app.ai/requests/<request-id> and compare the results. If both client and server give match, then the user has been properly identified and you should allow the user to proceed. Otherwise, then the user has failed the identification check. The following python code snippet illustrates the process.

params = up.parse_qs(event['body'])
client_match_status = params.get('match_status')[0]
request_id = params.get('request_id')[0]

url = 'https://info.v2.api.gemini-app.ai/requests/{0}'.format(request_id)
request = req.Request(url, headers={'X-Api-Key': X_API_KEY})
with req.urlopen(request) as f:
    server_match_status = json.loads(f.read()).get('match_status')
if server_match_status == client_match_status and server_result == 'match':
    print('MATCH!')
else:
    print('NO MATCH!')

API Reference

The calls to our server in the sections Token and Request Result need to be authenticated with your API Key as explained in the section Authentication.

Token

To obtain a one-time token to be embeddeded on a web page.

POST https://token.v2.api.gemini-app.ai/token
{
    "token": "52774829-3272-4881-ad04-d53c730e3c9b"
}

The JSON document of type Token has the following fields.

Field Name Type Value
token String One-time token to be embeddeded on a web page.

Request Result

To obtain results about a request identified by its id request_id

POST https://info.v2.api.gemini-app.ai/requests/<request_id>
{
  "prob": 96.9842579452659,
  "conf": 93.96851589053179,
  "match_status": "match",
  "request_id": "ba757f73-0823-11e8-a21d-6bcf51eef5a2"
  ...
}

The JSON document received from the answer is complex data structure: some of the keys carry primary information, some of the keys carry secondary information and some of the keys carry information in alpha status (meaning that they can change anytime). If you encounter a key that is not listed in the present document, you must consider it in alpha status.

The following table summaries the keys by path from the root of the JSON document.

Path Type Status Description
/algorithm_version string released The version of the algorithm used to perform the match
/anti_spoofing JSON released Information related to anti-spoofing (cf. section below)
/conf number released The confidence of the match
/errors array of JSON released Errors produces by the algorithm (cf. section below); if the error array is not empty, the match status will always be error
/fatal_errors array of JSON released Technical errors that prevented the algorithm to perform a match (cf. section below); if the fatal error array is not empty, the match status will always be error
/id_detection JSON released Information related to the ID detection (cf. section below)
/images array of JSON released Information related to every image sent to the the system (cf. section below)
/match_status string released The status of the match. Can have the values: match, no_match and error.
/prob number released The probability of the match
/request_id string released The id of the request
/request_timestamp string released The time at which the request has been processed, formatted as ISO string.
/user_feedback array of JSON alpha Feedback for the user (cf. section below)
/warnings array of JSON released Warnings produced by the algorithm (cf. section below). Many warnings render the result unreliable.

JSON /anti_spoofing

The anti spoofing JSON structure contains information coming from the anti-spoofing subprocessor.

Path Type Status Description
/replay_attack_prediction/selfie_shows_real_face String released Contains a description on how likely the selfie is a real face. Possible values: Highly likely, Likely and Not likely.
/user_action_prediction Array of JSON released Contains prediction of the user action for each processed image.
/user_action_in_face_sequence String released Contains a description of the user action in the face/selfie sequence. Possible values are: takes a selfie, presents an ID and Unknown.
/user_action_in_id_sequence String released Contains a description of the user action in the id sequence. Possible values are: takes a selfie, presents an ID and Unknown.

JSON /id_detection

The id detection JSON structure contains information coming from the ID detection subprocessor.

Note: the ID detection is part of the anti spoofing and does support only a small subset of ID documents. Currently, there is no plan to extend the list of detected ID documents.

Path Type Status Description
/id_detection String released A human readable description of the detected ID. Possible values are listed in the table below.
/id_type String released ID type. Possible values are listed in the table below.
/score Number released Probablity of the ID detection.
ID Type ID Description
ch-pp Swiss Passport
ch-dl Swiss Drivers License
ch-id Swiss Identification Card
us-pp United States Passport

JSON array /images

The images key contains an array of JSON data describing every images that have been received and processed by the system. The following table gives the description of these JSON data.

Path Type Status Description
/angle Number released The rotation of the image, in degrees and in 90 degrees increments.
/bounding_box_list Array of arrays of Numbers released Each array represents the bounding box and the probability of faces detected in the image.
/filename String released The filename of the image
/full_res_height Number released The height of the image in pixels
/full_res_width Number released The width of the image in pixels
/image_type String released The type of the image, face or id
/n_faces Number released The number of detected faces in the image
/use_for_match Number released A flag whether the image was used for the matching; 1 = true, 0 = false

JSON /user_feedback

In alpha status. Documentation will be available in a future release.

JSON array /warnings, /errors, /fatal_errors

These JSON arrays are all organised in the same way. They contain JSON data for each warning, error and fatal error respectively.

The general structure of the JSON data is described in the following table

Path Type Status Description
/type String released The type of the warning, error or fatal error. These are described below.
/message String released A human readable explanation for the warning, error or fatal error.
/data JSON released Additional data that corresponds to the warning, error or fatal error.

Warnings

The following table lists possible warnings.

Type Description
N_OUTLIERS_WARNING Before the system can perform a match, it must first analyse the images. During the process, an image can be considered an outlier and is not used for the matching. Reasons for such a classification are technical, but most of the time it occurs when the input images are blurry, grainy or bad quality in general. This warning is emitted if outliers have been detected.
LOW_N_OF_IMAGES_WARNING To perform well, the system should be provided 6 images of each category. The system emits this warning if less that 6 images have been sent.
IMAGE_FEATURE_QUALITY_YELLOW_WARNING The quality of an image has been assessed as being mediocre. The associated data will contain the name of the image and what feature is affected, e.g. exposuse, sharpness, detail, dynamic range, resolution, etc.
IMAGE_FEATURE_QUALITY_RED_ERROR The quality of an image has been assessed as being bad. The associated data will contain the name of the image and what feature is affected, e.g. exposuse, sharpness, detail, dynamic range, resolution, etc.
Note: Albeit an Error, it is listed as Warning and match status Error is not invoked. This behaviour may change in a future release.
IMAGE_CAPTURE_RESOLUTION_WARNING An image has a too low resolution for a reliable match. The associated data will contain the name of the image.
IMAGE_CROP_RESOLUTION_WARNING An detected face has a too low resolution for a reliable match. The associated data will contain the name of the image.

Errors

The following table lists possible errors.

Type Description
N_OUTLIERS_ERROR Too many outliers have been detected and the system cancels the match. Most of the time it occurs when the input images are blurry, grainy or bad quality in general.
N_FACES_ERROR The system has detected more that 1 face in at least one picture and cancels the match due to too low reliablity.
USER_ACTION_ERROR The user action detection has found a problem: either the user has presented an ID during scanning the selfie or the user has taken a selfie during the scanning of the ID document.

Fatal Errors

The following table lists possible fatal errors.

Type Description
UNABLE_TO_COMPUTE_MATCH_ERROR The given images are faulty/problematic and the system cannot proceed with the match.
SAME_FACE_IN_CLASS_ERROR The system has detected different persons within a class (selfie/id) and cannot proceed with the match.

Impressum

Rendered by Hugo with the DocuApi theme.

© 2018, smbh.ch