Ga naar hoofdinhoud

API voor documentvertaling

Vertaal ondersteunde documentbestanden asynchroon met je API-sleutel.

Werkwijze​

  1. Upload een document met POST /v1/translation/document-translation/api.
  2. Bewaar de geretourneerde translationId.
  3. Vraag de status op met GET /v1/translation/document-translation-status/{translationId}.
  4. Wanneer de status completed is, download je het vertaalde bestand via data.documentUrl.

1) Document uploaden​

Endpoint​

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

Authenticatie​

x-api-key: YOUR_API_KEY

Inhoudstype​

Gebruik multipart/form-data en stuur het bestand mee in het veld file.

Formuliervelden​

Verplicht:

  • file bestand
  • sourceLang string
  • targetLang string
  • model string

Optioneel:

  • domain string
  • writingStyle string
  • tone string
  • customPrompt string

Taalcodes staan in Ondersteunde talen. Ondersteunde modellen staan in Ondersteunde modellen. Ondersteunde bestandstypen staan in Ondersteunde documenttypen.

Validatieregels​

  • sourceLang, targetLang: moeten overeenkomen met ^[a-zA-Z]+(-[a-zA-Z]+)?$, minimaal 2 en maximaal 10 tekens.
  • model: moet een van de waarden uit Ondersteunde modellen zijn.
  • file: moet een van de extensies uit Ondersteunde documenttypen hebben.

cURL-voorbeeld​

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-voorbeeld​

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-voorbeeld​

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

Geslaagd antwoord 201​

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

Antwoordtypen​

Validatiefout van het verzoek (400) vanuit middleware:

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

Geen bestand geüpload (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."
}

Ongeldig bestandstype (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."
}

Ongeldige API-sleutelheader (401):

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

Ongeldige configuratie van API-sleutel/gebruiker/organisatie (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
}

Serverfout (500):

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

2) Vertaalstatus controleren​

Endpoint​

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

Authenticatie​

x-api-key: YOUR_API_KEY

cURL-voorbeeld​

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

JavaScript-voorbeeld​

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-voorbeeld​

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

Antwoordformaat​

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

Statuswaarden​

  • waiting: de taak staat in de wachtrij.
  • active: de vertaling is bezig.
  • completed: de vertaling is klaar en data.documentUrl is beschikbaar.
  • failed: de vertaling is mislukt. Controleer error.

Antwoordtypen​

Wachtrij-id ontbreekt (400):

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

Ongeldige API-sleutelheader (401):

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

Ongeldige configuratie van API-sleutel/gebruiker/organisatie (400):

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

Taak niet gevonden (404):

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

Niet geautoriseerd (401) als de gebruikerscontext ontbreekt:

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

Niet-geautoriseerde toegang tot de wachtrij (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
}

Fout in bedrijfsregel uit het wachtrijresultaat (voorbeeld 402):

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

Serverfout (500):

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

3) Vertaald document downloaden​

Wanneer de status completed is, roep je de documentUrl uit het statusantwoord aan.

Endpoint​

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

Optionele queryparameter:

  • fileType=translated (standaard)
  • fileType=source

cURL-voorbeeld​

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

JavaScript-voorbeeld​

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-voorbeeld​

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

Antwoordtypen​

Geslaagd (200):

  • Retourneert de binaire bestandsinhoud.
  • Headers bevatten onder meer:
    • Content-Type (afhankelijk van het vertaalde bestandstype)
    • Content-Disposition: attachment; filename="..."

Ongeldige API-sleutelheader (401):

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

Ongeldige configuratie van API-sleutel/gebruiker/organisatie (400):

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

Downloadfouten:

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

Aanbevolen werkwijze​

Vraag de status elke 2 tot 5 seconden op totdat translationStatus completed of failed is.