API Doc for AI Translation

Overview

This document describes all interfaces of the Translation Platform Open API. The Open API allows third-party systems to integrate translation services, including file translation, term library management, and memory library management.

Basic Information

Base URL: /api/v1/open
Request Format: application/json (except for file uploads)
Response Format: application/json

Authentication

All APIs require an API Key in the request header:

http

X-API-Key: your_api_key_here

Unified Response Format

json

{
    "code": 0,
    "message": "success",
    "data": {}
}

Field	Type	Description
code	int	Status code, 0 indicates success
message	string	Status message
data	object	Response data

Rate Limiting (QPS)

To ensure service stability, all APIs have rate limits:

API Type	QPS Limit	Description
File Upload	5/s	Maximum 5 requests per second per API Key
Submit Translation	10/s	Maximum 10 requests per second per API Key
Query Status	10/s	Maximum 10 requests per second per API Key
Get Download URL	10/s	Maximum 10 requests per second per API Key
Other APIs	20/s	Maximum 20 requests per second per API Key

When rate limit is exceeded, the API returns error code 91006 (Rate limit exceeded). Please reduce request frequency and retry.

General APIs

Get Supported Languages

Get all supported language codes and names.

Request

http

GET /api/v1/open/languages

Request Parameters

None

Response Data

Field	Type	Description
languages	array	Language list
languages[].code	string	Language code
languages[].name	string	Language name in English
total	int	Total number of languages

Response Example

json

{
    "code": 0,
    "message": "success",
    "data": {
        "languages": [
            {"code": "zh-CN", "name": "Chinese Simplified"},
            {"code": "en-US", "name": "English"},
            {"code": "ja", "name": "Japanese"}
        ],
        "total": 50
    }
}

File Translation APIs

Upload File

Upload a file for translation.

Request

http

POST /api/v1/open/files/upload
Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
file	file	Yes	File to upload. Supported formats: docx, doc, pdf, pptx, ppt, xlsx, xls, txt
is_can_edit	boolean	No	Whether PDF file is editable, default is true

Response Data

Field	Type	Description
file_id	string	File ID

Response Example

json

{
    "code": 0,
    "message": "success",
    "data": {
        "file_id": "12345678901234567"
    }
}

Submit Translation Task

Submit a file for translation.

Status Restriction: Only files with status 1 (Pending Translation) can be submitted for translation. Calling this API on files with other statuses will return error code 91104.

Request

http

POST /api/v1/open/translate/submit
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
file_id	int	Yes	File ID (integer type)
source_language	string	Yes	Source language code (LanguageEnum value, e.g., zh-CN)
target_language	string	Yes	Target language code (LanguageEnum value, e.g., en-US)
trans_mode	string	Yes	Translation mode: `deep` (Deep Translation) or `master` (Master Translation)
term_lib_ids	int[]	No	List of term library IDs
memory_libs	object[]	No	Memory library configuration list
memory_libs[].memory_lib_id	int	Yes	Memory library ID
memory_libs[].threshold	float	No	Match threshold, range 0-1, default 0.8

Request Example

json

{
    "file_id": 12345678901234567,
    "source_language": "zh-CN",
    "target_language": "en-US",
    "trans_mode": "deep",
    "term_lib_ids": [1, 2],
    "memory_libs": [
        {"memory_lib_id": 1, "threshold": 0.8}
    ]
}

Response Data

Field	Type	Description
estimated_cost	string	Estimated cost

Response Example

json

{
    "code": 0,
    "message": "success",
    "data": {
        "estimated_cost": "10.50"
    }
}

Query File Status

Batch query file translation status.

Request

http

POST /api/v1/open/files/status
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
file_ids	string[]	Yes	List of file IDs (string type), maximum 20

Request Example

json

{
    "file_ids": ["12345678901234567", "12345678901234568"]
}

Response Data

Field	Type	Description
files	array	File status list
files[].file_id	string	File ID
files[].status	int	File status code (see table below)
files[].filename	string	Filename (null if not exists)
files[].word_count	int	Word count (null if not exists)
files[].source_language	string	Source language code (null if not exists)

File Status Codes

Status Code	Description
-1	File not found
14	Parsing
15	Parse failed
1	Pending translation
5	Analyzing
6	Analysis failed
7	Analyzed
2	Translating
3	Translation failed
4	Translated
16	Extracting
17	Extraction failed
18	Extraction completed

Response Example

json

{
    "code": 0,
    "message": "success",
    "data": {
        "files": [
            {
                "file_id": "12345678901234567",
                "status": 4,
                "filename": "document.docx",
                "word_count": 1500,
                "source_language": "zh-CN"
            },
            {
                "file_id": "99999999999999999",
                "status": -1,
                "filename": null,
                "word_count": null,
                "source_language": null
            }
        ]
    }
}

Get Download URL

Get the download URL for a translated file.

Status Restriction: Only files with status 4 (Translated) can get download URL. Calling this API on files that are not yet translated will return error code 91108.

Request

http

POST /api/v1/open/translate/download
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
file_id	string	Yes	File ID (string type)

Request Example

json

{
    "file_id": "12345678901234567"
}

Response Data

Field	Type	Description
file_id	string	File ID
status	string	Status: `compositing` - composing, `completed` - completed
download_url	string	Download URL (null when compositing)
filename	string	Filename (null when compositing)
expires_in	int	URL expiration time in seconds (null when compositing)

Response Example (Compositing)

json

{
    "code": 0,
    "message": "success",
    "data": {
        "file_id": "12345678901234567",
        "status": "compositing",
        "download_url": null,
        "filename": null,
        "expires_in": null
    }
}

Response Example (Completed)

json

{
    "code": 0,
    "message": "success",
    "data": {
        "file_id": "12345678901234567",
        "status": "completed",
        "download_url": "https://storage.example.com/file.docx?token=xxx",
        "filename": "document_translated.docx",
        "expires_in": 300
    }
}

Delete File

Delete an uploaded file.

Request

http

POST /api/v1/open/files/delete
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
file_id	string	Yes	File ID (string type)

Request Example

json

{
    "file_id": "12345678901234567"
}

Response Data

Field	Type	Description
file_id	string	File ID
deleted	boolean	Whether deletion was successful

Response Example

json

{
    "code": 0,
    "message": "success",
    "data": {
        "file_id": "12345678901234567",
        "deleted": true
    }
}

Error Codes

Authentication Related (910xx)

Error Code	Description
91000	API Key is required
91001	Invalid API Key
91002	API Key has expired
91003	API Key is disabled
91004	API Key is not yet effective
91005	Customer not found
91006	Rate limit exceeded

File Translation Related (911xx)

Error Code	Description
91100	File size exceeds the limit
91101	File type not supported
91102	File upload failed
91103	File not found
91104	File status does not allow this operation
91105	Insufficient account balance
91106	Refund failed, balance record not found
91107	Task not found
91108	Task not completed, cannot download
91109	Translated file not found
91110	Failed to get download URL
91111	File is being translated, cannot operate

Language Code Reference

The following are common language codes (for the complete list, call the /api/v1/open/languages API):

Code	Language
zh-CN	Chinese (Simplified)
zh-TW	Chinese (Traditional)
en-US	English
ja	Japanese
ko	Korean
de	German
fr	French
es	Spanish
pt	Portuguese
ru	Russian
ar	Arabic
th	Thai
vi	Vietnamese
id	Indonesian
ms	Malay

Usage Examples

Python Example

python

import requests

BASE_URL = "https://api.example.com/api/v1/open"
API_KEY = "your_api_key"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# 1. Upload file
with open("document.docx", "rb") as f:
    files = {"file": f}
    data = {"is_can_edit": "true"}
    response = requests.post(
        f"{BASE_URL}/files/upload",
        files=files,
        data=data,
        headers={"X-API-Key": API_KEY}
    )
    file_id = response.json()["data"]["file_id"]

# 2. Submit translation
response = requests.post(
    f"{BASE_URL}/translate/submit",
    json={
        "file_id": int(file_id),
        "source_language": "zh-CN",
        "target_language": "en-US",
        "trans_mode": "deep"
    },
    headers=headers
)

# 3. Query status
response = requests.post(
    f"{BASE_URL}/files/status",
    json={"file_ids": [file_id]},
    headers=headers
)
status = response.json()["data"]["files"][0]["status"]

# 4. Get download URL (after translation is complete)
response = requests.post(
    f"{BASE_URL}/translate/download",
    json={"file_id": file_id},
    headers=headers
)
download_url = response.json()["data"]["download_url"]

cURL Example

bash

# Get supported languages
curl -X GET "https://api.example.com/api/v1/open/languages" \
  -H "X-API-Key: your_api_key"

# Upload file
curl -X POST "https://api.example.com/api/v1/open/files/upload" \
  -H "X-API-Key: your_api_key" \
  -F "file=@document.docx" \
  -F "is_can_edit=true"

# Submit translation
curl -X POST "https://api.example.com/api/v1/open/translate/submit" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"file_id": 12345678901234567, "source_language": "zh-CN", "target_language": "en-US", "trans_mode": "deep"}'

# Query status
curl -X POST "https://api.example.com/api/v1/open/files/status" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"file_ids": ["12345678901234567"]}'