API de tradução de documentos

Traduza arquivos de documentos compatíveis de forma assíncrona usando sua chave de API.

Fluxo de trabalho

Envie um documento usando POST /v1/translation/document-translation/api.
Guarde o translationId retornado.
Consulte o status usando GET /v1/translation/document-translation-status/{translationId}.
Quando o status for completed, use data.documentUrl para baixar o arquivo traduzido.

1) Enviar o documento

Endpoint

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

Autenticação

x-api-key: YOUR_API_KEY

Tipo de conteúdo

Use multipart/form-data e envie o arquivo no campo file.

Campos do formulário

Obrigatórios:

file arquivo
sourceLang string
targetLang string
model string

Opcionais:

domain string
writingStyle string
tone string
customPrompt string

Os códigos de idioma estão listados em Idiomas compatíveis. Os modelos compatíveis estão listados em Modelos compatíveis. Os tipos de arquivo compatíveis estão listados em Tipos de documento compatíveis.

Regras de validação

sourceLang, targetLang: devem corresponder a ^[a-zA-Z]+(-[a-zA-Z]+)?$, mínimo de 2 caracteres, máximo de 10 caracteres.
model: deve ser um dos valores em Modelos compatíveis.
file: deve ter uma das extensões em Tipos de documento compatíveis.

Exemplo com 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"'

Exemplo em 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);
}

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

Resposta de sucesso `201`

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

Tipos de resposta

Erro de validação da requisição (400) vindo do middleware:

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

Nenhum arquivo enviado (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 arquivo invá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."
}

Cabeçalho de chave de API inválido (401):

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

Configuração inválida de chave de API, usuário ou organização (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
}

Erro do 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) Verificar o status da tradução

Endpoint

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

Autenticação

x-api-key: YOUR_API_KEY

Exemplo com cURL

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

Exemplo em 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);

Exemplo em 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 da resposta

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

Valores de status

waiting: o trabalho está na fila.
active: a tradução está em andamento.
completed: a tradução foi concluída e data.documentUrl está disponível.
failed: a tradução falhou. Verifique error.

Tipos de resposta

ID da fila ausente (400):

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

Cabeçalho de chave de API inválido (401):

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

Configuração inválida de chave de API, usuário ou organização (400):

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

Trabalho não encontrado (404):

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

Não autorizado (401) se o contexto do usuário estiver ausente:

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

Acesso à fila não 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
}

Falha de regra de negócio retornada pelo resultado da fila (exemplo 402):

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

Erro do servidor (500):

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

3) Baixar o documento traduzido

Quando o status for completed, chame a documentUrl da resposta de status.

Endpoint

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

Parâmetro de consulta opcional:

fileType=translated (padrão)
fileType=source

Exemplo com cURL

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

Exemplo em 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);
}

Exemplo em 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 resposta

Sucesso (200):

Retorna o conteúdo binário do arquivo.
Os cabeçalhos incluem:
- Content-Type (conforme o tipo do arquivo traduzido)
- Content-Disposition: attachment; filename="..."

Cabeçalho de chave de API inválido (401):

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

Configuração inválida de chave de API, usuário ou organização (400):

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

Erros de download:

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

Boas práticas

Consulte o status a cada 2 a 5 segundos até que translationStatus seja completed ou failed.

Fluxo de trabalho​

1) Enviar o documento​

Endpoint​

Autenticação​

Tipo de conteúdo​

Campos do formulário​

Regras de validação​

Exemplo com cURL​

Exemplo em JavaScript​

Exemplo em Python​

Resposta de sucesso 201​

Tipos de resposta​

2) Verificar o status da tradução​

Endpoint​

Autenticação​

Exemplo com cURL​

Exemplo em JavaScript​

Exemplo em Python​

Formato da resposta​

Valores de status​

Tipos de resposta​

3) Baixar o documento traduzido​

Endpoint​

Exemplo com cURL​

Exemplo em JavaScript​

Exemplo em Python​

Tipos de resposta​

Boas práticas​

Fluxo de trabalho

1) Enviar o documento

Endpoint

Autenticação

Tipo de conteúdo

Campos do formulário

Regras de validação

Exemplo com cURL

Exemplo em JavaScript

Exemplo em Python

Resposta de sucesso `201`

Tipos de resposta

2) Verificar o status da tradução

Endpoint

Autenticação

Exemplo com cURL

Exemplo em JavaScript

Exemplo em Python

Formato da resposta

Valores de status

Tipos de resposta

3) Baixar o documento traduzido

Endpoint

Exemplo com cURL

Exemplo em JavaScript

Exemplo em Python

Tipos de resposta

Boas práticas