API Terjemahan Dokumen

Terjemahkan file dokumen yang didukung secara asinkron menggunakan kunci API Anda.

Alur kerja

Unggah dokumen menggunakan POST /v1/translation/document-translation/api.
Simpan translationId yang dikembalikan.
Periksa status menggunakan GET /v1/translation/document-translation-status/{translationId}.
Jika status sudah completed, gunakan data.documentUrl untuk mengunduh file terjemahan.

1) Unggah Dokumen

Endpoint

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

Autentikasi

x-api-key: YOUR_API_KEY

Tipe Konten

Gunakan multipart/form-data dan kirim file pada field file.

Field Formulir

Wajib:

file file
sourceLang string
targetLang string
model string

Opsional:

domain string
writingStyle string
tone string
customPrompt string

Kode bahasa tercantum di Bahasa yang Didukung. Model yang didukung tercantum di Model yang Didukung. Jenis file yang didukung tercantum di Jenis Dokumen yang Didukung.

Aturan Validasi

sourceLang, targetLang: Harus cocok dengan ^[a-zA-Z]+(-[a-zA-Z]+)?$, minimal 2 karakter, maksimal 10 karakter.
model: Harus salah satu nilai di Model yang Didukung.
file: Harus memiliki salah satu ekstensi di Jenis Dokumen yang Didukung.

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

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

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

Respons Berhasil `201`

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

Jenis Respons

Kesalahan validasi permintaan (400) dari middleware:

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

Tidak ada file yang diunggah (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."
}

Jenis file tidak valid (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."
}

Header kunci API tidak valid (401):

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

Pengaturan kunci API/pengguna/organisasi tidak valid (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
}

Kesalahan server (500):

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

2) Periksa Status Terjemahan

Endpoint

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

Autentikasi

x-api-key: YOUR_API_KEY

Contoh cURL

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

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

Contoh 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 Respons

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

Nilai Status

waiting: Pekerjaan sedang dalam antrean.
active: Terjemahan sedang berlangsung.
completed: Terjemahan selesai dan data.documentUrl tersedia.
failed: Terjemahan gagal. Periksa error.

Jenis Respons

ID antrean tidak ada (400):

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

Header kunci API tidak valid (401):

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

Pengaturan kunci API/pengguna/organisasi tidak valid (400):

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

Pekerjaan tidak ditemukan (404):

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

Tidak sah (401) jika konteks pengguna tidak ada:

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

Akses antrean tidak sah (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
}

Kegagalan aturan bisnis dari hasil antrean (contoh 402):

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

Kesalahan server (500):

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

3) Unduh Dokumen Terjemahan

Jika status completed, panggil documentUrl dari respons status.

Endpoint

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

Kueri opsional:

fileType=translated (default)
fileType=source

Contoh cURL

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

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

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

Jenis Respons

Berhasil (200):

Mengembalikan konten file biner.
Header mencakup:
- Content-Type (sesuai jenis file terjemahan)
- Content-Disposition: attachment; filename="..."

Header kunci API tidak valid (401):

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

Pengaturan kunci API/pengguna/organisasi tidak valid (400):

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

Kesalahan unduhan:

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

Praktik Terbaik

Periksa status setiap 2 hingga 5 detik sampai translationStatus menjadi completed atau failed.

Alur kerja​

1) Unggah Dokumen​

Endpoint​

Autentikasi​

Tipe Konten​

Field Formulir​

Aturan Validasi​

Contoh cURL​

Contoh JavaScript​

Contoh Python​

Respons Berhasil 201​

Jenis Respons​

2) Periksa Status Terjemahan​

Endpoint​

Autentikasi​

Contoh cURL​

Contoh JavaScript​

Contoh Python​

Format Respons​

Nilai Status​

Jenis Respons​

3) Unduh Dokumen Terjemahan​

Endpoint​

Contoh cURL​

Contoh JavaScript​

Contoh Python​

Jenis Respons​

Praktik Terbaik​

Alur kerja

1) Unggah Dokumen

Endpoint

Autentikasi

Tipe Konten

Field Formulir

Aturan Validasi

Contoh cURL

Contoh JavaScript

Contoh Python

Respons Berhasil `201`

Jenis Respons

2) Periksa Status Terjemahan

Endpoint

Autentikasi

Contoh cURL

Contoh JavaScript

Contoh Python

Format Respons

Nilai Status

Jenis Respons

3) Unduh Dokumen Terjemahan

Endpoint

Contoh cURL

Contoh JavaScript

Contoh Python

Jenis Respons

Praktik Terbaik