The ModelFront translation risk prediction API predicts the risk of machine translations.
The API gives sentence levels scores and supports batching. If an engine is requested and a translation is not included, the API automatically provides a translation from that engine.
The ModelFront translation risk prediction service base endpoint URL is https://api.modelfront.com
. The only currently available version is v1
, and the only supported method is predict
.
To get your API access token, create an account on console.modelfront.com and click on API.
predict
POST https://api.modelfront.com/v1/predict?sl={ sl }&tl={ tl }&token={ token }&model={ model }
<style>
table, th, td {
border-collapse: collapse;
border: 1px solid lightgray;
padding: 1em;
min-width: 3em;
}
td:nth-child(1), td:nth-child(2) {
font-weight: bold;
white-space: nowrap
}
td:nth-child(3) {
color: gray
}
table {
margin-top: 1em;
margin-bottom: 2em;
}
pre {
padding: 1em;
padding-left: 1em;
margin-top: 1em;
margin-bottom: 1em;
}
sup {
color: lightgray;
}
.optional {
font-weight: normal !important;
}
sl |
string | required | The source language code |
tl |
string | required | The target language code |
token |
string | required | Your access token |
model |
string | optional | Your custom model with which to perform risk prediction |
engine |
string | optional | The engine with which to translate if no translation is provided |
custom_engine_id |
string | optional | The custom engine with which to translate. |
engine_key |
string | optional | The engine key to use. This is required for some custom engines. |
sl
and tl
should be among the ModelFront supported languages. model
should be the identifier of your custom model. engine
should be from the ModelFront supported engines.
{
"rows": [
{
"original": string,
"translation": string
}
]
}
rows |
{row}[] | required | The list of row objects |
{row}.original |
string | required | The original text |
{row}.translation |
string | optional | The translated text to be scored |
metadata |
{} | optional | The metadata object |
For optimal performance, requests should send batches of multiple rows. A single request can include up to 30 rows.
For optimal predictions, every row should include at most one full sentence and no more than 500 characters in original
and translation
.
{
"status": "ok"|...,
"rows": [
{
"risk": number,
"translations": string
},
...
]
}
A risk
is a floating point number with a value from 0.0 to 1.0. It can be parsed by JavaScript parseFloat()
or Python float()
.
A language code must be a valid ISO 639-1 code or ISO 639-2 code.
For example, for English, the correct code is en
, and the 3-letter code eng
is equivalent to en
. For languages like Cebuano or Alemannic, there is no ISO 639-1 code, so you must use the ISO-639-2 code like ceb
or als
.
For most languages, the locale or variant is reduced to the raw language code for the purposes of risk prediction.
For example, en-GB
and en-ZA
are equivalent to en
.
There are two main exceptions:
If the request does not include the translation and instead includes the engine
option, then the locale will be passed to the machine translation engine if it supports that locale. For example, DeepL supports en-UK
.
If the language is Chinese, then risk. You can select the Traditional script with zh-Hant
or with the locales zh-tw
, zh-hk
or zh-mo
. The script code Hant
or Hans
takes precedence over the country code. The default for zh
is the Simplified script.
ModelFront supports more than a hundred languages. If a language is unsupported, you can try the codes of related languages or macrolanguages that are supported, or use und
.
Requests can include a translation, or select a translation engine to have them filled in.
google |
Custom translation with custom_engine_id |
|
Microsoft | microsoft |
Custom translation with custom_engine_id |
DeepL | deepl |
No custom translation |
ModernMT | modernmt |
Custom translation with custom_engine_id and engine_key . |
If translation is already included in a row, the engine will not be used.
You can get the identifier and deployment state of your custom models in the console API tab.
If no model is provided, the default base model is used.
If your model supports metadata, you can pass the metadata object in the request.
{
"rows": [ ... ],
"metadata": { ... }
}
The keys and values should be based on the keys and values used in the training data.
In the case of invalid path or malformed request, the default FastAPI validation error handling will return an HTTP status code in the range 4xx
and a response of the form:
{ "detail": ... }
In case of an error in the request values or on the server, the ModelFront API returns a FastAPI UJSONResponse with a specific HTTP status code and a response of the form:
{
"status": "error",
"message": "..."
}
400
When the body is malformed or the parameters like sl
, tl
, engine
and model
are missing, invalid or in an invalid combination
401
When the authentication token is missing or invalid
402
When a payment or contract is required
419
When the requested model
is unavailable, typically because it is undeployed
429
When there are too many requests from the same IP address
424
When the external machine translation API for the requested engine
has returned an error
503
When a model, including the default model, is temporarily unavailable
500
When there is any other error
First set an environment variable with your token on your local system.
export MODELFRONT_TOKEN=<your access token>
Don't have a token? Sign up to the console!
Then send a request.
curl \
--header "Content-Type: application/json" --request POST \
--data '{ "rows": [ {"original": "This is not a test.", "translation": "Esto no es una prueba."} ] }' \
"https://api.modelfront.com/v1/predict?sl=en&tl=es&token=$MODELFRONT_TOKEN"
// npm install request
const util = require('util')
const request = util.promisify(require("request"));
const url = `https://api.modelfront.com/v1/predict?sl=en&tl=es&token=${ process.env.MODELFRONT_TOKEN }`;
const body = {
rows: [
{
original: "This is not a test.",
translation: "Esto no es una prueba."
}
]
};
(async () => {
const response = await request({
url,
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Accept-Charset': 'utf-8' },
json: true,
body
});
console.log(response.body);
})();
The response you receive should be:
{
"status": "ok",
"rows": [
{
"risk": 0.0028
}
]
}
If you want to send a million lines programmatically, you should stream by sending sending batch requests sequentially. You can send a few in parallel, but do not send a million lines at once.
If you require dedicated GPUs, large batches, accelerated autoscaling or on-prem models, contact us.
You can also simply use the console to run an evaluation on very large files. It handles retrying with exponential backoff.
If you want to reduce latency, you should probably still send batch requests. You can reduce latency by sending requests from near or within Google datacenters in North America and Western Europe.
If you require colocated GPUs or on-prem models, contact us.