Document Translation API

Translate supported document files asynchronously using your API key.

Workflow

Upload a document using POST /v1/translation/document-translation/api.
Save the returned translationId.
Poll status using GET /v1/translation/document-translation-status/{translationId}.
When status is completed, use data.documentUrl to download the translated file.

1) Upload Document

Endpoint

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

Authentication

x-api-key: YOUR_API_KEY

Content Type

Use multipart/form-data and send file field as file.

Form Fields

Required:

file file
sourceLang string
targetLang string
model string

Optional:

domain string
writingStyle string
tone string
customPrompt string

Language codes are listed in Supported Languages. Supported models are listed in Supported Models. Supported file types are listed in Supported Document Types.

Validation Rules

sourceLang, targetLang: Must match ^[a-zA-Z]+(-[a-zA-Z]+)?$, min 2 chars, max 10 chars.
model: Must be one of the values in Supported Models.
file: Must be one of the extensions in Supported Document Types.

cURL Example

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 Example

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 Example

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())

Success Response `201`

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

Response Types

Request validation error (400) from middleware:

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

No file uploaded (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."
}

Invalid file type (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."
}

Invalid API key header (401):

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

Invalid API key/user/org setup (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
}

Server error (500):

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

2) Check Translation Status

Endpoint

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

Authentication

x-api-key: YOUR_API_KEY

cURL Example

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

JavaScript Example

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 Example

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())

Response Format

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

Status Values

waiting: Job is queued.
active: Translation is in progress.
completed: Translation finished and data.documentUrl is available.
failed: Translation failed. Check error.

Response Types

Queue id missing (400):

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

Invalid API key header (401):

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

Invalid API key/user/org setup (400):

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

Job not found (404):

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

Unauthorized (401) if user context is missing:

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

Unauthorized queue access (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
}

Business rule failure surfaced by queue result (402 example):

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

Server error (500):

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

3) Download Translated Document

When status is completed, call the documentUrl from status response.

Endpoint

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

Optional query:

fileType=translated (default)
fileType=source

cURL Example

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

JavaScript Example

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 Example

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")

Response Types

Success (200):

Returns binary file content.
Headers include:
- Content-Type (based on translated file type)
- Content-Disposition: attachment; filename="..."

Invalid API key header (401):

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

Invalid API key/user/org setup (400):

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

Download errors:

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

Best Practice

Poll every 2 to 5 seconds for status until translationStatus becomes completed or failed.

Workflow​

1) Upload Document​

Endpoint​

Authentication​

Content Type​

Form Fields​

Validation Rules​

cURL Example​

JavaScript Example​

Python Example​

Success Response 201​

Response Types​

2) Check Translation Status​

Endpoint​

Authentication​

cURL Example​

JavaScript Example​

Python Example​

Response Format​

Status Values​

Response Types​

3) Download Translated Document​

Endpoint​

cURL Example​

JavaScript Example​

Python Example​

Response Types​

Best Practice​

Workflow

1) Upload Document

Endpoint

Authentication

Content Type

Form Fields

Validation Rules

cURL Example

JavaScript Example

Python Example

Success Response `201`

Response Types

2) Check Translation Status

Endpoint

Authentication

cURL Example

JavaScript Example

Python Example

Response Format

Status Values

Response Types

3) Download Translated Document

Endpoint

cURL Example

JavaScript Example

Python Example

Response Types

Best Practice