# 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
* medical
* legal
* technical
* e-commerce
* game
* customer service
* social media
* academic
* travel
* finance
* marketing
* subtitle (Deprecated. Please use drama.)
* drama
* webnovel&#x20;
* patent

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.marsmt.com/marsmt/marsmt-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.