> For the complete documentation index, see [llms.txt](https://doc.faceplugin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.faceplugin.com/getting-started/try-it.md).

# Try it

Try Faceplugin SDKs with copy-paste commands. Start with license-free curl health and machine-code checks, then activate the SDK and test face detection, face matching, liveness, and document OCR.

These snippets are meant to be **copied as-is**. You do not write a UI first. Start with `health` and `machinecode` (no license needed), then activate and call one process API. Full endpoint contracts: [HTTP API](/integration/http-api.md).

{% hint style="info" %}
**Start with the server if you want the quickest test.** Docker Hub + `curl` lets you test the SDK without Android Studio. Mobile snippets assume you have already run the demo once, with the required AAR/framework files in place and the demo license configured for the demo app ID.
{% endhint %}

## 1. Server — no license yet

Start any Linux/Windows server product, then:

```bash
curl -s http://127.0.0.1:8083/api/health
curl -s http://127.0.0.1:8083/api/machinecode
```

Change the port: **ID Document Recognition** (Document Reader) **8082**, Face Recognition **8083**, Face Liveness **8084**, Document Liveness **8086**.

`health` works **before** you have a key. Copy the server **machine code** (machine code) from `machinecode` and [request a license](/help/request-a-license-and-support.md).

## 2. Server — activate once

```bash
# license.txt contains one line: license key
curl -s -X POST http://127.0.0.1:8083/api/activate \
  -H 'Content-Type: text/plain' \
  --data-binary @license.txt
```

Success looks like `"Successfully activated"`. The service also loads the engine on this call.

## 3. Server — try the main APIs for each product

{% tabs %}
{% tab title="Face Recognition" %}

```bash
IMG=$(base64 -w0 face.jpg)   # macOS: base64 -i face.jpg

curl -s -X POST http://127.0.0.1:8083/api/detect \
  -H 'Content-Type: application/json' \
  -d "{\"image\":\"$IMG\"}"

curl -s -X POST http://127.0.0.1:8083/api/match \
  -H 'Content-Type: application/json' \
  -d "{\"image1\":\"$IMG\",\"image2\":\"$IMG\"}"
```

Install: [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk.md). Combined recognition + liveness in one package: [Face Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux.md) (same port, adds `/api/liveness`).
{% endtab %}

{% tab title="Face Liveness" %}

```bash
IMG=$(base64 -w0 face.jpg)

curl -s -X POST http://127.0.0.1:8084/api/liveness \
  -H 'Content-Type: application/json' \
  -d "{\"image\":\"$IMG\"}"
```

Score **≥ 0.5** is Real / pass. JPEG only. [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk.md). Combined package on **8083**: same body against `/api/liveness` on [Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux.md).
{% endtab %}

{% tab title="ID Document" %}

```bash
FRONT=$(base64 -w0 passport_front.jpg)

curl -s -X POST http://127.0.0.1:8082/api/documentRecognition \
  -H 'Content-Type: application/json' \
  -d "{\"images\":[{\"image\":\"$FRONT\",\"page_idx\":0}]}"
```

Combined pipeline: `POST /api/documentProcess`. Dedicated Document Liveness product: port **8086**. [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk.md).
{% endtab %}
{% endtabs %}

Windows: use Git Bash or WSL for `base64`, or Python:

```python
import base64, json, urllib.request
img = base64.b64encode(open("face.jpg", "rb").read()).decode()
req = urllib.request.Request(
    "http://127.0.0.1:8083/api/detect",
    data=json.dumps({"image": img}).encode(),
    headers={"Content-Type": "application/json"},
)
print(urllib.request.urlopen(req).read().decode())
```

## 4. Mobile — after the demo compiles

Keep the **demo application ID** so the included license key license works. Call this on a **background** thread.

{% tabs %}
{% tab title="Android Face Recognition" %}

```kotlin
Thread {
    FaceRecognitionSDK.getMachineCode(context)
    var code = FaceRecognitionSDK.setActivation(context, "license key") // demo key from the repo
    if (code == FaceRecognitionSDK.SDK_SUCCESS) {
        code = FaceRecognitionSDK.init(context)
    }
    val faces = FaceRecognitionSDK.faceDetection(bitmap, FaceDetectionParam())
    val template = FaceRecognitionSDK.templateExtraction(bitmap, faces[0])
    val score = FaceRecognitionSDK.similarity(template, template)
}.start()
```

Install: [Face Recognition Android SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk.md).
{% endtab %}

{% tab title="Flutter Face Recognition" %}

```dart
import 'package:face_recognition_sdk/face_recognition_sdk.dart';

Future<void> tryOnce(String imagePath, String license) async {
  await getMachineCode();
  if (await setActivation(license) != sdkSuccess) return;
  if (await init() != sdkSuccess) return;
  final faces = await faceDetection(imagePath);
  final t1 = await templateExtraction(imagePath, faces.first);
  final t2 = await templateExtraction(imagePath, faces.first);
  final score = await similarity(t1, t2);
}
```

Install: [Face Recognition Flutter SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-flutter-sdk.md).
{% endtab %}

{% tab title="Android ID Document" %}

```kotlin
Thread {
    DocumentReaderSDK.getMachineCode(context)
    var code = DocumentReaderSDK.setActivation(context, "license key")
    if (code == DocumentReaderSDK.SDK_SUCCESS) {
        code = DocumentReaderSDK.init(context)
    }
    val json = DocumentReaderSDK.recognize(frontBitmap, null, "none")
}.start()
```

`locateDocument` is overlay-only (no OCR). Install: [ID Document Recognition Android SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-android-sdk.md).
{% endtab %}
{% endtabs %}

### Related documentation

* [HTTP API](/integration/http-api.md) · [Deploy and host](/integration/deploy-and-host.md) · [Choose a product](/getting-started/choose-a-product.md)
* [Glossary](/help/resources/glossary.md) · [Status codes](/help/resources/status-codes.md) · [Troubleshooting](/help/resources/troubleshooting.md)
* [Request a License](/help/request-a-license-and-support.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.faceplugin.com/getting-started/try-it.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.