ModelFront docs > ModelFront API docs
Base URL:
https://api.modelfront.com
Versions:v1
Endpoints:/predict
,/postedit
,/languages
,/models
To get your API access token and code samples, create an account at console.modelfront.com and click on API.
/predict
/postedit
/languages
/models
/predict
/postedit
/predict
The /predict
endpoint returns sentence level quality scores.
POST https://api.modelfront.com/v1/predict?sl={sl}&tl={tl}&token={token}&model={model}&metadata_id={metadata_id}&threshold={threshold}
sl |
string | required | The source language code |
tl |
string | required | The target language code |
token |
string | required | Your API access token |
model |
string | optional | Your custom model ID with which to perform quality 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. |
metadata_id |
integer | optional | The metadata ID that specified model accepts. The metadata is used to pass certain meta information to the model. The list of possible metadatas with their IDs can be obtained from the /models endpoint |
threshold |
string | optional | The threshold for translation quality prediction. It can either be a float from [0.00, 1.00], or one of the fixed threshold types: strict, standard, aggressive or greedy. Threshold types reflect the expected savings and final translation quality, with strict being the safest option with the lowest savings and best quality, and greedy giving the best savings but lowest quality of all. It is recommended to use standard threshold value to preserve the final human quality while having significant savings. |
It supports batching. If you request an engine and a translation is not included, the API automatically gets the translation from that engine.
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. Use /models to get the supported metadata_id
values for the model.
{
"rows": [
{
"original": string,
"translation": string,
"id": string
}
],
"additional_metadata": {
"domain": string,
"content_type": string,
"context": string,
"file_name": string,
"project_id": string,
"project_name": string,
"any": 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 |
{row}.id |
string | optional | ID of the row |
additional_metadata |
{additional_metadata} | optional | The additional metadata is used to pass optional meta information |
{additional_metadata}.domain |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.content_type |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.context |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.file_name |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.project_id |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.project_name |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.any |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
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
.
If there is no error, then the response will contain a status and rows. The rows correspond to the request rows and they will include the row ID if the ID was provided in the request. A translation is included if it was requested. If a threshold was passed, the response will also indicate whether the segment was approved.
{
"status": "ok",
"rows": [
{
"translation": string,
"quality": number,
"risk": number,
"approved": boolean, // exists if threshold parameter was passed
"id": string,
},
...
]
}
A quality
is a floating point number with a value from 0.0 to 1.0. It can be parsed by JavaScript parseFloat()
or Python float()
.
risk
is equivalent to quality subtracted from 1.0.
/postedit
The /postedit
endpoint returns an automatic post-edit from a given source and translation.
POST https://api.modelfront.com/v1/postedit?sl={sl}&tl={tl}&token={token}&model={model}&ape_model={ape_model}&metadata_id={metadata_id}
sl |
string | required | The source language code |
tl |
string | required | The target language code |
token |
string | required | Your API access token |
model |
string | required | Your custom model ID with which to perform quality prediction |
ape_model |
string | required | Your custom APE model ID with which to perform automatic post-edit |
metadata_id |
integer | optional | The metadata ID that specified model and ape_model accepts. The metadata is used to pass certain meta information to the models. The list of possible metadatas with their IDs can be obtained from the /models endpoint |
sl
and tl
should be among the ModelFront supported languages. model
should be the identifier of your custom model. Use /models to get the supported metadata_id
values for the model.
{
"rows": [
{
"original": string,
"translation": string,
"id": string
}
],
"additional_metadata": {
"domain": string,
"content_type": string,
"context": string,
"file_name": string,
"project_id": string,
"project_name": string,
"any": 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 |
{row}.id |
string | optional | ID of the row |
additional_metadata |
{additional_metadata} | optional | The additional metadata is used to pass optional meta information |
{additional_metadata}.domain |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.content_type |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.context |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.file_name |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.project_id |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.project_name |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
{additional_metadata}.any |
string | optional | Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters |
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
.
If there is no error, then the response will contain a status and rows. The rows correspond to the request rows and they will include the row ID if the ID was provided in the request.
{
"status": "ok",
"rows": [
{
"postedit": string,
"quality": number,
"id": string
},
...
]
}
A quality
is a floating point number with a value from 0.0 to 1.0. It can be parsed by JavaScript parseFloat()
or Python float()
.
/languages
The /languages
endpoint returns a list of supported languages. 🌍
It provides a map of language codes to language names.
You can even hit it in your browser at api.modelfront.com/v1/languages.
The response is not the full list of valid languages codes and locales. The ModelFront API is smart enough to handle many variants for supported languages.
⚠️ Some machine translation APIs and translation management systems use other codes or other default locales for languages or language groups, like Chinese, Norwegian, Kurdish and Uzbek, Serbian, Hmong, Tagalog (Filipino), Dari, Otomi and Maya.
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
.
⚠️ Do not use non-standard codes, like
spa
for Spanish.
For most languages, the locale or variant is reduced to the raw language code for the purposes of quality 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
and pt-BR
.
If the language is Chinese, then the two major variants are two totally separate target languages. You can select the Traditional script with zh-Hant
or with the locales zh-tw
, zh-hk
or zh-mo
. The default script is the Simplified script, so the language code zh
(with no locale) or zh-us
is equivalent to zh-Hans
. The script code Hant
or Hans
takes precedence over the country code.
⚠️ Do not use non-standard locales, like
es-LA
for Latin American Spanish, orpa-PA
for Punjabi.
⚠️
cmn
is not supported, because Mandarin Chinese is a spoken language.
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
.
/models
The /models
endpoint returns the list of available models for your account.
GET https://api.modelfront.com/v1/models?token={token}
token |
string | required | Your access token |
If there is no error, then the response will contain the status and models - the list of the models the token has access to. Each object in the models list will have additional details, like the model’s ID, name and metadata.
{
"status": "ok",
"models": [
{
"id": string,
"name": string,
"metadata": [
{
"id": integer,
"name": string
},
...
]
}
]
}
status |
string | The request status |
models |
{model}[] | The list of models the token has access to |
{model}.id |
string | The model ID |
{model}.name |
string | The model name |
{model}.metadata |
{metadata}[] | The list of model's metadata objects |
{model}.{metadata}.id |
integer | The ID of the metadata object |
{model}.{metadata}.name |
string | the metadata name |
In particular, the response contains the list of metadata objects supported by each model. The metadata IDs are non-negative integers that should be passed to /predict
requests to specify e.g. the content type of the rows for the specific model.
You can get the identifier and deployment state of your custom models in the API tab of the console.
If no model is passed to /predict
, the default base model is used.
You can get the metadata for your model in the object returned by /models
. It contains a list of metadata objects each of which has the id and name of the metadata (see the /models
response body above).
If your model supports metadata, then metadata_id
parameter should be passed to /predict
. It should be one of the metadata ids returned by /models
.
Optionally, you can select a machine translation engine to have the translations filled in for you.
google |
Custom translation with custom_engine_id and engine_key |
|
Microsoft | microsoft |
Custom translation with custom_engine_id |
DeepL | deepl |
No custom translation supported |
ModernMT | modernmt |
Custom translation with custom_engine_id and engine_key |
Let ModelFront choose… | * |
You will be billed for using the machine translation engine.
If you want to use your own key for billing instead, include engine_key
.
If translation is already included in a row, the engine will not be used.
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": "..."
}
200
Successful response
400
When the body is malformed or the parameters like sl
, tl
, engine
, model
and metadata_id
’ 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? You can find your token in the API tab of the console.
Then send a request.
/predict
curl \
--header "Content-Type: application/json" --request POST \
--data '{ "rows": [ {"original": "This is not a test.", "translation": "Esto no es una prueba.", "id": "1"} ] }' \
"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.",
id: "1"
}
]
};
(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": [
{
"quality": 0.9972,
"id": "1"
}
]
}
/postedit
export $QP_MODEL=<your quality prediction model>
export $APE_MODEL=<your automatic post-edit model>
curl \
--header "Content-Type: application/json" --request POST \
--data '{ "rows": [ {"original": "This is not a test.", "translation": "Esto es una prueba.", "id": "1"} ] }' \
"https://api.modelfront.com/v1/postedit?sl=en&tl=es&token=$MODELFRONT_TOKEN&model=$QP_MODEL&ape_model=$APE_MODEL"
// npm install request
const util = require('util')
const request = util.promisify(require("request"));
const token = process.env.MODELFRONT_TOKEN;
const qpModel = process.env.QP_MODEL;
const apeModel = process.env.APE_MODEL;
const url = `https://api.modelfront.com/v1/postedit?sl=en&tl=es&token=${ token }&model=${ qpModel }&ape_model=${ apeModel }`;
const body = {
rows: [
{
original: "This is not a test.",
translation: "Esto es una prueba.",
id: "1"
}
]
};
(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": [
{
"postedit":"Esto no es una prueba.",
"quality":0.70957
}
]
}
⚠️ Do not just send a million lines at once. 😊
If you want to send thousands or millions of lines programmatically, you should stream by sending batch requests of 30 rows sequentially. You can send up to 3 requests in parallel on a cold start.
ModelFront autoscales under load. So the throughput increases after a few minutes.
If you send too many requests, the API will respond with status code 429 - “Slow down!”. We generally recommend a retry with exponential backoff.
ⓘ If you just want to run evaluations large files, you can just the console - no coding! You can run files with tens of millions of lines - with just a few clicks. 💻
The response time is similar to a machine translation API.
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 dedicated GPUs, large batches, accelerated autoscaling or on-prem models, contact us.