> For the complete documentation index, see [llms.txt](https://docs.marsmt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marsmt.com/marsmt/marsmt-api.md).

# MarsMT API

## Introduction

Version: 1.3.0 

## Authentication

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

```http
Authorization: MarsMT-Auth-Key <your key>
```

## Supported languages

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

## Supported engines

* `Mars Translate (LLM)` &#x20;
* `GPT-5`
* `DeepSeek 3.2`&#x20;
* `Google Translate`&#x20;
* `DeepL Translate`
* `Microsoft Translate`

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

<table><thead><tr><th width="133">Name</th><th width="147">Required</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>Y (string array)</td><td>Text</td></tr><tr><td>srcLang</td><td>Y</td><td>Source language</td></tr><tr><td>trgLang</td><td>Y</td><td>Target language</td></tr><tr><td>engine</td><td>N</td><td>Engine name</td></tr><tr><td>domain</td><td>N</td><td>Domain (Deprecated)</td></tr><tr><td>scene</td><td>N</td><td>The scene parameter specifies the context or scenario for translation. It helps the system apply appropriate terminology and style.</td></tr><tr><td>glossaryIds</td><td>N (string array)</td><td>Applicable only to Mars Translate (LLM)</td></tr></tbody></table>

### Translate Text Example

Example request

```http
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", (Deprecated)
    "scene": "general",
    "engine": "Mars Translate",
    "text": [
        "hello"
    ]
}
```

Example response

```http
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)**

<table><thead><tr><th width="135">Name</th><th width="125">Required</th><th>Description</th></tr></thead><tbody><tr><td>file</td><td>Y</td><td>File(binary)</td></tr><tr><td>srcLang</td><td>Y</td><td>Source language.<br>This value will be ignored when translating bilingual documents</td></tr><tr><td>trgLang</td><td>Y</td><td>Target language.<br>This value will be ignored when translating bilingual documents</td></tr><tr><td>engine</td><td>N</td><td>Engine name</td></tr><tr><td>scene</td><td>N</td><td>The scene parameter specifies the context or scenario for translation. It helps the system apply appropriate terminology and style.</td></tr><tr><td>glossaryIds</td><td>N (string)</td><td>Use commas to separate multiple IDs.</td></tr></tbody></table>

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

### Translate Document Example

Example request

```http
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

```json
{
    "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**

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

**Response example**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "id": "o90hwidre6qmxw",
    "filename": "ts2017-test01.sdlppx",
    "state": "Queue/Translating/Done/Error"
}
</code></pre>

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

```json
{
    "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**

<table><thead><tr><th width="122">Name</th><th width="163">Required</th><th>Description</th></tr></thead><tbody><tr><td>docId</td><td>Y (In Path)</td><td>See <code>Step 1</code> response body</td></tr><tr><td>docKey</td><td>Y (In FormParam)</td><td>See <code>Step 1</code> response body</td></tr><tr><td>bilingual</td><td>N(In FormParam)</td><td>Whether to export bilingual files, optional values: <code>true</code>, <code>false</code>.
<br>When the value is true, you will get a zip file containing the translation and the bilingual files.<br><mark style="color:orange;">Supported file types: docx, pptx, xlsx</mark></td></tr></tbody></table>

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

<pre class="language-http"><code class="lang-http"><strong>POST /api/v1/glossaries HTTP/1.1
</strong>Content-Type: application/json
Authorization: MarsMT-Auth-Key &#x3C;your_auth_key>
...
 
{
    "languages": [
        "en",
        "zh-CN"
    ],
    "type": "Standard",
    "name": "your unique name",
    "entries": "en,zh-CN\nButton,按钮",
    "entriesFormat": "CSV"
}
</code></pre>

Response example

```json
{
    "glossaryId": "aEopHlswqhVK"
}
```

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

| en     | zh-CN | fr     |
| ------ | ----- | ------ |
| Button | 按钮    | Bouton |

Request Example

```http
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.&#x20;

**Optional values:**

* general
* drama
* webnovel&#x20;
* finance
* medical
* pharma(<mark style="color:red;">New</mark>)
* patent
* legal
* technical
* marketing
* game
* e-commerce
* customer service
* social media
* academic
* travel

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