Inference Sync

Synchronous inference is primarily intended for one or more of the following use cases:

• There is a need to process the data immediately
• There is no need to upload the document to the platform
• There is an external validation process for the extracted data
• No human intervention for validation is required

In the following section a description of expected request format is provided, along with a description of the endpoint’s response model.

Request

POST '/inference/service/:service_id:/predict'

curl --location 'https://platform.mybiros.com/api/inference/service/:service_id:/async-predict' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--form 'push_result_on_platform="never"' \
--form 'include_validation_errors="false"' \
--form 'file=@"/path/to/file"'

Parameters

Headers Parameters

x-api-key (required)

Type: string

A valid API key for the service.

Path Parameters

service_id (required)

Type: string

Identifier of the service.

Body Parameters

The accepted body content-type is multipart/form-data with the following parameters specified as form fields:

file (required)

Type: bytes

Bytes of the file to process.

push_result_on_platform (required)

Type: string
Allowed values: never | always | only_review

The value of this parameter determines if and when the document will be uploaded on Platform:

• never: predicted document will not be uploaded on platform
• always: predicted document will be always uploaded on platform
• only_review: this will trigger the validation policies execution and if any violation occurs then document will be uploaded on platform

include_validation_errors (optional)

Default: false
Type: boolean

If set to true, the result will be validated through the validation policies and any violations will be reported in the response.

Warning

Enabling or disabling validation policies will not affect in any case the behaviour of parameters: push_result_on_platform and include_validation_errors.

Info

For further information on supported file types, see Limits & Constraints

Info

For more information about validation policies, see Validation Policies

Responses

Successful Responses

The request was successful, and a JSON response is returned.

Status	Message	Description	Reference
200	OK	the request has succeeded.	Success Response 200

Status 200 - OK

JSON Response Example

    {
        "service": "<service-id>",
        "service_name": "Example Service",
        "service_fields": {
            "surname_1": {
                "tag_alias": "Surname",
                "tag_multiple_values": true
            },
            "name_1": {
                "tag_alias": "Name",
                "tag_multiple_values": true
            },
            "fiscal_code_1": {
                "tag_alias": "FiscalCode",
                "tag_multiple_values": false
            }
        },
        "current_date": "2024-04-26T11:21:58+00:00",
        "document": {
            "original_name": "health_card.jpg",
            "content_type": "image/jpeg",
            "page_count": 1
        },
        "document_pages": [
            {
                "page_index": 0,
                "page_layout": {
                    "height": 600,
                    "width": 1000,
                    "rotation_angle": 0
                },
                "ocr": [ ... ],
                "entities_index": 3,
                "entities": {
                    "surname_1": [
                        {
                            "id": 0,
                            "text": "VERDI",
                            "confidence": 99.43,
                            "bounding_boxes": [...]
                        }
                    ],
                    "name_1": [
                        {
                            "id": 1,
                            "text": "GIUSEPPE",
                            "confidence": 99.47,
                            "bounding_boxes": [...]
                            ]
                        }
                    ],
                    "fiscal_code_1": {
                            "id": 2,
                        "text": "VRDGPP13R10B293P",
                        "confidence": 90.97,
                        "bounding_boxes": [...]
                    }
                },
                "aggregated_entities": {},
                "policy_violations": [],
                "errors": []
            }
        ]
    }

Schema: Sync Inference Response

Key	Type	Description
service	string	the service identifier
service_name	string	the service name
service_fields	string	a JSON object containing info about service fields
current_date	object	datetime of when document has been processed in ISO 8601 format
document	object	a JSON object containing document info
document_pages	list [object]	a JSON list containing document page objects

Service Fields Deep Dive

For more informations about service_fields object visit Service Fields Object

---

Schema: Sync Inference Response > Document

Key	Type	Description
original_name	string	the original name of document
content_type	string	the content-type of document
page_count	integer	the number of pages in document

---

Schema: Sync Inference Response > Document Page

Key	Type	Description
page_index	integer	the index if page (starts from 0)
page_layout	object	a JSON object containing layout info
ocr	list [object]	a list of ocr objects
entities_index	integer	the last ID assigned to an entity
entities	object	a JSON object containing entities
aggregated_entities	object	a JSON object containing aggregated entities
policy_violations	list [object]	a list of policy violation objects
errors	list	a list of non fatal errors occurred while processing

Additional Information

• ocr: more info on Ocr Object
• entities: more info on Entities Object
• aggregated_entities: more info on Aggregated Entities Object

---

Error Responses

The request was unsuccessful, and a specific status code is returned to identify the error.

Status	Message	Description	Reference
401	Unauthorized	the server has not been able to authenticate the request.	Response 401
403	Forbidden	the service successfully authenticated the request but you are not allowed to perform the requested action.	Response 403
404	Not Found	the server could not locate the requested resource.	Response 404
422	Unprocessable Content	the server has not been able to process the content of the request.	Response 422
429	Too Many Requests	the client has sent too many requests in a short period, exceeding the rate limit. Please try again later.	Response 429

500	Internal Server Error	the server encountered an unexpected and unrecoverable error while processing the request.	Response 500
503	Service Unavailable	the server could be under maintenance for an update. Will be back soon.	Response 503

Status 401 - Unauthorized

The current endpoint is protected and requires an API key to be accessed. If sufficient privileges are not present, the request will not be authorized.

Tip

Double-check that the API Key is correct, valid and set using the x-api-key header in the request. Also make sure that you are using the right API key for the service you are requesting and that the service ID in it is correct and corresponds to the ID of an existing service in your account.

Status 403 - Forbidden

The server has denied the request because the user is not allowed to perform the required action. This happens when the user has exceeded the allowed quota defined in their usage plan.

Tip

You can monitor service usage on the Platform's web interface.

Status 404 - Not Found

The service ID provided does not exist or could not be found. Please verify the ID and try again.

Status 422 - Unprocessable content

This status code indicates that the server successfully received and understood the request, but it cannot process it due to errors in the provided data. These errors may include missing fields, invalid formats, or values that do not meet the endpoint requirements.

Tip

Double-check your request's payload format and parameters

Status 429 - Too Many Requests

This status code is returned when the client has made too many requests in a given timeframe, exceeding the rate limits set by the server. It indicates that the client needs to slow down and retry after a specified cooldown period. Rate limits are typically enforced to protect the server from being overwhelmed and to ensure fair use of resources.

Status 500 - Internal Server Error

This status code indicates that the server encountered an unexpected error or condition that prevented it from completing the request. It is a generic error message when no more specific message is suitable. The client cannot resolve the issue.

Status 503 - Service Unavailable

This status code indicates that the server is currently unavailable, typically due to ongoing maintenance or temporary overloading. The server is unable to handle the request at the moment, but the issue is expected to be resolved shortly. This status code signals that the downtime is temporary, and the service will be restored once maintenance is complete.