Asynchronous Translation API quick guide

This is a brief introduction to Intento asynchronous Translation REST API, the full REST API documentation is available by the links: https://github.com/intento/intento-api and https://github.com/intento/intento-api/blob/master/ai.text.translate.md

Translation calls

In order to promptly translate large amounts of text it’s recommended to leverage asynchronous calls of Intento API. You’d feed all segments of text in one batch to async call, API splits them in chunks, performs multiple translate calls with a provider, assembles the response, and returns your translation result in one batch. Here’s the example:

curl -XPOST -H 'apikey: <YOUR_API_KEY>' 'https://api.inten.to/ai/text/translate' -d '{
    "context": {
        "text": [
           "Large text corpus"
        ],
        "to": "es",
        "from": "en"
    },
    "service": {
        "routing":"<YOUR_ROUTING_NAME>",
        "async": true
    }
}'

Please replace <YOUR_API_KEY> with your Production Key that is available at https://console.inten.to/dashboard.

Please replace <YOUR_ROUTING_NAME> with your smart routing name.

Please note “async”: true in the service section.

The response contains id of the operation (please note that id value here is just an example and will differ from id you’d actually receive in response):

{
    "id": "XXXX-YYYY-ZZZZ"
} 

To retrieve the result of the operation, make a GET request to the https://api.inten.to/operations/<YOUR_OPERATION_ID>. We recommend checking if the operation is complete approximately one time per second.

You’d see the following response while the request is not complete:

{
    "id": "XXXX-YYYY-ZZZZ",
    "done": false,
    "response": null,
    "error": null
}            

Once the operation is complete, the request returns the translated text:

{
    "id": "XXXX-YYYY-ZZZZ",
    "done": true,
    "response": [
    {
       "results": [
           "Translated large text corpus"
       ],
       "meta": {},
       "service": {
           "provider": {                    
           "routing":"<YOUR_ROUTING_NAME>",
           }
        }
    ],
    "error": null
}

Please note that "done": true (meaning that the request is complete) and "error": null (no errors during translation).

In some cases, the translation may return partial results (e.g. if the MT provider has a persistent failure). In such a case, information about the errors will be in the error field as per Intento API documentation. Please make sure you log all error codes and messages, to ensure quick issue resolution.

Errors

Error codes for Intento API are described here: https://github.com/intento/intento-api#errors

Please note that some of the errors may be different from the HTTP standard, hence we recommend logging look both at the error code and message to identify the error reason.

Technical Support

By default, Intento API works in “no trace” mode, with no payload stored on the Intento side. Even temporary translation results are not accessible by Intento employees.

If you have a reproducible error when using the Intento API and require technical support, we recommend you to enable the payload logging to provide more information to our support team.

This is done using "trace": true parameter as follows:

curl -XPOST -H 'apikey: <YOUR_API_KEY>' 'https://api.inten.to/ai/text/translate' -d '{
    "context": {
        "text": [
           "Large text corpus"
        ],
        "to": "es",
        "from": "en"
    },
    "service": {
        "routing":"<YOUR_ROUTING_NAME>",
        "async": true,
        "trace": true
    }
}'