API de traducción de documentos

Traduce archivos de documentos compatibles de forma asíncrona con tu clave de API.

Flujo de trabajo

Sube un documento con POST /v1/translation/document-translation/api.
Guarda el translationId devuelto.
Consulta el estado con GET /v1/translation/document-translation-status/{translationId}.
Cuando el estado sea completed, usa data.documentUrl para descargar el archivo traducido.

1) Subir el documento

Endpoint

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

Autenticación

x-api-key: YOUR_API_KEY

Tipo de contenido

Usa multipart/form-data y envía el archivo en el campo file.

Campos del formulario

Obligatorios:

file archivo
sourceLang cadena
targetLang cadena
model cadena

Opcionales:

domain cadena
writingStyle cadena
tone cadena
customPrompt cadena

Los códigos de idioma se indican en Idiomas compatibles. Los modelos compatibles se indican en Modelos compatibles. Los tipos de archivo compatibles se indican en Tipos de documento compatibles.

Reglas de validación

sourceLang, targetLang: deben coincidir con ^[a-zA-Z]+(-[a-zA-Z]+)?$, mínimo 2 caracteres, máximo 10 caracteres.
model: debe ser uno de los valores de Modelos compatibles.
file: debe tener una de las extensiones de Tipos de documento compatibles.

Ejemplo con 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"'

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

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

Respuesta correcta `201`

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

Tipos de respuesta

Error de validación de la solicitud (400) desde el middleware:

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

No se subió ningún archivo (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."
}

Tipo de archivo no válido (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."
}

Encabezado de clave de API no válido (401):

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

Configuración no válida de clave de API, usuario u organización (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
}

Error del servidor (500):

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

2) Consultar el estado de la traducción

Endpoint

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

Autenticación

x-api-key: YOUR_API_KEY

Ejemplo con cURL

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

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

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

Formato de respuesta

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

Valores de estado

waiting: el trabajo está en cola.
active: la traducción está en curso.
completed: la traducción ha terminado y data.documentUrl está disponible.
failed: la traducción ha fallado. Revisa error.

Tipos de respuesta

Falta el id de la cola (400):

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

Encabezado de clave de API no válido (401):

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

Configuración no válida de clave de API, usuario u organización (400):

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

Trabajo no encontrado (404):

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

No autorizado (401) si falta el contexto del usuario:

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

Acceso a la cola no autorizado (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
}

Fallo de regla de negocio devuelto por el resultado de la cola (ejemplo 402):

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

Error del servidor (500):

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

3) Descargar el documento traducido

Cuando el estado sea completed, llama a la documentUrl de la respuesta de estado.

Endpoint

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

Parámetro de consulta opcional:

fileType=translated (predeterminado)
fileType=source

Ejemplo con cURL

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

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

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

Tipos de respuesta

Correcto (200):

Devuelve el contenido binario del archivo.
Los encabezados incluyen:
- Content-Type (según el tipo del archivo traducido)
- Content-Disposition: attachment; filename="..."

Encabezado de clave de API no válido (401):

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

Configuración no válida de clave de API, usuario u organización (400):

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

Errores de descarga:

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

Buenas prácticas

Consulta el estado cada 2 a 5 segundos hasta que translationStatus sea completed o failed.

Flujo de trabajo​

1) Subir el documento​

Endpoint​

Autenticación​

Tipo de contenido​

Campos del formulario​

Reglas de validación​

Ejemplo con cURL​

Ejemplo en JavaScript​

Ejemplo en Python​

Respuesta correcta 201​

Tipos de respuesta​

2) Consultar el estado de la traducción​

Endpoint​

Autenticación​

Ejemplo con cURL​

Ejemplo en JavaScript​

Ejemplo en Python​

Formato de respuesta​

Valores de estado​

Tipos de respuesta​

3) Descargar el documento traducido​

Endpoint​

Ejemplo con cURL​

Ejemplo en JavaScript​

Ejemplo en Python​

Tipos de respuesta​

Buenas prácticas​

Flujo de trabajo

1) Subir el documento

Endpoint

Autenticación

Tipo de contenido

Campos del formulario

Reglas de validación

Ejemplo con cURL

Ejemplo en JavaScript

Ejemplo en Python

Respuesta correcta `201`

Tipos de respuesta

2) Consultar el estado de la traducción

Endpoint

Autenticación

Ejemplo con cURL

Ejemplo en JavaScript

Ejemplo en Python

Formato de respuesta

Valores de estado

Tipos de respuesta

3) Descargar el documento traducido

Endpoint

Ejemplo con cURL

Ejemplo en JavaScript

Ejemplo en Python

Tipos de respuesta

Buenas prácticas