Dokumentübersetzungs-API

Übersetzen Sie unterstützte Dokumentdateien mit Ihrem API-Schlüssel asynchron.

Arbeitsablauf

Laden Sie ein Dokument mit POST /v1/translation/document-translation/api hoch.
Speichern Sie die zurückgegebene translationId.
Fragen Sie den Status mit GET /v1/translation/document-translation-status/{translationId} ab.
Wenn der Status „completed“ lautet, laden Sie die übersetzte Datei über data.documentUrl herunter.

1) Dokument hochladen

Endpunkt

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

Authentifizierung

x-api-key: YOUR_API_KEY

Inhaltstyp

Verwenden Sie multipart/form-data und senden Sie die Datei im Feld file.

Formularfelder

Erforderlich:

file Datei
sourceLang String
targetLang String
model String

Optional:

domain String
writingStyle String
tone String
customPrompt String

Sprachcodes sind aufgeführt unter Unterstützte Sprachen. Unterstützte Modelle sind aufgeführt unter Unterstützte Modelle. Unterstützte Dateitypen sind aufgeführt unter Unterstützte Dokumenttypen.

Validierungsregeln

sourceLang, targetLang: Muss übereinstimmen mit ^[a-zA-Z]+(-[a-zA-Z]+)?$, min 2 chars, max 10 chars.
model: Muss einem der Werte aus entsprechen Unterstützte Modelle.
file: Muss eine der Dateiendungen aus Unterstützte Dokumenttypen haben.

cURL-Beispiel

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

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

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

Erfolgsantwort `201`

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

Antworttypen

Validierungsfehler der Anfrage (400) aus der Middleware:

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

Keine Datei hochgeladen (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."
}

Ungültiger Dateityp (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."
}

Ungültiger API-Schlüssel-Header (401):

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

Ungültige Einrichtung von API-Schlüssel, Benutzer oder Organisation (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
}

Serverfehler (500):

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

2) Übersetzungsstatus prüfen

Endpunkt

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

Authentifizierung

x-api-key: YOUR_API_KEY

cURL-Beispiel

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

JavaScript-Beispiel

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

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

Antwortformat

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

Statuswerte

waiting: Der Auftrag befindet sich in der Warteschlange.
active: Die Übersetzung läuft.
completed: Die Übersetzung ist abgeschlossen und data.documentUrl ist verfügbar.
failed: Die Übersetzung ist fehlgeschlagen. Prüfen Sie error.

Antworttypen

Warteschlangen-ID fehlt (400):

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

Ungültiger API-Schlüssel-Header (401):

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

Ungültige Einrichtung von API-Schlüssel, Benutzer oder Organisation (400):

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

Auftrag nicht gefunden (404):

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

Nicht autorisiert (401) if user context is missing:

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

Nicht autorisierter Zugriff auf die Warteschlange (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
}

Geschäftsregelfehler aus dem Warteschlangenergebnis (Beispiel 402):

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

Serverfehler (500):

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

3) Übersetztes Dokument herunterladen

Wenn der Status completed ist, rufen Sie die documentUrl aus der Statusantwort auf.

Endpunkt

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

Optionale Abfrage:

fileType=translated (Standard)
fileType=source

cURL-Beispiel

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

JavaScript-Beispiel

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

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

Antworttypen

Erfolg (200):

Gibt den binären Dateiinhalt zurück.
Die Header enthalten:
- Content-Type (abhängig vom Typ der übersetzten Datei)
- Content-Disposition: attachment; filename="..."

Ungültiger API-Schlüssel-Header (401):

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

Ungültige Einrichtung von API-Schlüssel, Benutzer oder Organisation (400):

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

Downloadfehler:

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

Bewährte Vorgehensweise

Fragen Sie den Status alle 2 bis 5 Sekunden ab, bis translationStatus becomes completed or failed.

Arbeitsablauf​

1) Dokument hochladen​

Endpunkt​

Authentifizierung​

Inhaltstyp​

Formularfelder​

Validierungsregeln​

cURL-Beispiel​

JavaScript-Beispiel​

Python-Beispiel​

Erfolgsantwort 201​

Antworttypen​

2) Übersetzungsstatus prüfen​

Endpunkt​

Authentifizierung​

cURL-Beispiel​

JavaScript-Beispiel​

Python-Beispiel​

Antwortformat​

Statuswerte​

Antworttypen​

3) Übersetztes Dokument herunterladen​

Endpunkt​

cURL-Beispiel​

JavaScript-Beispiel​

Python-Beispiel​

Antworttypen​

Bewährte Vorgehensweise​

Arbeitsablauf

1) Dokument hochladen

Endpunkt

Authentifizierung

Inhaltstyp

Formularfelder

Validierungsregeln

cURL-Beispiel

JavaScript-Beispiel

Python-Beispiel

Erfolgsantwort `201`

Antworttypen

2) Übersetzungsstatus prüfen

Endpunkt

Authentifizierung

cURL-Beispiel

JavaScript-Beispiel

Python-Beispiel

Antwortformat

Statuswerte

Antworttypen

3) Übersetztes Dokument herunterladen

Endpunkt

cURL-Beispiel

JavaScript-Beispiel

Python-Beispiel

Antworttypen

Bewährte Vorgehensweise