Synchronous Prediction

The Synchronous Prediction endpoint is one of the two ways to extract information from your document in real time. Via HTTPS, you send your document (binary file, base64, or URL) and receive the prediction in the response body as a JSON.

🚧

Synchronous Prediction endpoint is not available for all document parsing APIs, instead, you may use the Asynchronous Prediction endpoint. Check your API Documentation on Mindee's Platform.

Send my document

URL

πŸ“˜

POST /predict

https://api.mindee.net/v1/products/mindee/<name>/<version>/predict

To make synchronous predictions, make sure your document parsing API supports synchronous mode, then select:

  • <name> refers to the name and selected version of your Off-the-shelf APIs.
  • <version> refers to the API version as described in your API Documentation. A new version may not be fully backward compatible and bring new features and better performance.

Prepare payload

The Prediction endpoint can handle three types of payload in order to send your document:

  • a binary file
  • a base64 encoded file
  • a URL

See Document inputs for more information on supported files.

Binary File

Use a multipart/form-data encoding to send your document:

import requests

url = "https://api.mindee.net/v1/products/mindee/<api_name>/<api_version>/predict"

with open("/path/to/my/file", "rb") as myfile:
    files = {"document": myfile}
    headers = {"Authorization": "Token <my-api-key-here>"}
    response = requests.post(url, files=files, headers=headers)
    print(response.text)
curl -X POST 
  https://api.mindee.net/v1/products/mindee/<api_name>/<api_version>/predict 
  -H 'Authorization: Token <my-api-key-here>'
  -F document=@/path/to/your/file.png
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;

class Program
{
    static void Main(string[] args)
    {
        var url = "https://api.mindee.net/v1/products/mindee/<api_name>/<api_version>/predict";
        var filePath = @"/path/to/my/file";
        var token = "my-api-key-here";

        var file = File.OpenRead(filePath);
        var streamContent = new StreamContent(file);
        var imageContent = new ByteArrayContent(streamContent.ReadAsByteArrayAsync().Result);
        imageContent.Headers.ContentType = MediaTypeHeaderValue.Parse("multipart/form-data");

        var form = new MultipartFormDataContent();
        form.Add(imageContent, "document", Path.GetFileName(filePath));

        var httpClient = new HttpClient();
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", token);
        var response = httpClient.PostAsync(url, form).Result;
        Console.WriteLine(response.Content.ReadAsStringAsync().Result);
    }
}

Base64 Encoded File

Prepare a JSON payload:

{
  "document": "/9j......"
}

Send your request with an application/json encoding:

curl -X POST \
  https://api.mindee.net/v1/products/mindee/<api_name>/<api_version>/predict \
  -H 'Authorization: Token <my-api-key-here>' \
  -H 'Content-Type: application/json' \
  -d 'document="/9j..."'

Public URL

Prepare a JSON payload with the URL included. Only valid public HTTPS links are accepted:

{
  "document": "https://mydomain.com/my_file.pdf"
}

Send your request with an application/json encoding:

curl -X POST \
  https://api.mindee.net/v1/products/mindee/<api_name>/<api_version>/predict \
  -H 'Authorization: Token <my-api-key-here>' \
  -H 'Content-Type: application/json' \
  -d '{"document":"https://mydomain.com/my_file.pdf"}'

Get my prediction

See Endpoints for general description of Mindee's REST API response format.

JSON Response

When calling the prediction endpoint, the parsed information from your documents can be found in the document key.

{
  "api_request": { .. }, 
  "document": {
    "id": "ac668055-e7db-48f2-b81f-e5ba9a6a6b8f",
    "name": "myfile.pdf",
    "n_pages": 2,
    "inference": {
      "started_at": "2021-03-24T09:14:27",
      "finished_at": "2021-03-24T09:14:28",
      "processing_time": 1.087,
      "is_rotation_applied": true,
      "extras": {},
      "prediction": { .. },
      "pages": [
        {
          "id": 0,
          "orientation": {"value": 0},
          "extras": {},
          "prediction": { .. }
        },
        {
          "id": 1,
          "orientation": {"value": 0},
          "extras": {},
          "prediction": { .. }
        }
      ]
    }
  }
}

Document

Describes the uploaded document

keytypedescription
idstringa unique identifier
namestringthe filename
n_pagesnumberthe number of pages
inferenceobjecta JSON object with the content of your inference (prediction)

Document > Inference

Contains the whole inference data (predictions)

keytypedescription
started_atstringthe date & time the inference has started in ISO 8601 format
finished_atstringthe date & time the inference was finished in ISO 8601 format
processing_timenumberthe request processing time in seconds
is_rotation_appliedboolean or nulltrue: polygons are already rotated given the page orientation
false: polygons are never rotated
null: the API has no orientation information
extrasobjecta JSON object with document-level extras predictions
predictionobjecta JSON object with the document-level API prediction
pageslist[object]a JSON object with the page-level inference data

Document > Inference > Pages[ ]

Contains the page-level specific inference data (predictions)

keytypedescription
idnumberthe page index
orientation.valuenumberthe clockwise rotation to apply to get the page upright
Examples: 0, 90, 180, 270
extrasobjecta JSON object with page-level extras predictions
Example: the Cropper feature
predictionobjecta JSON object with the page-level API prediction

Prediction example

Each API can describe several fields within its prediction object. Depending on the field properties, you will find values, a confidence score or polygons.

{
  "prediction": {
    "locale": {
      "country": "CA",
      "currency": "CAD",
      "language": "en",
      "value": "en-CA",
      "confidence": 0.85
    },
    "date": {
      "value": "2020-07-03",
      "confidence": 0.99,
      "polygon": [[0.273, 0.355], [0.289, 0.355], [0.289, 0.373], [0.273, 0.373]]
    },
    "total_incl": {
      "value": 14.32,
      "confidence": 0.98,
      "polygon": [[0.581, 0.485], [0.696, 0.485], [0.696, 0.503], [0.581, 0.503]]
    }
  }
}

πŸ‘

Success

To know more about your document parsing API response, especially the prediction object's structure, you can access the Documentation part of your API on Mindee's platform.

Β 

Questions?
Slack Logo IconΒ Β Join our Slack