Asynchronous Translation API Quick Guide

This is a brief introduction to Intento asynchronous Translation REST API.

The full REST API documentation is available at the links:

Translation Calls

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 an 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
    }
}'

The response contains the 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: 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
}

  • "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

Some of the errors may be different from the HTTP standard; hence, we recommend logging to look at both 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 to 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
    }
}'