Belge Çeviri API'si

Desteklenen belge dosyalarını API anahtarınızla eşzamansız olarak çevirin.

İş akışı

POST /v1/translation/document-translation/api ile bir belge yükleyin.
Dönen translationId değerini kaydedin.
Durumu GET /v1/translation/document-translation-status/{translationId} ile sorgulayın.
Durum completed olduğunda çevrilmiş dosyayı indirmek için data.documentUrl kullanın.

1) Belgeyi yükleyin

Uç nokta

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

Kimlik doğrulama

x-api-key: YOUR_API_KEY

İçerik türü

multipart/form-data kullanın ve dosyayı file alanında gönderin.

Form alanları

Zorunlu:

file dosya
sourceLang string
targetLang string
model string

İsteğe bağlı:

domain string
writingStyle string
tone string
customPrompt string

Dil kodları Desteklenen Diller sayfasında listelenmiştir. Desteklenen modeller Desteklenen Modeller sayfasında listelenmiştir. Desteklenen dosya türleri Desteklenen Belge Türleri sayfasında listelenmiştir.

Doğrulama kuralları

sourceLang, targetLang: ^[a-zA-Z]+(-[a-zA-Z]+)?$ ile eşleşmelidir, en az 2, en fazla 10 karakter.
model: Desteklenen Modeller içindeki değerlerden biri olmalıdır.
file: Desteklenen Belge Türleri içindeki uzantılardan birine sahip olmalıdır.

cURL örneği

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 örneği

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 örneği

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

Başarılı yanıt `201`

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

Yanıt türleri

Middleware'den gelen istek doğrulama hatası (400):

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

Dosya yüklenmedi (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."
}

Geçersiz dosya türü (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."
}

Geçersiz API anahtarı başlığı (401):

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

Geçersiz API anahtarı/kullanıcı/kuruluş yapılandırması (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
}

Sunucu hatası (500):

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

2) Çeviri durumunu kontrol edin

Uç nokta

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

Kimlik doğrulama

x-api-key: YOUR_API_KEY

cURL örneği

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

JavaScript örneği

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 örneği

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

Yanıt biçimi

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

Durum değerleri

waiting: İş kuyrukta.
active: Çeviri devam ediyor.
completed: Çeviri tamamlandı ve data.documentUrl kullanılabilir.
failed: Çeviri başarısız oldu. error alanını kontrol edin.

Yanıt türleri

Kuyruk kimliği eksik (400):

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

Geçersiz API anahtarı başlığı (401):

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

Geçersiz API anahtarı/kullanıcı/kuruluş yapılandırması (400):

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

İş bulunamadı (404):

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

Kullanıcı bağlamı eksikse yetkisiz (401):

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

Yetkisiz kuyruk erişimi (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
}

Kuyruk sonucundan gelen iş kuralı hatası (402 örneği):

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

Sunucu hatası (500):

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

3) Çevrilmiş belgeyi indirin

Durum completed olduğunda, durum yanıtındaki documentUrl adresini çağırın.

Uç nokta

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

İsteğe bağlı sorgu:

fileType=translated (varsayılan)
fileType=source

cURL örneği

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

JavaScript örneği

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 örneği

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

Yanıt türleri

Başarılı (200):

İkili dosya içeriğini döndürür.
Başlıklar şunları içerir:
- Content-Type (çevrilmiş dosya türüne göre)
- Content-Disposition: attachment; filename="..."

Geçersiz API anahtarı başlığı (401):

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

Geçersiz API anahtarı/kullanıcı/kuruluş yapılandırması (400):

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

İndirme hataları:

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

En iyi uygulama

translationStatus değeri completed veya failed olana kadar durumu 2 ila 5 saniyede bir sorgulayın.

İş akışı​

1) Belgeyi yükleyin​

Uç nokta​

Kimlik doğrulama​

İçerik türü​

Form alanları​

Doğrulama kuralları​

cURL örneği​

JavaScript örneği​

Python örneği​

Başarılı yanıt 201​

Yanıt türleri​

2) Çeviri durumunu kontrol edin​

Uç nokta​

Kimlik doğrulama​

cURL örneği​

JavaScript örneği​

Python örneği​

Yanıt biçimi​

Durum değerleri​

Yanıt türleri​

3) Çevrilmiş belgeyi indirin​

Uç nokta​

cURL örneği​

JavaScript örneği​

Python örneği​

Yanıt türleri​

En iyi uygulama​

İş akışı

1) Belgeyi yükleyin

Uç nokta

Kimlik doğrulama

İçerik türü

Form alanları

Doğrulama kuralları

cURL örneği

JavaScript örneği

Python örneği

Başarılı yanıt `201`

Yanıt türleri

2) Çeviri durumunu kontrol edin

Uç nokta

Kimlik doğrulama

cURL örneği

JavaScript örneği

Python örneği

Yanıt biçimi

Durum değerleri

Yanıt türleri

3) Çevrilmiş belgeyi indirin

Uç nokta

cURL örneği

JavaScript örneği

Python örneği

Yanıt türleri

En iyi uygulama