API dịch tài liệu

Dịch bất đồng bộ các tệp tài liệu được hỗ trợ bằng khóa API của bạn.

Quy trình

Tải tài liệu lên bằng POST /v1/translation/document-translation/api.
Lưu lại translationId được trả về.
Kiểm tra trạng thái bằng GET /v1/translation/document-translation-status/{translationId}.
Khi trạng thái là completed, dùng data.documentUrl để tải tệp đã dịch.

1) Tải tài liệu lên

Endpoint

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

Xác thực

x-api-key: YOUR_API_KEY

Loại nội dung

Dùng multipart/form-data và gửi tệp trong trường file.

Các trường biểu mẫu

Bắt buộc:

file tệp
sourceLang chuỗi
targetLang chuỗi
model chuỗi

Tùy chọn:

domain chuỗi
writingStyle chuỗi
tone chuỗi
customPrompt chuỗi

Mã ngôn ngữ được liệt kê trong Ngôn ngữ được hỗ trợ. Các mô hình được hỗ trợ được liệt kê trong Mô hình được hỗ trợ. Các loại tệp được hỗ trợ được liệt kê trong Loại tài liệu được hỗ trợ.

Quy tắc xác thực dữ liệu

sourceLang, targetLang: Phải khớp với ^[a-zA-Z]+(-[a-zA-Z]+)?$, tối thiểu 2 ký tự, tối đa 10 ký tự.
model: Phải là một trong các giá trị trong Mô hình được hỗ trợ.
file: Phải có một trong các phần mở rộng trong Loại tài liệu được hỗ trợ.

Ví dụ 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"'

Ví dụ 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);
}

Ví dụ 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())

Phản hồi thành công `201`

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

Các loại phản hồi

Lỗi xác thực yêu cầu (400) từ middleware:

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

Chưa tải tệp lên (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."
}

Loại tệp không hợp lệ (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."
}

Header khóa API không hợp lệ (401):

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

Thiết lập khóa API/người dùng/tổ chức không hợp lệ (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
}

Lỗi máy chủ (500):

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

2) Kiểm tra trạng thái dịch

Endpoint

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

Xác thực

x-api-key: YOUR_API_KEY

Ví dụ cURL

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

Ví dụ 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);

Ví dụ 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())

Định dạng phản hồi

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

Các giá trị trạng thái

waiting: Tác vụ đang trong hàng đợi.
active: Đang dịch.
completed: Đã dịch xong và có thể dùng data.documentUrl.
failed: Dịch thất bại. Kiểm tra error.

Các loại phản hồi

Thiếu id hàng đợi (400):

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

Header khóa API không hợp lệ (401):

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

Thiết lập khóa API/người dùng/tổ chức không hợp lệ (400):

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

Không tìm thấy tác vụ (404):

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

Không được phép (401) nếu thiếu ngữ cảnh người dùng:

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

Truy cập hàng đợi không được phép (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
}

Lỗi quy tắc nghiệp vụ trả về từ kết quả hàng đợi (ví dụ 402):

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

Lỗi máy chủ (500):

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

3) Tải xuống tài liệu đã dịch

Khi trạng thái là completed, gọi documentUrl từ phản hồi trạng thái.

Endpoint

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

Tham số truy vấn tùy chọn:

fileType=translated (mặc định)
fileType=source

Ví dụ cURL

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

Ví dụ 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);
}

Ví dụ 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")

Các loại phản hồi

Thành công (200):

Trả về nội dung tệp nhị phân.
Header bao gồm:
- Content-Type (theo loại tệp đã dịch)
- Content-Disposition: attachment; filename="..."

Header khóa API không hợp lệ (401):

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

Thiết lập khóa API/người dùng/tổ chức không hợp lệ (400):

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

Lỗi tải xuống:

{ "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" }

Khuyến nghị

Kiểm tra trạng thái mỗi 2 đến 5 giây cho đến khi translationStatus là completed hoặc failed.

Quy trình​

1) Tải tài liệu lên​

Endpoint​

Xác thực​

Loại nội dung​

Các trường biểu mẫu​

Quy tắc xác thực dữ liệu​

Ví dụ cURL​

Ví dụ JavaScript​

Ví dụ Python​

Phản hồi thành công 201​

Các loại phản hồi​

2) Kiểm tra trạng thái dịch​

Endpoint​

Xác thực​

Ví dụ cURL​

Ví dụ JavaScript​

Ví dụ Python​

Định dạng phản hồi​

Các giá trị trạng thái​

Các loại phản hồi​

3) Tải xuống tài liệu đã dịch​

Endpoint​

Ví dụ cURL​

Ví dụ JavaScript​

Ví dụ Python​

Các loại phản hồi​

Khuyến nghị​

Quy trình

1) Tải tài liệu lên

Endpoint

Xác thực

Loại nội dung

Các trường biểu mẫu

Quy tắc xác thực dữ liệu

Ví dụ cURL

Ví dụ JavaScript

Ví dụ Python

Phản hồi thành công `201`

Các loại phản hồi

2) Kiểm tra trạng thái dịch

Endpoint

Xác thực

Ví dụ cURL

Ví dụ JavaScript

Ví dụ Python

Định dạng phản hồi

Các giá trị trạng thái

Các loại phản hồi

3) Tải xuống tài liệu đã dịch

Endpoint

Ví dụ cURL

Ví dụ JavaScript

Ví dụ Python

Các loại phản hồi

Khuyến nghị