MarsMT API

Introduction

Version: 1.3.0

Authentication

All API requests should include your API key in an Authorization HTTP header as follows:

Authorization: MarsMT-Auth-Key <your key>

Supported languages

https://www.marsmt.com/api/v1/languages

Supported engines

• Mars Translate (LLM)

• Gemini

• GPT-4.1

• GPT-5

• DeepSeek 3.1

• Qwen

• Doubao

• Google Translate

• DeepL Translate

• Microsoft Translate

Deprecated engines

• Amazon Translate

• Baidu Translate

• Youdao Translate

• GPT-4

• GPT-4o

• Qwen Max

• DeepSeek R1

Supported engines may be updated. You can get a list of supported engines through this API:

GET https://marsmt.com/api/v1/supported_engines

If you want to know which engines are available for language pair:

GET https://marsmt.com/api/v1/supported_engines?srcLang=en-US&trgLang=zh-CN

Note: The original parameter tarLang is deprecated, please change it to trgLang

Translate Text

POST https://www.marsmt.com/api/v1/translate

Request Parameters

Name	Required	Description
text	Y (string array)	Text
srcLang	Y	Source language
trgLang	Y	Target language
engine	N	Engine name
domain	N	Domain (Deprecated)
scene	N	The scene parameter specifies the context or scenario for translation. It helps the system apply appropriate terminology and style.
glossaryIds	N (string array)	Applicable only to Mars Translate (LLM)

Translate Text Example

Example request

POST /api/v1/translate HTTP/1.1
Content-Type: application/json
Host: www.marsmt.com
Authorization: MarsMT-Auth-Key <your key>
...
 
{
    "srcLang": "en",
    "trgLang": "de",
    "domain": "general",
    "engine": "Mars Translate",
    "text": [
        "hello"
    ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{"translations":[{"source":"hello","target":"hallo"}]}

Translate Documents

• Upload the document to be translated (==Suggestion: size<10MB and characters<100,000==)

• Periodically check the status of the document translation

• Once the status call reports Done, download the translated document

Step 1. Upload and Translate a Document

This call uploads a document and queues it for translation. The call returns once the upload is complete, returning a document ID and key which can be used to query the translation status and to download the translated document once translation is complete..

Because the request includes a file upload, it must be an HTTP POST request with content type multipart/form-data.

POST https://www.marsmt.com/api/v1/document

Request Parameters (form-data)

Name	Required	Description
file	Y	File(binary)
srcLang	Y	Source language. This value will be ignored when translating bilingual documents
trgLang	Y	Target language. This value will be ignored when translating bilingual documents
engine	N	Engine name
scene	N	The scene parameter specifies the context or scenario for translation. It helps the system apply appropriate terminology and style.
glossaryIds	N (string)	Use commas to separate multiple IDs.

FileType: docx, xlsx, pptx, xml, html, json, properties, sdlxliff, sdlppx

Translate Document Example

Example request

POST https://www.marsmt.com/api/v1/document HTTP/1.1
Authorization: MarsMT-Auth-Key <your key>
...


------WebKitFormBoundarycJPyWlbPvKtC5pAo
Content-Disposition: form-data; name="file"; filename="simple.sdlppx"
...

------WebKitFormBoundarycJPyWlbPvKtC5pAo--

Example response

{
    "docId": "7jtuvyh1zb4jdcpmt8oo7xjymbvr3x8o",
    "docKey": "UfFI8IhSwvff6y2yeRe4B2LijO8lQZhE8n445q2t1ndkt4xCiZxkZ7R9yKgiI6FY"
}

Note: Please save docId and docKey, they will be used later.

Step 2. Check Document Status

Retrieve the current state of a document translation process.

If the document is a sdlppx file type, you will get additional parts information

est is the estimated time (in seconds), but this is usually inaccurate.

GET https://www.marsmt.com/api/v1/document/{docId}/status

Request Parameters

Name	Required	Description
docId	Y (In Path)	See Step 1 response body

Request Parameters

Name	Description
id	Document ID
filename	File Name
state	Translation Status: Queue, Translating, Done, Error
characterCount	Number of characters translated (Only returned in Done and Error states)

Request example

GET https://www.marsmt.com/api/v1/document/<docId>/status HTTP/1.1
Authorization: MarsMT-Auth-Key <your key>
...

Response example

{
    "id": "o90hwidre6qmxw",
    "filename": "ts2017-test01.sdlppx",
    "state": "Queue/Translating/Done/Error"
}

If it is a sdlppx file, you will get detailed information about the sub-files

{
    "id": "o90hwidre6qmxw",
    "filename": "ts2017-test01.sdlppx",
    "state": "Done",
    "est": 2,
    "parts": [
        {
            "id": "eblq1dqe3mrdra",
            "filename": "Test.docx.sdlxliff",
            "state": "Done",
            "est": 1
        },
        {
            "id": "pedqclat3kocju",
            "filename": "Test.docx.sdlxliff",
            "state": "Done",
            "est": 1
        }
    ]
}

Step 3. Download Translated Document

Once the status of the document translation process is Done, the result can be downloaded.

For privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again.

POST https://www.marsmt.com/api/v1/document/{docId}/result

Request Parameters

Name	Required	Description
docId	Y (In Path)	See Step 1 response body
docKey	Y (In FormParam)	See Step 1 response body
bilingual	N(In FormParam)	Whether to export bilingual files, optional values: true, false. When the value is true, you will get a zip file containing the translation and the bilingual files. Supported file types: docx, pptx, xlsx

Response

The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.

Manage glossaries

The glossary functions allow you to create, inspect, and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the glossaryId parameter.

Create a glossary

Request Parameters

Name	Required	Description
languages	Y (string array)	language code array
type	N(default: Standard )	Standard , Reference
name	N(default: Auto Generate)	unique name
entries	Y	CSV TSV data or Excel URL
entriesFormat	Y	CSV, TSV, XLSX_URI TBX_URI , TMX_URI

Request Example

POST /api/v1/glossaries HTTP/1.1
Content-Type: application/json
Authorization: MarsMT-Auth-Key <your_auth_key>
...
 
{
    "languages": [
        "en",
        "zh-CN"
    ],
    "type": "Standard",
    "name": "your unique name",
    "entries": "en,zh-CN\nButton,按钮",
    "entriesFormat": "CSV"
}

Response example

{
    "glossaryId": "aEopHlswqhVK"
}

If you want to use Excel, please refer to the following template:

en	zh-CN	fr
Button	按钮	Bouton

Request Example

POST /api/v1/glossaries HTTP/1.1
Content-Type: application/json
Authorization: MarsMT-Auth-Key <your_auth_key>
...
 
{
    "languages": [
        "en",
        "zh-CN",
        "fr"
    ],
    "type": "Standard",
    "name": "your unique name",
    "entries": "https://example.com/your_terms.xlsx",
    "entriesFormat": "XLSX_URI"
}

Scene

Use the scenario to replace the domain parameters.

Optional values:

• general

• medical

• legal

• technical

• e-commerce

• game

• customer service

• social media

• academic

• travel

• finance

• marketing

• subtitle (Deprecated. Please use drama.)

• drama

Error Codes

HTTP status and error code are consistent

Code	Description
400	Invalid request parameters
400	Unsupported file type
400	Unsupported language
400	Engine does not support
400	Invalid glossary file
401	Unauthorized / Invalid Auth Key
403	Invalid document key (Attempt to illegally obtain translation documents)
404	Not Found, Trying to get a translation document that doesn't exist
413	The number of terms in the file exceeds the limit (5000)
429	Rate Limit Reached, please try again later
429	File exceeds the 200,000 character limit
500	Server Error, Please retry your request after a brief wait and contact us if the issue persists
502	The service is temporarily unavailable, please try again later