Quick Start

Quickest way to get started using the client libraries.

Installation Instructions

Python

Requires Python ≥ 3.9. Python ≥ 3.10 is highly recommended.

Simply install the PyPi package using pip:

pip install mindee>=4.27.1

Node.js

Requires Node.js ≥ 20. Node.js ≥ 22 is recommended.

Simply install the NPM package:

npm install [email protected]

PHP

Requires PHP ≥ 8.0. PHP ≥ 8.3 is recommended.

Simply install the Packagist package using composer:

php composer.phar require "mindee/mindee:>=1.23"

If you get an error message like this:

found mindee/mindee[v1.23.0-rc2] but it does not match your minimum-stability.

You'll need to configure your composer settings to allow installing an RC version:

php composer.phar config minimum-stability RC
php composer.phar config prefer-stable true

Ruby

Requires Ruby ≥ 3.0. Simply install the gem using:

gem install mindee --pre

Java

Requires Java ≥ 8. Java ≥ 11 is highly recommended.

Group ID: com.mindee.sdk Artifact ID: mindee-api-java Version:

There are various installation methods, Maven, Gradle, etc:

Installation Details

.NET

Requires .NET ≥ 6.0. .NET ≥ 8.0 is recommended.

Simply install the NuGet package using .NET CLI:

dotnet add package Mindee --version 3.30

Don't see support for your favorite language or framework? Make a feature request!

Send a File and Poll

Make a note of your model's ID for use in the API.

When getting started, we recommend using the polling method which will be quickest (unless you happen to already have access to a public-facing Web server).

Here are basic code examples, these are self-contained and can be run as-is:

Python

Requires Python ≥ 3.9. Python ≥ 3.10 is highly recommended. Requires the Mindee Python client library version 4.27.1 or greater.

from mindee import ClientV2, InferenceParameters

input_path = "/path/to/the/file.ext"
api_key = "MY_API_KEY"
model_id = "MY_MODEL_ID"

# Init a new client
mindee_client = ClientV2(api_key)

# Set inference parameters
params = InferenceParameters(
    # ID of the model, required.
    model_id=model_id,
    # If set to `True`, will enable Retrieval-Augmented Generation.
    rag=False,
)

# Load a file from disk
input_source = mindee_client.source_from_path(input_path)

# Send for processing using polling
response = mindee_client.enqueue_and_get_inference(
    input_source, params
)

# Print a brief summary of the parsed data
print(response.inference)

Node.js

Requires Node.js ≥ 20. Node.js ≥ 22 is recommended. Requires the Mindee Node.js client library version 4.29.0-rc6 or greater.

const mindee = require("mindee");
// for TS or modules:
// import * as mindee from "mindee";

const apiKey = "MY_API_KEY";
const filePath = "/path/to/the/file.ext";
const modelId = "MY_MODEL_ID";

// Init a new client
const mindeeClient = new mindee.ClientV2({ apiKey: apiKey });

// Set inference parameters
const inferenceParams = {
  modelId: modelId,
  // If set to `true`, will enable Retrieval-Augmented Generation.
  rag: false
};

// Load a file from disk
const inputSource = new mindee.PathInput({ inputPath: filePath });

// Send for processing using polling
const response = mindeeClient.enqueueAndGetInference(
  inputSource,
  inferenceParams
);

// Handle the response Promise
response.then((resp) => {
  // print a string summary
  console.log(resp.inference.toString());
});

PHP

Requires PHP ≥ 8.0. Requires the Mindee PHP client library version 1.23.0-rc2 or greater.

<?php

use Mindee\ClientV2;
use Mindee\Input\InferenceParameters;
use Mindee\Input\PathInput;
use Mindee\Error\MindeeException;

$apiKey = "MY_API_KEY";
$filePath = "/path/to/the/file.ext";
$modelId = "MY_MODEL_ID";

// Init a new client
$mindeeClient = new ClientV2($apiKey);

// Set inference parameters
// Note: modelId is mandatory.
$inferenceParams = new InferenceParameters(
    $modelId,
    // If set to `true`, will enable Retrieval-Augmented Generation.
    false
);

// Load a file from disk
$inputSource = new PathInput($filePath);

// Send for processing using polling
$response = $mindeeClient->enqueueAndGetInference(
    $inputSource,
    $inferenceParams
);

// Print a summary of the response
echo strval($response->inference);

Ruby

Requires Ruby ≥ 3.0. Requires the Mindee Ruby client library version 4.7.0.pre.rc2 or greater.

require 'mindee'

input_path = '/path/to/the/file.ext'
api_key = 'MY_API_KEY'
model_id = 'MY_MODEL_ID'

# Init a new client
mindee_client = Mindee::ClientV2.new(api_key: api_key)

# Set inference parameters
inference_params = Mindee::Input::InferenceParameters.new(
    # ID of the model, required.
    model_id,
    # If set to `true`, will enable Retrieval-Augmented Generation.
    rag: false,
)

# Load a file from disk
input_source = Mindee::Input::Source::PathInputSource.new(input_path)

# Send for processing using polling
response = mindee_client.enqueue_and_get_inference(
    input_source,
    inference_params # Note: this parameter can also be provided as a Hash.
)

# Print a brief summary of the parsed data
puts response.inference

Java

Requires Java ≥ 8. Java ≥ 11 recommended. Requires the Mindee Java client library version 4.33.0 or greater.

import com.mindee.MindeeClientV2;
import com.mindee.InferenceParameters;
import com.mindee.input.LocalInputSource;
import com.mindee.parsing.v2.InferenceResponse;
import java.io.File;
import java.io.IOException;

public class SimpleMindeeClient {

  public static void main(String[] args)
      throws IOException, InterruptedException
  {
    String filePath = "/path/to/the/file.ext";
    String apiKey = "MY_API_KEY";
    String modelId = "MY_MODEL_ID";

    // Init a new client
    MindeeClientV2 mindeeClient = new MindeeClientV2(apiKey);

    // Set inference parameters
    // Note: modelId is mandatory.
    InferenceParameters options = InferenceParameters.builder(modelId)
        // If set to `true`, will enable Retrieval-Augmented Generation.
        .rag(false)
        .build();

    // Load a file from disk
    LocalInputSource inputSource = new LocalInputSource(
        new File(filePath)
    );

    // Send for processing using polling
    InferenceResponse response = mindeeClient.enqueueAndGetInference(
        inputSource,
        options
    );

    // Print a summary of the response
    System.out.println(response.getInference().toString());
  }
}

.NET

Requires .NET ≥ 6. Requires the Mindee .NET client library version 3.30 or greater.

using Mindee;
using Mindee.Input;

string filePath = "/path/to/the/file.ext";
string apiKey = "MY_API_KEY";
string modelId = "MY_MODEL_ID";

// Construct a new client
MindeeClientV2 mindeeClient = new MindeeClientV2(apiKey);

// Set inference parameters
var inferenceParams = new InferenceParameters(
    modelId: modelId
    // If set to `true`, will enable Retrieval-Augmented Generation.
    , rag: false
);

// Load a file from disk
var inputSource = new LocalInputSource(filePath);

// Send for processing using polling
var response = await mindeeClient.EnqueueAndGetInferenceAsync(
    inputSource, inferenceParams);

// Print a summary of the response
System.Console.WriteLine(response.Inference.ToString());

Details on Sending

For details on available options and advanced usage, check the following sections:

• Configure the Client

• Load and Adjust a File

• Send a File or URL

Processing the Results

Once you've sent the file and retrieved the results, you can start extracting the JSON payload.

The model's fields will be in the fields object in the returned JSON, in the response variable returned from the above step.

Each key in the fields object corresponds to the field's name in your model configuration.

You'll want to adapt your processing depending on the type of field, for example looping over lists.

Python

Accessing a simple value, where my_simple_field is the name of the field in the Model.

my_simple_field = response.inference.result.fields["my_simple_field"]
field_value = my_simple_field.value

Accessing a list of values, where my_list_field is the name of the field in the Model.

my_list_field = response.inference.result.fields["my_list_field"]

# access a value at a given position
field_first_value = my_list_field.items[0].value

# loop over all values in the list
for list_item in my_list_field:
    item_value = list_item.value

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

object_field = response.inference.result.fields["my_object_field"]
sub_field_value = object_field.fields["sub_field"].value

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

object_list_field = response.inference.result.fields["my_object_list_field"]

# access an object at a given position
object_item_0 = object_list_field.items[0]
sub_field_0_value = object_item_0["sub_field"].value

# loop over object lists
for object_item in object_list_field.items:
  sub_field_value = object_item.fields["sub_field"].value

Node.js

Accessing a simple value, where my_simple_field is the name of the field in the Model.

const mySimpleField = response.inference.result.fields.my_simple_field;
const fieldValue = mySimpleField.value;

Accessing a list of values, where my_list_field is the name of the field in the Model.

const myListField = response.inference.result.fields.my_list_field;

// access a value at a given position
const fieldFirstValue = myListField.items[0].value;

// loop over all values in the list
for (const listItem of myListField) {
    const itemValue = listItem.value;
}

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

const objectField = response.inference.result.fields.my_object_field;
const subFieldValue = objectField.fields.sub_field.value;

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

const objectListField = response.inference.result.fields.my_object_list_field;

// access an object at a given position
const objectItem0 = objectListField.items[0];
const subField0Value = objectItem0.sub_field.value;

// loop over object lists
for (const objectItem of objectListField.items) {
    const subFieldValue = objectItem.fields.sub_field.value;
}

PHP

Accessing a simple value, where my_simple_field is the name of the field in the Model.

$inferenceFields = $response->inference->result->fields;
$mySimpleField = $inferenceFields["my_simple_field"];
$field_value = $mySimpleField->value;

Accessing a list of values, where my_list_field is the name of the field in the Model.

$inferenceFields = $response->inference->result->fields;
$myListField = $inferenceFields["my_list_field"];

// access a value at a given position
$fieldFirstValue = $myListField[0]->value;

// loop over all values in the list
foreach ($myListField->items as $listItem) {
    $itemValue = $listItem->value;
}

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

$inferenceFields = $response->inference->result->fields;
$objectField = $inferenceFields["my_object_field"];
$subFieldValue = $objectField["sub_field"]->value;

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

$inferenceFields = $response->inference->result->fields;
$myObjectListField = $inferenceFields["my_object_list_field"];

// access an object at a given position
$objectItem0 = $myObjectListField->items[0];
$subField0Value = $objectItem0["sub_field"]->value;

// loop over object lists
foreach ($myObjectListField->items as $objectItem) {
    $subFieldValue = $objectItem["sub_field"]->value;
}

Ruby

Accessing a simple value, where my_simple_field is the name of the field in the Model.

my_simple_field = response.inference.fields['my_simple_field']
field_value = my_simple_field.value

Accessing a list of values, where my_list_field is the name of the field in the Model.

my_list_field = response.inference.fields['my_list_field']

# access a value at a given position
field_first_value = my_list_field[0]["value"]
# Note: Here `value` could be another subfield attribute, since my_list_field[0] can be an `ObjectField`.

# loop over all values in the list
my_list_field.each do |list_item|
  item_value = list_item["value"]
end

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

object_field = response.inference.fields["my_object_field"]
sub_field_value = object_field["sub_field"]["value"]

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

object_list_field = result.inference.fields["my_object_list_field"]

# access an object at a given position
object_item_0 = object_list_field[0]
sub_field_0_value = object_item_0["sub_field"]["value"]

# loop over object lists
object_list_field.each do |object_item|
  sub_field_value = object_item["sub_field"]["value"]
end

Java

Accessing a simple value, where my_simple_field is the name of the field in the Model.

We need to access the field as a SimpleField instance in order to access its value.

We also need to specify the type of value , the possible types are String , Boolean , Double . Notice that these are all classes, not primitives: this is to allow null values.

import com.mindee.parsing.v2.field.*;


InferenceFields fields = response.getInference().getResult().getFields();
SimpleField mySimpleField = fields.get("my_simple_field").getSimpleField();

// Showing a String field example.
// You'll need to choose one of the possible classes:
// String, Double, Boolean
String fieldValue = (String) mySimpleField.getValue();

Accessing a list of values, where my_list_field is the name of the field in the Model.

We need to specify that the field is a ListField in order to access its items.

For each item in the list, we also need to specify the correct field and value type, as described above.

import com.mindee.parsing.v2.field.*;


InferenceFields fields = response.getInference().getResult().getFields();
ListField myListField = fields.get("my_list_field").getListField();

List<DynamicField> myListFieldItems = fieldSimpleList.getItems();

// Access a value at a given position
// Showing a String field example, other types are: String, Double, Boolean
String fieldFirstValue = (String) simpleItems.get(0).getSimpleField().getValue()

// loop over all values in the list
for (DynamicField listItem : myListFieldItems) {

    // Showing a String field example, other types are: String, Double, Boolean
    String itemValue = (String) listItem.getValue();
}

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

import com.mindee.parsing.v2.field.*;


InferenceFields fields = response.getInference().getResult().getFields();
ObjectField objectField = fields.get("my_object_field").getObjectField()

// Useful to separate out the fields mapping for easier access
InferenceFields fieldObjectFields = objectField.getFields();

// The subfield is handled like any other SimpleField
SimpleField subField = fieldObjectFields.get("sub_field").getSimpleField();

// Showing a String field example, other types are: String, Double, Boolean
String itemValue = (String) subField.getSimpleField().getValue();

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

import com.mindee.parsing.v2.field.*;


InferenceFields fields = response.getInference().getResult().getFields();
ListField objectListField = fields.get("my_object_list_field").getListField();

// Useful to separate out the fields list for easier access
List<DynamicField> objectItems = fieldSimpleList.getItems();

// access an object at a given position
ObjectField objectField0 = objectItems.get(0).getObjectField();
SimpleField subField0 = objectField0.getFields().get("sub_field").getSimpleField();
// Showing a String field example, other types are: String, Double, Boolean
String subField0Value = (String) subField0.getValue();

for (DynamicField objectItem : objectItems.getItems()) {
    ObjectField objectField = objectItem.getObjectField();
    SimpleField subField = objectField.getFields().get("sub_field").getSimpleField();
    // Showing a String field example, other types are: String, Double, Boolean
    String subFieldValue = (String) subField.getValue();
}

Depending on your requirements, this can be simplified using various custom methods.

.NET

Accessing a simple value, where my_simple_field is the name of the field in the Model.

We need to specify that the field is a SimpleField in order to access its Value.

var mySimpleField = response.Inference.Result.Fields["my_simple_field"];
var fieldValue = mySimpleField.SimpleField.Value;

Accessing a list of values, where my_list_field is the name of the field in the Model.

We need to specify that the field is a ListField in order to access its Items.

var myListField = response.Inference.Result.Fields["my_list_field"];

// access a value at a given position
var fieldFirstValue = myListField.ListField.Items[0].SimpleField.Value;

// loop over all values in the list
foreach (var listItem in myListField.ListField.Items)
{
    var itemValue = listItem.SimpleField.Value;
}

Accessing an object field, where my_object_field is the name of the field in the Model. In this hypothetical case, the object has a sub-field named sub_field .

var objectField = response.Inference.Fields["my_object_field"];
var subField = objectField.ObjectField.Fields["sub_field"];
var subFieldValue = subField.SimpleField.Value;

Accessing a list of objects, where my_object_list_field is the name of the field in the Model.

objectListField = response.Inference.Fields["my_object_list_field"];

// access an object at a given position
var objectItem0 = objectListField.ListField.Items[0];
var subField0Value = objectItem0.ObjectField.Items["sub_field"].Value;

// loop over object lists
foreach (var objectItem in objectListField.ListField.Items) {
    var subField = objectItem.ObjectField.Fields["sub_field"];
    var subFieldValue = subField.SimpleField.Value;
}

Details on Processing

For details on available options and advanced usage, check the following sections:

• Process the Result