ModelFront docs > ModelFront API docs

ModelFront API docs

How to use the ModelFront API

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

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

Request body

{
  "rows": [
    {
      "id": string,
      "original": string,
      "translation": string,
      "segment_type": 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,
      "approved": boolean,
      // If APE Enabled, approved is false, and postedit_approved is true then postedit and postedit_approved will be present
      "postedit": string,
      "postedit_approved": boolean
    },
    ...
  ]
}

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.

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

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 the languages supported by your models

HTTP request

GET /v1/languages?token={token}
Host: api.modelfront.com
Content-Type: application/json
token string required Your API access token

Response body

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

{
  "status": "ok",
  "languages": {
      source_language: [ ...target_languages ],
      ...
    }
}

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 are missing, invalid or in an invalid combination

401 When the authentication token is missing or invalid

402 When the API token is blocked

419 When the requested model is unavailable, typically because it is undeployed

429 When there are too many requests from the same IP client. By default it’s restricted to 40 requests per seconds. We highly recommend implementing retries with exponential backoff for 429 status code.

Server errors

503 When a model is temporarily unavailable

500 When there is any other error

While /predict and /feedback endpoints are designed for high availability, occasional maintenance or unforeseen circumstances may result in brief periods of unavailability, potentially returning 5xx status codes.

We highly recommend implementing retries with an exponential backoff in case client receives 50x or 429 status codes.

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", "segment_type": "mt"} ] }' \
  "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",
      segment_type: "mt"
    }
  ]
};

(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": [
    {
      "id": "1",
      "approved": true,
      // If APE Enabled, approved is false, and postedit_approved is true then postedit and postedit_approved will be present
      "postedit": "Esto no es una prueba.",
      "postedit_approved": true
    }
  ]
}

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.