ModelFront docs > ModelFront API docs

ModelFront API docs

How to use the ModelFront API

Base URL: https://api.modelfront.com
Versions: v1
Endpoints: /predict, /postedit, /feedback, /languages, /models

To get your API access token and code samples, sign in at console.modelfront.com and click on the API tab.

/predict

The /predict endpoint returns an approve / reject flag for the given segment’s translation.

HTTP request

POST /v1/predict?threshold=standard&sl={sl}&tl={tl}&token={token}&model={model}
Host: api.modelfront.com
Content-Type: application/json
sl string required The source language code
tl string required The target language code
token string required Your API access token
threshold string required The threshold for translation approval strictness. It can either be one of the fixed threshold types: strict, standard, aggressive, greedy or a float from [0.00, 1.00]. Threshold types reflect the expected savings and final translation quality. ModelFront recommends using the standard threshold value to get the maximum savings while preserving the same final human quality. strict will decrease savings but will most likely not increase quality, aggressive and greedy will increase savings but decrease quality.
model string required 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.

It supports batching, up to 30 rows per request. 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.

Request body

{ 
  "rows": [ 
    {
      "id": string
      "original": string,
      "translation": string,
    }
  ],
  "additional_metadata": {
    "workflow": string,
    "client": string,
    "domain": string,
    "content_type": string,
    "context": string,
    "file_name": string,
    "file_id": string
    "file_total_batch_count": integer
    "file_current_batch_index": integer
    "project_id": string,
    "project_name": string, 
    "any": string,
  }
}
rows {row}[] required The list of row objects. Can be a batch of up to 30 items.
{row}.id string required ID of the row
{row}.original string required The source text
{row}.translation string optional The translated text to approve or reject
{row}.segment_type string required The type of the segment, possible values are - `mt` - machine translation - `fm` - fuzzy-match
{row}.tm_score float required when {row}.segment_type == "fm" The translation memory score in case the segment_type is `fm`. Must be in between [0,100]
additional_metadata {additional_metadata} required The additional metadata is used to pass optional meta information
{additional_metadata}.file_id string required Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.file_name string required Any string, up to 255 characters
{additional_metadata}.file_total_batch_count integer required Any positive integer, representing the total number of request batches for the given file (e.g. 100 line file -> each batch request has 30 rows => ceil(100 / 30) -> 4 batches)
{additional_metadata}.file_current_batch_index integer required The current request batch index for the given file (must be in the range [0, file_total_batch_count - 1]). The index should be preserved over possible request retries to avoid double counting
{additional_metadata}.project_id string required Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.project_name string required Any string, up to 255 characters
{additional_metadata}.workflow string optional Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.client string optional Any string, up to 255 characters
{additional_metadata}.domain string optional Any string, up to 255 characters
{additional_metadata}.content_type string optional Any string, up to 255 characters
{additional_metadata}.context string optional Any string, 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
API calls recommendations

For optimal predictions, every row should include at most one full sentence and no more than 500 characters in original and translation.

Response body

The response will contain a status and rows, unless there is an error. 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.

{
  "status": "ok",
  "rows": [
    {
      "id": string,
      "translation": string,
      "approved": boolean,
      "quality": number, // deprecated in favor of "approved"
      "risk": number, // deprecated in favor of "approved"
    },
    ...
  ]
}

The approved flag indicates whether the given translation is safe to be skipped by the human translator, i.e. automatically signed off. The safest and most user-friendly option is to use the approved flag during integration.

A quality and risk are a floating point number with a value from 0.0 to 1.0. risk is equivalent to quality subtracted from 1.0.
It’s important to not confuse it with a fuzzy match score from a translation memory. There is no universal threshold for a quality score - thresholds for each model, language pair, content type and other variables are calibrated by the ModelFront team and provided with each production model.

/postedit

The /postedit endpoint returns an automatic post-edit from a given source and translation.

HTTP request

POST /v1/postedit?sl={sl}&tl={tl}&token={token}&model={model}&ape_model={ape_model}&metadata_id={metadata_id}
Host: api.modelfront.com
Content-Type: application/json
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.

Request body

{ 
  "rows": [ 
    {
      "original": string,
      "translation": string,
      "id": string
    }
  ],
  "additional_metadata": {
    "workflow": string,
    "client": string,
    "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. Can be a batch of up to 30 items.
{row}.id string optional ID of the row
{row}.original string required The source text
{row}.translation string optional The translated text to approve or reject
{row}.segment_type string optional The type of the segment, possible values are - `mt` - machine translation - `fm` - fuzzy-match
{row}.tm_score float optional The translation memory score in case the segment_type is `fm`. Must be in between [0,100]
additional_metadata {additional_metadata} optional The additional metadata is used to pass optional meta information
{additional_metadata}.workflow string optional Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.client string optional Any string, up to 255 characters
{additional_metadata}.domain string optional Any string, up to 255 characters
{additional_metadata}.content_type string optional Any string, up to 255 characters
{additional_metadata}.context string optional Any string, up to 255 characters
{additional_metadata}.file_id 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 string, up to 255 characters
{additional_metadata}.file_total_batch_count integer optional Any positive integer, representing the total number of request batches for the given file (e.g. 100 line file -> each batch request has 30 rows => ceil(100 / 30) -> 4 batches)
{additional_metadata}.file_current_batch_index integer optional The current request batch index for the given file (must be in the range [0, file_total_batch_count - 1]). The index should be preserved over possible request retries to avoid double counting
{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 string, 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
API calls recommendations

For an optimal result, every row should include at most one full sentence and no more than 500 characters in original and translation.

Response body

The response will contain a status and rows unless there is an error. 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, // deprecated, will be removed anytime
      "id": string
    },
    ...
  ]
}

[deprecated] A quality score is a floating point number with a value from 0.0 to 1.0.

/feedback

The /feedback endpoint updates the system with the given segment’s human edit / verification, to provide the human feedback loop for monitoring and retraining.

HTTP request

POST /v1/feedback?sl={sl}&tl={tl}&token={token}
Host: api.modelfront.com
Content-Type: application/json
sl string required The source language code
tl string required The target language code
token string required Your API access token

It supports batching, up to 30 rows per request.

sl and tl should be among the ModelFront supported languages.

Request body

{ 
  "rows": [ 
    {
      "id": string
      "original": string,
      "postedit": string,
    }
  ],
  "additional_metadata": {
    "workflow_step": string,
    "project_id": string,
    "project_name": string,
    "file_id": string,
    "file_name": string,
    "file_total_batch_count": integer
    "file_current_batch_index": integer,
  }
}
rows {row}[] required The list of row objects. Can be a batch of up to 30 items.
{row}.id string required ID of the row
{row}.original string required The source text
{row}.postedit string required The postedit text
additional_metadata {additional_metadata} required The additional metadata is used to pass optional meta information
{additional_metadata}.workflow_step string required Any string, up to 255 characters
{additional_metadata}.project_id string required Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.project_name string required Any string, up to 255 characters
{additional_metadata}.file_id string required Any dash-case or snake_case string, no spaces or special characters allowed, up to 255 characters
{additional_metadata}.file_name string required Any string, up to 255 characters
{additional_metadata}.file_total_batch_count integer required Any positive integer, representing the total number of request batches for the given file (e.g. 100 line file -> each batch request has 30 rows => ceil(100 / 30) -> 4 batches)
{additional_metadata}.file_current_batch_index integer required The current request batch index for the given file (must be in the range [0, file_total_batch_count - 1]). The index should be preserved over possible request retries to avoid double counting

When to call /feedback

For workflows with multiple human editing steps, /feedback can be called multiple times.

API calls recommendations

Response body

The response will contain a status ok, unless there is an error.

{
  "status": "ok"
}

/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.

Language codes

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.

Locales and variants

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:

  1. 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.

  2. 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, or pa-PA for Punjabi.

⚠️ cmn is not supported, because Mandarin Chinese is a spoken language.

More languages

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.

HTTP request

GET /v1/models?token={token}
Host: api.modelfront.com
token string required Your access token

Response body

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.

Metadata

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.

Engines

Optionally, you can select a machine translation engine to have the translations filled in for you.

Supported engines
Google 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.

Errors

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": "..."
}

Status codes

Successful response

200 Successful response

Request errors

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. By default it’s restricted to 40 requests per socond.

424 When the external machine translation API for the requested engine has returned an error

Server errors

503 When a model, including the default model, is temporarily unavailable

500 When there is any other error

Code examples

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

bash

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"

Node.js

// 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

bash

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"

Node.js

// 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
    }
  ]
}

FAQ

How can we hit the API at scale?

⚠️ 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. 💻

How can we hit the API at speed?

The response time is similar to a machine translation API.

For the best latency, you should 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.

More questions?

Read our general documentation, or shoot us an email at [email protected]
© ModelFront Inc.