Quick start
Note
This quick start guide covers only IDLive Doc REST API usage. To find out about IDLive Doc SDK please refer to the corresponding documentation section.
The quickiest and easiest way to start with the IDLive Doc product is to use IDLive Doc Server provided as a Docker image. It exposes REST API and can be used out-of-box with minimal configuration. This guide will walk you through end-to-end process of installing IDLive Doc Server, running it and making basic requests.
Installing prerequisites¶
Since the IDLive Doc Server is distributed in a form of Docker image, you need to make sure that you have Docker Engine installed on your machine. If it's not, the best way to install it is to follow the official documentation.
The next step is to install the AWS Command Line Interface (CLI) utility. It is needed to pull the Docker image from the Amazon Elastic Container Registry (ECR) which is used by ID R&D for Docker image distribution. The easiest was to install the AWS CLI is to follow the official documentation.
Pulling the Docker image¶
Now that you have all prerequisites installed, you can pull the IDLive Doc Server Docker image from AWS ECR using the credentials provided by ID R&D. This guide uses the EVAL version of the image intended for CPU-only deployment, but the process for PROD and/or GPU-enabled Docker images of the IDLive Doc Server is essentially the same. Below example illustrates the process of pulling the Docker image using shell.
$ aws configure --profile idrnd
AWS Access Key ID None: <YOUR_API_KEY>
AWS Secret Access Key None: <YOUR_SECRET_API_KEY>
Default region name None: eu-central-1
Default output format None: <None>
$ aws ecr get-login-password --profile idrnd | \
docker login --username AWS --password-stdin 367672406076.dkr.ecr.eu-central-1.amazonaws.com
$ docker pull 367672406076.dkr.ecr.eu-central-1.amazonaws.com/idlivedoc-server-eval:2.2.0
Running the Docker container¶
After pulling the Docker image, you are ready to run the Docker container. Below example illustrates how to run the container in foreground (-it command argument) and expose the REST API at 8080 port (-p 8080:8080 command argument).
$ docker run -it -e IDLIVEDOC_SERVER_AVAILABLE_PIPELINES="default-sr,default-pc,default-ps" -p 8080:8080 367672406076.dkr.ecr.eu-central-1.amazonaws.com/idlivedoc-server-eval:2.2.0
Started License Manager
License /app/prod-all-license-2025-06-30.adminmode.v2c installed
Standard Commons Logging discovery in action with spring-jcl: please remove commons-logging.jar from classpath in order to avoid potential conflicts
. ____ ____ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v3.2.5)
2024-07-01T08:43:54.747Z INFO 1 --- [IDLive Doc Server] [ main] [][]net.idrnd.idlivedoc.Application : Starting Application v2.4.1 using Java 17.0.10 with PID 1 (/app/app.jar started by server in /app)
2024-07-01T08:43:54.757Z INFO 1 --- [IDLive Doc Server] [ main] [][]net.idrnd.idlivedoc.Application : No active profile set, falling back to 1 default profile: "default"
2024-07-01T08:43:55.934Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port 8080 (http)
2024-07-01T08:43:55.943Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.apache.catalina.core.StandardService : Starting service [Tomcat]
2024-07-01T08:43:55.943Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/10.1.20]
2024-07-01T08:43:55.972Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2024-07-01T08:43:55.973Z INFO 1 --- [IDLive Doc Server] [ main] [][]w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1104 ms
Standard Commons Logging discovery in action with spring-jcl: please remove commons-logging.jar from classpath in order to avoid potential conflicts
OpenJDK 64-Bit Server VM warning: You have loaded library /app/libs/libDocSdk.so.2.4.1 which might have disabled stack guard. The VM will try to fix the stack guard now.
It's highly recommended that you fix the library with 'execstack -c <libfile>', or link it with '-z noexecstack'.
2024-07-01T08:43:56.415Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : Available license features (pipelines that can be enabled):
2024-07-01T08:43:56.415Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=SCREEN_REPLAY, pipelineName=toucan-sr, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=SCREEN_REPLAY, pipelineName=ibis-sr, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=SCREEN_REPLAY, pipelineName=ibis-sr-soft, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=PRINTED_COPY, pipelineName=robin-pc, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=PRINTED_COPY, pipelineName=penguin-pc, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=PORTRAIT_SUBSTITUTION, pipelineName=umbrellabird-ps, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=PORTRAIT_SUBSTITUTION, pipelineName=stork-ps, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : DocSdkFeature{ attackType=DIGITAL_MANIPULATIONS, pipelineName=hawk-sd, expirationDate=2025-06-02}
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : Enabled pipelines:
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : toucan-sr
2024-07-01T08:43:56.416Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : umbrellabird-ps
2024-07-01T08:43:56.417Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : robin-pc
2024-07-01T08:43:56.417Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : default-sr (alias for 'toucan-sr')
2024-07-01T08:43:56.417Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : default-ps (alias for 'umbrellabird-ps')
2024-07-01T08:43:56.417Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : default-pc (alias for 'robin-pc')
2024-07-01T08:43:56.417Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : Please wait, pipelines initialization may take a while...
2024-07-01T08:44:15.109Z INFO 1 --- [IDLive Doc Server] [ main] [][]n.i.idlivedoc.service.LivenessService : Liveness Pipelines toucan-sr, umbrellabird-ps, robin-pc initialized
2024-07-01T08:44:15.400Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.s.b.a.e.web.EndpointLinksResolver : Exposing 1 endpoint(s) beneath base path ''
2024-07-01T08:44:15.410Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.s.s.web.DefaultSecurityFilterChain : Will secure any request with [org.springframework.security.web.session.DisableEncodeUrlFilter@3855d9b2, org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter@39f42d0e, org.springframework.security.web.context.SecurityContextHolderFilter@325162e9, org.springframework.security.web.header.HeaderWriterFilter@33324c05, org.springframework.web.filter.CorsFilter@47a3d56a, org.springframework.security.web.authentication.logout.LogoutFilter@78c74647, org.springframework.security.web.savedrequest.RequestCacheAwareFilter@5c448ef, org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter@50e5032c, org.springframework.security.web.authentication.AnonymousAuthenticationFilter@3a209918, org.springframework.security.web.session.SessionManagementFilter@6169be09, org.springframework.security.web.access.ExceptionTranslationFilter@6b9c42bd]
2024-07-01T08:44:15.748Z INFO 1 --- [IDLive Doc Server] [ main] [][]o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8080 (http) with context path ''
2024-07-01T08:44:15.766Z INFO 1 --- [IDLive Doc Server] [ main] [][]net.idrnd.idlivedoc.Application : Started Application in 21.471 seconds (process running for 21.946)
Once you see the "Started Application ..." line, the container is started and ready to process requests.
Making a document liveness check request¶
The container is up and running, so now you are able to make requests to the REST API. Below example illustrates a way to make a document liveness check on a sample PNG image request using curl command line utility. Using curl utility is not mandatory, you can use any utility of your choice: Postman, Python script or Swagger UI available at http://0.0.0.0:8080/swagger-ui/index.html.
$ (echo -n '{
"image": "'; base64 image.png; echo '",
"pipelines": [
{"pipeline_name": "default-sr"}
]
}') | \
curl -H "x-api-key: <API-key>" \
-H "Content-Type: application/json" \
-X POST -d @- https://idlivedoc-rest-api.idrnd.net/check_liveness
{"pipeline_results":[{"pipeline_name":"ibis-sr","calibration":"REGULAR","result":{"liveness_score":5.4685650,"quality_score":0.9450540,"liveness_probability":0.9999875,"image_quality_warnings":[],"status_code":"OK"}}],"aggregate_quality_score":0.9450540,"aggregate_liveness_probability":0.9999875,"aggregate_image_quality_warnings":[]}
To find out more about IDLive Doc Server API and configuration possibilities please refer to the corresponding documentation section.