文档翻译 API

使用您的 API 密钥异步翻译受支持的文档文件。

工作流程

使用 POST /v1/translation/document-translation/api 上传文档。
保存返回的 translationId。
使用 GET /v1/translation/document-translation-status/{translationId} 轮询状态。
状态为 completed 时，使用 data.documentUrl 下载翻译后的文件。

1) 上传文档

端点

POST https://api.gpttranslator.co/v1/translation/document-translation/api

身份验证

x-api-key: YOUR_API_KEY

内容类型

使用 multipart/form-data，并通过 file 字段发送文件。

表单字段

必填：

file 文件
sourceLang 字符串
targetLang 字符串
model 字符串

可选：

domain 字符串
writingStyle 字符串
tone 字符串
customPrompt 字符串

语言代码列于支持的语言。支持的模型列于支持的模型。支持的文件类型列于支持的文档类型。

验证规则

sourceLang、targetLang：必须匹配 ^[a-zA-Z]+(-[a-zA-Z]+)?$，最少 2 个字符，最多 10 个字符。
model：必须是支持的模型中的值之一。
file：扩展名必须是支持的文档类型中的一种。

cURL 示例

curl --location 'https://api.gpttranslator.co/v1/translation/document-translation/api' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form 'file=@"/absolute/path/sample.docx"' \
  --form 'sourceLang="en"' \
  --form 'targetLang="fr"' \
  --form 'model="gpt-4.1-mini-2025-04-14"' \
  --form 'tone="professional"'

JavaScript 示例

const apiKey = "YOUR_API_KEY";
const fileInput = document.querySelector("#fileInput");

const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("sourceLang", "en");
formData.append("targetLang", "fr");
formData.append("model", "gpt-4.1-mini-2025-04-14");
formData.append("tone", "professional");

const uploadRes = await fetch(
  "https://api.gpttranslator.co/v1/translation/document-translation/api",
  {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
    },
    body: formData,
  },
);

const uploadData = await uploadRes.json();
const translationId = uploadData?.data?.translationId;

if (!translationId) {
  console.error("Upload failed:", uploadData);
}

Python 示例

import requests

api_key = "YOUR_API_KEY"
url = "https://api.gpttranslator.co/v1/translation/document-translation/api"

headers = {
    "x-api-key": api_key
}

data = {
    "sourceLang": "en",
    "targetLang": "fr",
    "model": "gpt-4.1-mini-2025-04-14",
    "tone": "professional"
}

with open("/absolute/path/sample.docx", "rb") as f:
    files = {
        "file": ("sample.docx", f)
    }
    response = requests.post(url, headers=headers, data=data, files=files)

print(response.status_code)
print(response.json())

成功响应 `201`

{
  "message": "Document translation added successfully",
  "data": {
    "translationId": "12345"
  },
  "error": null,
  "statusCode": 201
}

响应类型

来自中间件的请求验证错误（400）：

{
  "error": "Invalid model type. Please enter a valid model type e.g. ..."
}

未上传文件（400）：

{
  "error": "No file uploaded. Please upload a file for translation.",
  "statusCode": 400,
  "data": null,
  "message": "No file uploaded. Please upload a file for translation."
}

文件类型无效（400）：

{
  "error": "Invalid file type. Please upload one of: docx, xlsx, pdf, pptx, srt, vtt, xml, json, yaml, yml, csv, txt, md, html, eml.",
  "statusCode": 400,
  "data": null,
  "message": "Invalid file type. Please upload one of: docx, xlsx, pdf, pptx, srt, vtt, xml, json, yaml, yml, csv, txt, md, html, eml."
}

API 密钥请求头无效（401）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 401,
  "data": null
}

API 密钥/用户/组织设置无效（400）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 400,
  "data": null
}

{
  "message": "User not found or user is not active",
  "error": "User not found or user is not active",
  "statusCode": 400,
  "data": null
}

{
  "message": "Organization Id not found for the user",
  "error": "Organization Id not found for the user",
  "statusCode": 400,
  "data": null
}

服务器错误（500）：

{
  "error": "Internal server error",
  "message": "An error occurred while processing the document translation request. Please try again later.",
  "data": null,
  "statusCode": 500
}

2) 检查翻译状态

端点

GET https://api.gpttranslator.co/v1/translation/document-translation-status/{translationId}

身份验证

x-api-key: YOUR_API_KEY

cURL 示例

curl --location 'https://api.gpttranslator.co/v1/translation/document-translation-status/12345' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript 示例

const apiKey = "YOUR_API_KEY";
const translationId = "12345";

const statusRes = await fetch(
  `https://api.gpttranslator.co/v1/translation/document-translation-status/${translationId}`,
  {
    headers: {
      "x-api-key": apiKey,
    },
  },
);

const statusData = await statusRes.json();
console.log(statusData);

Python 示例

import requests

api_key = "YOUR_API_KEY"
translation_id = "12345"
url = f"https://api.gpttranslator.co/v1/translation/document-translation-status/{translation_id}"

response = requests.get(url, headers={"x-api-key": api_key})

print(response.status_code)
print(response.json())

响应格式

{
  "message": "Translation status fetched successfully",
  "translationStatus": "completed",
  "data": {
    "documentUrl": "https://api.gpttranslator.co/v1/translation/download-document/65f0d3f6f0a1c91234567890"
  },
  "error": null,
  "statusCode": 200
}

状态值

waiting：任务正在排队。
active：正在翻译。
completed：翻译已完成，可使用 data.documentUrl。
failed：翻译失败。请查看 error。

响应类型

缺少队列 ID（400）：

{
  "error": "Queue ID is required",
  "message": "Queue ID is required to fetch translation status",
  "data": null,
  "statusCode": 400
}

API 密钥请求头无效（401）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 401,
  "data": null
}

API 密钥/用户/组织设置无效（400）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 400,
  "data": null
}

未找到任务（404）：

{
  "error": "Translation job not found",
  "message": "The requested translation job does not exist.",
  "data": null,
  "statusCode": 404
}

缺少用户上下文时未授权（401）：

{
  "error": "Unauthorized",
  "message": "You are not authorized to access this resource.",
  "data": null,
  "statusCode": 401
}

未授权访问队列（401）：

{
  "error": "Unauthorized access to translation status",
  "message": "You do not have permission to access the status of this translation job.",
  "data": null,
  "statusCode": 401
}

队列结果返回的业务规则失败（402 示例）：

{
  "message": "Translation status fetched successfully",
  "translationStatus": "failed",
  "data": null,
  "error": "only subscribed users are allowed to use this model",
  "statusCode": 402
}

服务器错误（500）：

{
  "error": "Internal server error",
  "message": "An error occurred while fetching the translation status. Please try again later.",
  "data": null,
  "statusCode": 500
}

3) 下载翻译后的文档

状态为 completed 时，调用状态响应中的 documentUrl。

端点

GET https://api.gpttranslator.co/v1/translation/download-document/{translationId}

可选查询参数：

fileType=translated（默认）
fileType=source

cURL 示例

curl --location 'https://api.gpttranslator.co/v1/translation/download-document/65f0d3f6f0a1c91234567890' \
  --header 'x-api-key: YOUR_API_KEY' \
  --output translated-file

JavaScript 示例

const apiKey = "YOUR_API_KEY";
const translationId = "65f0d3f6f0a1c91234567890";

const downloadRes = await fetch(
  `https://api.gpttranslator.co/v1/translation/download-document/${translationId}`,
  {
    headers: {
      "x-api-key": apiKey,
    },
  },
);

if (!downloadRes.ok) {
  const err = await downloadRes.json();
  console.error("Download failed:", err);
} else {
  const blob = await downloadRes.blob();
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = "translated-document";
  a.click();
  URL.revokeObjectURL(url);
}

Python 示例

import requests

api_key = "YOUR_API_KEY"
translation_id = "65f0d3f6f0a1c91234567890"
url = f"https://api.gpttranslator.co/v1/translation/download-document/{translation_id}"

response = requests.get(url, headers={"x-api-key": api_key}, stream=True)

if response.status_code == 200:
    with open("translated-document", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
else:
    print(response.status_code)
    try:
        print(response.json())
    except Exception:
        print("Download failed")

响应类型

成功（200）：

返回二进制文件内容。
响应头包括：
- Content-Type（取决于翻译后文件的类型）
- Content-Disposition: attachment; filename="..."

API 密钥请求头无效（401）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 401,
  "data": null
}

API 密钥/用户/组织设置无效（400）：

{
  "message": "Invalid api key",
  "error": "Invalid api key",
  "statusCode": 400,
  "data": null
}

下载错误：

{ "error": "Invalid translation ID" }

{ "error": "Translation not found or you do not have permission to access it" }

{ "error": "Translation is currently active. Please wait for completion." }

{ "error": "Translated file not available" }

最佳实践

每 2 到 5 秒轮询一次状态，直到 translationStatus 变为 completed 或 failed。

工作流程​

1) 上传文档​

端点​

身份验证​

内容类型​

表单字段​

验证规则​

cURL 示例​

JavaScript 示例​

Python 示例​

成功响应 201​

响应类型​

2) 检查翻译状态​

端点​

身份验证​

cURL 示例​

JavaScript 示例​

Python 示例​

响应格式​

状态值​

响应类型​

3) 下载翻译后的文档​

端点​

cURL 示例​

JavaScript 示例​

Python 示例​

响应类型​

最佳实践​

工作流程

1) 上传文档

端点

身份验证

内容类型

表单字段

验证规则

cURL 示例

JavaScript 示例

Python 示例

成功响应 `201`

响应类型

2) 检查翻译状态

端点

身份验证

cURL 示例

JavaScript 示例

Python 示例

响应格式

状态值

响应类型

3) 下载翻译后的文档

端点

cURL 示例

JavaScript 示例

Python 示例

响应类型

最佳实践