API de traduction de documents

Traduisez de manière asynchrone les documents pris en charge à l’aide de votre clé API.

Flux de traitement

Téléversez un document avec POST /v1/translation/document-translation/api.
Enregistrez le translationId.
Interrogez le statut avec GET /v1/translation/document-translation-status/{translationId}.
Lorsque le statut est completed, utilisez data.documentUrl pour télécharger le fichier traduit.

1) Téléverser un document

Point de terminaison

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

Authentification

x-api-key: YOUR_API_KEY

Type de contenu

Utilisez multipart/form-data et envoyez le fichier dans le champ file.

Champs du formulaire

Champs obligatoires :

file : fichier
sourceLang : chaîne de caractères
targetLang : chaîne de caractères
model : chaîne de caractères

Champs facultatifs :

domain : chaîne de caractères
writingStyle : chaîne de caractères
tone : chaîne de caractères
customPrompt : chaîne de caractères

Les codes de langue sont répertoriés dans Langues prises en charge. Les modèles pris en charge sont répertoriés dans Modèles pris en charge. Les types de fichiers pris en charge sont répertoriés dans Types de documents pris en charge.

Règles de validation

sourceLang, targetLang: Doit correspondre à ^[a-zA-Z]+(-[a-zA-Z]+)?$, 2 caractères minimum et 10 maximum.
model: Doit être l’une des valeurs de Modèles pris en charge.
file: Doit être l’une des extensions répertoriées dans Types de documents pris en charge.

Exemple 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"'

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

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

Réponse de succès `201`

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

Types de réponse

Erreur de validation de la requête (400) du middleware :

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

Aucun fichier téléversé (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."
}

Type de fichier non valide (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."
}

En-tête de clé API non valide (401):

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

Configuration de la clé API, de l’utilisateur ou de l’organisation non valide (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
}

Erreur serveur (500):

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

2) Vérifier le statut de la traduction

Point de terminaison

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

Authentification

x-api-key: YOUR_API_KEY

Exemple cURL

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

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

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

Format de la réponse

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

Valeurs de statut

waiting: La tâche est dans la file d’attente.
active: La traduction est en cours.
completed: La traduction est terminée et data.documentUrl est disponible.
failed: La traduction a échoué. Vérifiez error.

Types de réponse

ID de file d’attente manquant (400):

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

En-tête de clé API non valide (401):

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

Configuration de la clé API, de l’utilisateur ou de l’organisation non valide (400) :

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

Tâche introuvable (404):

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

Non autorisé (401) si le contexte utilisateur est manquant :

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

Accès non autorisé à la file d’attente (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
}

Échec d’une règle métier signalé par le résultat de la file d’attente (402 example):

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

Erreur serveur (500):

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

3) Télécharger le document traduit

Lorsque le statut est completed, appelez l’URL documentUrl issue de la réponse de statut.

Point de terminaison

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

Paramètre de requête facultatif :

fileType=translated (par défaut)
fileType=source

Exemple cURL

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

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

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

Types de réponse

Succès (200):

Renvoie le contenu du fichier binaire.
Les en-têtes incluent :
- Content-Type (selon le type de fichier traduit)
- Content-Disposition: attachment; filename="..."

En-tête de clé API non valide (401):

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

Configuration de la clé API, de l’utilisateur ou de l’organisation non valide (400) :

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

Erreurs de téléchargement :

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

Bonne pratique

Interrogez le statut toutes les 2 à 5 secondes jusqu’à ce que translationStatus devienne completed ou failed.

Flux de traitement​

1) Téléverser un document​

Point de terminaison​

Authentification​

Type de contenu​

Champs du formulaire​

Règles de validation​

Exemple cURL​

Exemple JavaScript​

Exemple Python​

Réponse de succès 201​

Types de réponse​

2) Vérifier le statut de la traduction​

Point de terminaison​

Authentification​

Exemple cURL​

Exemple JavaScript​

Exemple Python​

Format de la réponse​

Valeurs de statut​

Types de réponse​

3) Télécharger le document traduit​

Point de terminaison​

Exemple cURL​

Exemple JavaScript​

Exemple Python​

Types de réponse​

Bonne pratique​

Flux de traitement

1) Téléverser un document

Point de terminaison

Authentification

Type de contenu

Champs du formulaire

Règles de validation

Exemple cURL

Exemple JavaScript

Exemple Python

Réponse de succès `201`

Types de réponse

2) Vérifier le statut de la traduction

Point de terminaison

Authentification

Exemple cURL

Exemple JavaScript

Exemple Python

Format de la réponse

Valeurs de statut

Types de réponse

3) Télécharger le document traduit

Point de terminaison

Exemple cURL

Exemple JavaScript

Exemple Python

Types de réponse

Bonne pratique