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) от middleware:

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

Порядок работы​

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

Типы ответов

Рекомендация