Train with API

When working with the API Builder, you need to upload documents in order to train your endpoint. You can either use our Training interface or Mindee REST API to do so. This page explains the two scenarios and steps to use Mindee REST API.

Scenario 1
I want to upload documents via API but use the training interface for annotation

Upload your document
Use the training interface on Mindee Platform

Scenario 2
I want to upload documents via API and send my annotations via API

Upload your document & get the candidates
Make your annotations from the candidates
Upload your annotations

Scenario 1: upload documents via API and use the training interface

1. Upload your document

Use the Prediction endpoint with an additional URL parameter training=true.

Example:

POST https://api.mindee.net/v1/products/<account_name>/<api_name>/v1/predict?training=true

2. Use the training interface

Once uploaded, the document will be available on the platform Training interface. Go to your endpoint training page, you can use normally the interface for the annotation and training process.

Scenario 2: upload documents and send annotations via API

1. Upload your document and get the candidates

Use the Prediction endpoint with additional parameters. Add both URL parameters training=true and with_candidates=true . Once uploaded, the document will be available on the platform but you will also have received the additional candidates payload required to craft your annotations on your side. You also need to save the document ID found in the document.id JSON response.

Example:

POST https://api.mindee.net/v1/products/<account_name>/<api_name>/v1/predict?training=true&with_candidates=true

2. Make your annotations from the candidates

Use the candidates payload found in your json response to annotate your document and prepare your final label.

Classification fields

These classification field candidates work at the document level and contain for each field a list of all classes that were defined when the API was created.

Candidates Location

document.inference.extras.candidates.classification

Candidates Example

{
  "classification": {
    "color": ["red", "green", "blue"],
    "size": ["short", "medium", "large"],
     ...
  }
}

Annotation Format

{
  "feature": "color",
  "class": "red"
}

Extraction fields

These extraction field candidates work at the page level and contain for each field a list of boxes with:

the key, a unique identifier of the box
the content, the box content (a string, a number, a date… etc)
the polygon, the box coordinates

Candidates Location

document.inference.page[ ].extras.candidates.extraction

Candidates Example

{
  "extraction": {
    "my_text_field": [
      {
        "content": "Bob",
        "key": "d3fb58c1",
        "polygon": [[0.518, 0.067], [0.555, 0.067], [0.555, 0.077], [0.518, 0.077]]
      },{
        "content": "Marley",
        "key": "e2ba57c3",
        "polygon": [[0.612, 0.087], [0.671, 0.087], [0.671, 0.092], [0.612, 0.092]]
      },
      ...
    ],
    "my_number_field": [
      {
        "content": 105.87,
        "key": "c7ba79d2",
        "polygon": [[0.241, 0.063], [0.334, 0.064], [0.334, 0.073], [0.242, 0.072]]
      },
      ...
    ],
    ...
  }
}

Annotation Format

{
  "feature": "my_text_field",
  "page_id": 0,
  "selected": ["d3fb58c1", "e2ba57c3"]
}

3. Send the annotations

Prepare a final JSON payload that must contain all your annotations for each field:

Example:

{
  "labels": [
    {
      "feature": "color",
      "class": "red"
    },
    {
      "feature": "my_text_field",
      "page_id": 0,
      "selected": ["d3fb58c1", "e2ba57c3"]
    }, {
      "feature": "my_number_field",
      "page_id": 0,
      "selected": ["c7ba79d2"]
    }
  ]
}

Send it to the Mindee API Annotations endpoint with your API key:

POST https://api.mindee.net/v1/products/<account_name>/<api_name>/v1/documents/<document_id>/annotations

You can also edit & replace your document annotations by using the PUT route or remove it via the DELETE route.

Questions?
Join our Slack