This is a brief introduction to Intento asynchronous HTTP API, which we hope helps you jumpstart the integration.
The full HTTP API documentation is available here: https://github.com/intento/intento-api/ and https://github.com/intento/intento-api/blob/master/ai.text.translate.md.
Asynchronous API
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 the provider, assembles the response, and returns the translation result in one batch. Here’s an example:
curl --location 'https://api.inten.to/ai/text/translate' \
--header 'Content-Type: application/json' \
--header 'apikey: <YOUR_API_KEY>' \
--data '{
"context": {
"text": [
"Large text corpus",
"of text to translate"
],
"to": "es",
"from": "en"
},
"service": {
"routing": "best",
"async": true
}
}'
{"id": "80fab22b-f999-421f-9ac4-c0b7e55a2158"}
Please replace <YOUR_API_KEY> with your API key.
Please also note async
is true in the service
section for asynchronous calls.
The response contains the ID of the operation (please note that the ID value here is just an example and will differ from the ID you’d actually receive in response)
To retrieve the result of the operation, make a request:
curl --location 'https://api.inten.to/operations/80fab22b-f999-421f-9ac4-c0b7e55a2158' \
--header 'apikey: <YOUR_API_KEY>'
We recommend checking for operation completeness approximately once a second. You’d see the following response while the request is incomplete:
{
"done": false,
"error": null,
"id": "80fab22b-f999-421f-9ac4-c0b7e55a2158",
"meta": {},
"response": []
}
Once the operation is complete, the service returns the translated text:
{
"id": "80fab22b-f999-421f-9ac4-c0b7e55a2158",
"done": true,
"response": [
{
"results": [
"Corpus de texto grande",
"de texto a traducir"
],
"meta": {
"detected_source_language": [
"en",
"en"
],
"size_info": {
"symbols": 37,
"provider_symbols": 37
},
"routing": {
"id": "best"
},
"client_key_label": "production"
},
"service": {
"provider": {
"id": "ai.text.translate.amazon.translate",
"name": "Amazon Translate",
"timing": {
"provider": 0.121953
},
"vendor": "Amazon",
"description": "Translate",
"logo": "https://inten.to/img/api/aws.png"
}
}
}
],
"meta": {
"providers": [
{
"id": "ai.text.translate.amazon.translate",
"name": "Amazon Translate",
"timing": {
"provider": 0.121953
},
"vendor": "Amazon",
"description": "Translate",
"logo": "https://inten.to/img/api/aws.png"
}
],
"from": "en",
"to": "es",
"format": null,
"glossary": null,
"smart_routing": "default",
"category": "default",
"own_keys": false,
"size": 37,
"intento_user_agent": [],
"userdata": {},
"user_key_label": "production",
"is_trace": false
},
"error": null
}
Please note that done
is true (meaning that the request is complete), and the error
is 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 cases, 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.
Syncwrapper API
In cases when Asynchronous API is not suitable, and for smaller texts up to 10,000 symbols total, there’s SyncWrapper API which wraps async calls into synchronous calls. It offers a similar interface as Async API:
curl --location 'https://syncwrapper.inten.to/ai/text/translate' \
--header 'apikey: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"context": {
"text": [
"Large text corpus",
"of text to translate"
],
"to": "es",
"from": "en"
},
"service": {
"routing": "best"
}
}'
In the response, you will synchronously receive the translated text along with service information regarding the MT provider, glossary, etc.:
{
"results": [
"Corpus de texto grande",
"de texto a traducir"
],
"meta": {
"detected_source_language": [
"en",
"en"
],
"size_info": {
"symbols": 37,
"provider_symbols": 37
},
"routing": {
"id": "best"
},
"client_key_label": "production"
},
"service": {
"provider": {
"id": "ai.text.translate.amazon.translate",
"name": "Amazon Translate",
"timing": {
"provider": 0.339526
},
"vendor": "Amazon",
"description": "Translate",
"logo": "https://inten.to/img/api/aws.png"
}
},
"id": "d61107ee-ab54-47e7-bf07-4e1a67648d57",
"request_id": "10.121.3.23-8000-1-48774726-1-1686570996.354"
}
Errors
Error codes for Intento API are described here:
https://github.com/intento/intento-api#errors
Please note that some of the error codes may have different meanings than the HTTP standard; thus, we recommend logging both the error code and the message to identify the error.
Technical Support
By default, Intento API works in the “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 enable the payload logging to provide more information to our support team.
This is done using the trace: true parameter as follows:
curl --location 'https://api.inten.to/ai/text/translate' \
--header 'Content-Type: application/json' \
--header 'apikey: <YOUR_API_KEY>' \
--data '{
"context": {
"text": [
"Large text corpus",
"of text to translate"
],
"to": "es",
"from": "en"
},
"service": {
"routing": "best",
"trace": true
}
}'
Smart routing
Intento provides the smart routing feature so that the translation request is automatically routed to the best provider. The best provider is determined based on the following information:
- apriori benchmark on the standard dataset
- provider usage statistics, collected by Intento, including user feedback signals (the post-editing complexity for Machine Translation).
Basic smart routing
To use the smart routing, just omit the service.provider
parameter:
curl --location 'https://api.inten.to/ai/text/translate' \
--header 'apikey: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"context": {
"text": "A sample text",
"to": "es"
}
}'
Response:
{
"results": [
"Un ejemplo de texto"
],
"meta": {
"detected_source_language": [
"en"
],
"size_info": {
"provider_symbols": 13,
"symbols": 13
},
"routing": {
"id": "best"
},
"timing": {
"total": 0.3851,
"providers": 0.257487
},
"client_key_label": "production"
},
"service": {
"provider": {
"id": "ai.text.translate.deepl.api.v2",
"name": "DeepL API v2",
"timing": {
"provider": 0.257487
}
},
"id": "ebf7a6"
}
}
Specifying the smart routing strategy
By default, when the provider is missing, requests are routed to a provider with the best-expected price/performance ratio. This behavior may be controlled by specifying the desired routing strategy in service.routing
parameter.
curl --location 'https://api.inten.to/ai/text/translate' \
--header 'apikey: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"context": {
"text": "A sample text",
"to": "es"
},
"service": {
"routing": "best_colloquial"
}
}'
For questions and technical issues, please contact us:
- via Portal (https://help.inten.to/hc/en-us/requests/new)
- via support@inten.to
Happy Intento API integration!