Asiakirjojen käännös-API

Käännä tuettuja asiakirjatiedostoja asynkronisesti API-avaimellasi.

Työnkulku

Lataa asiakirja käyttämällä POST /v1/translation/document-translation/api.
Tallenna palautettu translationId.
Kysy tilaa käyttämällä GET /v1/translation/document-translation-status/{translationId}.
Kun tila on completed, lataa käännetty tiedosto osoitteesta data.documentUrl.

1) Asiakirjan lataaminen

Päätepiste

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

Todennus

x-api-key: YOUR_API_KEY

Sisältötyyppi

Käytä multipart/form-data-muotoa ja lähetä tiedosto kentässä file.

Lomakkeen kentät

Pakolliset:

file tiedosto
sourceLang merkkijono
targetLang merkkijono
model merkkijono

Valinnaiset:

domain merkkijono
writingStyle merkkijono
tone merkkijono
customPrompt merkkijono

Kielikoodit on lueteltu sivulla Tuetut kielet. Tuetut mallit on lueteltu sivulla Tuetut mallit. Tuetut tiedostotyypit on lueteltu sivulla Tuetut asiakirjatyypit.

Validointisäännöt

sourceLang, targetLang: täytyy vastata lauseketta ^[a-zA-Z]+(-[a-zA-Z]+)?$, vähintään 2 ja enintään 10 merkkiä.
model: täytyy olla jokin sivun Tuetut mallit arvoista.
file: tiedostopäätteen täytyy olla jokin sivun Tuetut asiakirjatyypit päätteistä.

cURL-esimerkki

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-esimerkki

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-esimerkki

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

Onnistunut vastaus `201`

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

Vastaustyypit

Pyynnön validointivirhe (400) middlewarelta:

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

Tiedostoa ei ladattu (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."
}

Virheellinen tiedostotyyppi (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."
}

Virheellinen API-avaimen otsake (401):

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

Virheelliset API-avaimen, käyttäjän tai organisaation asetukset (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
}

Palvelinvirhe (500):

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

2) Käännöksen tilan tarkistaminen

Päätepiste

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

Todennus

x-api-key: YOUR_API_KEY

cURL-esimerkki

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

JavaScript-esimerkki

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-esimerkki

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

Vastauksen muoto

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

Tila-arvot

waiting: työ on jonossa.
active: käännös on käynnissä.
completed: käännös on valmis ja data.documentUrl on käytettävissä.
failed: käännös epäonnistui. Tarkista error.

Vastaustyypit

Jonon tunnus puuttuu (400):

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

Virheellinen API-avaimen otsake (401):

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

Virheelliset API-avaimen, käyttäjän tai organisaation asetukset (400):

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

Työtä ei löytynyt (404):

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

Ei käyttöoikeutta (401), jos käyttäjäkonteksti puuttuu:

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

Luvaton pääsy jonoon (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
}

Jonon tuloksen palauttama liiketoimintasäännön virhe (esimerkki 402):

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

Palvelinvirhe (500):

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

3) Käännetyn asiakirjan lataaminen

Kun tila on completed, kutsu tilavastauksen documentUrl-osoitetta.

Päätepiste

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

Valinnainen kyselyparametri:

fileType=translated (oletus)
fileType=source

cURL-esimerkki

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

JavaScript-esimerkki

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-esimerkki

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

Vastaustyypit

Onnistui (200):

Palauttaa tiedoston binäärisisällön.
Otsakkeet sisältävät:
- Content-Type (käännetyn tiedoston tyypin mukaan)
- Content-Disposition: attachment; filename="..."

Virheellinen API-avaimen otsake (401):

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

Virheelliset API-avaimen, käyttäjän tai organisaation asetukset (400):

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

Latausvirheet:

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

Suositeltu käytäntö

Kysy tilaa 2–5 sekunnin välein, kunnes translationStatus on completed tai failed.

Työnkulku​

1) Asiakirjan lataaminen​

Päätepiste​

Todennus​

Sisältötyyppi​

Lomakkeen kentät​

Validointisäännöt​

cURL-esimerkki​

JavaScript-esimerkki​

Python-esimerkki​

Onnistunut vastaus 201​

Vastaustyypit​

2) Käännöksen tilan tarkistaminen​

Päätepiste​

Todennus​

cURL-esimerkki​

JavaScript-esimerkki​

Python-esimerkki​

Vastauksen muoto​

Tila-arvot​

Vastaustyypit​

3) Käännetyn asiakirjan lataaminen​

Päätepiste​

cURL-esimerkki​

JavaScript-esimerkki​

Python-esimerkki​

Vastaustyypit​

Suositeltu käytäntö​

Työnkulku

1) Asiakirjan lataaminen

Päätepiste

Todennus

Sisältötyyppi

Lomakkeen kentät

Validointisäännöt

cURL-esimerkki

JavaScript-esimerkki

Python-esimerkki

Onnistunut vastaus `201`

Vastaustyypit

2) Käännöksen tilan tarkistaminen

Päätepiste

Todennus

cURL-esimerkki

JavaScript-esimerkki

Python-esimerkki

Vastauksen muoto

Tila-arvot

Vastaustyypit

3) Käännetyn asiakirjan lataaminen

Päätepiste

cURL-esimerkki

JavaScript-esimerkki

Python-esimerkki

Vastaustyypit

Suositeltu käytäntö