API na preklad dokumentov

Prekladajte podporované dokumenty asynchrónne pomocou svojho API kľúča.

Postup

Nahrajte dokument pomocou POST /v1/translation/document-translation/api.
Uložte si vrátené translationId.
Zisťujte stav pomocou GET /v1/translation/document-translation-status/{translationId}.
Keď je stav completed, stiahnite preložený súbor cez data.documentUrl.

1) Nahratie dokumentu

Endpoint

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

Overenie

x-api-key: YOUR_API_KEY

Typ obsahu

Použite multipart/form-data a súbor pošlite v poli file.

Polia formulára

Povinné:

file súbor
sourceLang reťazec
targetLang reťazec
model reťazec

Voliteľné:

domain reťazec
writingStyle reťazec
tone reťazec
customPrompt reťazec

Kódy jazykov sú uvedené v časti Podporované jazyky. Podporované modely sú uvedené v časti Podporované modely. Podporované typy súborov sú uvedené v časti Podporované typy dokumentov.

Pravidlá validácie

sourceLang, targetLang: musia zodpovedať ^[a-zA-Z]+(-[a-zA-Z]+)?$, najmenej 2 a najviac 10 znakov.
model: musí byť jednou z hodnôt v časti Podporované modely.
file: musí mať jednu z prípon v časti Podporované typy dokumentov.

Príklad 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"'

Príklad v JavaScripte

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);
}

Príklad v Pythone

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

Úspešná odpoveď `201`

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

Typy odpovedí

Chyba validácie požiadavky (400) z middleware:

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

Nebol nahratý žiadny súbor (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."
}

Neplatný typ súboru (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."
}

Neplatná hlavička API kľúča (401):

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

Neplatné nastavenie API kľúča, používateľa alebo organizácie (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
}

Chyba servera (500):

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

2) Kontrola stavu prekladu

Endpoint

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

Overenie

x-api-key: YOUR_API_KEY

Príklad cURL

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

Príklad v JavaScripte

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

Príklad v Pythone

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

Formát odpovede

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

Hodnoty stavu

waiting: úloha čaká vo fronte.
active: preklad prebieha.
completed: preklad je dokončený a data.documentUrl je k dispozícii.
failed: preklad zlyhal. Pozrite si error.

Typy odpovedí

Chýba ID fronty (400):

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

Neplatná hlavička API kľúča (401):

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

Neplatné nastavenie API kľúča, používateľa alebo organizácie (400):

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

Úloha sa nenašla (404):

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

Neoprávnený prístup (401), ak chýba kontext používateľa:

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

Neoprávnený prístup k fronte (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
}

Porušenie obchodného pravidla vrátené výsledkom fronty (príklad 402):

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

Chyba servera (500):

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

3) Stiahnutie preloženého dokumentu

Keď je stav completed, zavolajte documentUrl z odpovede o stave.

Endpoint

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

Voliteľný parameter dopytu:

fileType=translated (predvolené)
fileType=source

Príklad cURL

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

Príklad v JavaScripte

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);
}

Príklad v Pythone

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

Typy odpovedí

Úspech (200):

Vráti binárny obsah súboru.
Hlavičky obsahujú:
- Content-Type (podľa typu preloženého súboru)
- Content-Disposition: attachment; filename="..."

Neplatná hlavička API kľúča (401):

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

Neplatné nastavenie API kľúča, používateľa alebo organizácie (400):

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

Chyby pri sťahovaní:

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

Odporúčaný postup

Zisťujte stav každé 2 až 5 sekúnd, kým translationStatus nebude completed alebo failed.

Postup​

1) Nahratie dokumentu​

Endpoint​

Overenie​

Typ obsahu​

Polia formulára​

Pravidlá validácie​

Príklad cURL​

Príklad v JavaScripte​

Príklad v Pythone​

Úspešná odpoveď 201​

Typy odpovedí​

2) Kontrola stavu prekladu​

Endpoint​

Overenie​

Príklad cURL​

Príklad v JavaScripte​

Príklad v Pythone​

Formát odpovede​

Hodnoty stavu​

Typy odpovedí​

3) Stiahnutie preloženého dokumentu​

Endpoint​

Príklad cURL​

Príklad v JavaScripte​

Príklad v Pythone​

Typy odpovedí​

Odporúčaný postup​

Postup

1) Nahratie dokumentu

Endpoint

Overenie

Typ obsahu

Polia formulára

Pravidlá validácie

Príklad cURL

Príklad v JavaScripte

Príklad v Pythone

Úspešná odpoveď `201`

Typy odpovedí

2) Kontrola stavu prekladu

Endpoint

Overenie

Príklad cURL

Príklad v JavaScripte

Príklad v Pythone

Formát odpovede

Hodnoty stavu

Typy odpovedí

3) Stiahnutie preloženého dokumentu

Endpoint

Príklad cURL

Príklad v JavaScripte

Príklad v Pythone

Typy odpovedí

Odporúčaný postup