واجهة API لترجمة المستندات

ترجم ملفات المستندات المدعومة بشكل غير متزامن باستخدام مفتاح API.

سير العمل

ارفع مستندًا باستخدام POST /v1/translation/document-translation/api.
احفظ القيمة المعادة translationId.
استعلم عن الحالة باستخدام GET /v1/translation/document-translation-status/{translationId}.
عندما تكون الحالة completed، استخدم data.documentUrl لتنزيل الملف المترجم.

1) تحميل مستند

نقطة النهاية

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

المصادقة

x-api-key: YOUR_API_KEY

نوع المحتوى

استخدم multipart/form-data وأرسل الملف في الحقل file.

حقول النموذج

مطلوب:

file ملف
sourceLang نص
targetLang نص
model نص

اختياري:

domain نص
writingStyle نص
tone نص
customPrompt نص

رموز اللغات مدرجة في اللغات المدعومة. النماذج المدعومة مدرجة في النماذج المدعومة. أنواع الملفات المدعومة مدرجة في أنواع المستندات المدعومة.

قواعد التحقق

sourceLang, targetLang: يجب أن يطابق ^[a-zA-Z]+(-[a-zA-Z]+)?$, بحد أدنى حرفان وبحد أقصى 10 أحرف.
model: يجب أن تكون إحدى القيم في النماذج المدعومة.
file: يجب أن يكون أحد الامتدادات في أنواع المستندات المدعومة.

مثال 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"'

مثال 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);
}

مثال 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())

استجابة النجاح `201`

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

أنواع الاستجابة

خطأ التحقق من الطلب (400) من وسيط التحقق:

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

لم يتم تحميل أي ملف (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."
}

نوع الملف غير صالح (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."
}

ترويسة مفتاح API غير صالحة (401):

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

إعداد غير صالح لمفتاح API أو المستخدم أو المؤسسة (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
}

خطأ في الخادم (500):

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

2) التحقق من حالة الترجمة

نقطة النهاية

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

المصادقة

x-api-key: YOUR_API_KEY

مثال cURL

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

مثال 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);

مثال 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())

تنسيق الاستجابة

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

قيم الحالة

waiting: المهمة في قائمة الانتظار.
active: الترجمة قيد التنفيذ.
completed: اكتملت الترجمة وأصبح data.documentUrl متاحًا.
failed: فشلت الترجمة. تحقق من error.

أنواع الاستجابة

معرّف قائمة الانتظار مفقود (400):

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

ترويسة مفتاح API غير صالحة (401):

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

إعداد غير صالح لمفتاح API أو المستخدم أو المؤسسة (400):

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

لم يتم العثور على المهمة (404):

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

غير مصرح (401) إذا كان سياق المستخدم مفقودًا:

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

وصول غير مصرح به إلى قائمة الانتظار (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
}

ظهر إخفاق قاعدة العمل في نتيجة قائمة الانتظار (402 example):

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

خطأ في الخادم (500):

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

3) تنزيل المستند المترجم

عندما تكون الحالة completed, استدعِ documentUrl من استجابة الحالة.

نقطة النهاية

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

معامل استعلام اختياري:

fileType=translated (افتراضيًا)
fileType=source

مثال cURL

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

مثال 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);
}

مثال 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")

أنواع الاستجابة

نجاح (200):

يعيد محتوى الملف الثنائي.
تتضمن الترويسات:
- Content-Type (حسب نوع الملف المترجم)
- Content-Disposition: attachment; filename="..."

ترويسة مفتاح API غير صالحة (401):

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

إعداد غير صالح لمفتاح API أو المستخدم أو المؤسسة (400):

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

أخطاء التنزيل:

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

أفضل ممارسة

استعلم عن الحالة كل ثانيتين إلى خمس ثوانٍ حتى تصبح translationStatus تصبح completed or failed.

سير العمل​

1) تحميل مستند​

نقطة النهاية​

المصادقة​

نوع المحتوى​

حقول النموذج​

قواعد التحقق​

مثال cURL​

مثال JavaScript​

مثال Python​

استجابة النجاح 201​

أنواع الاستجابة​

2) التحقق من حالة الترجمة​

نقطة النهاية​

المصادقة​

مثال cURL​

مثال JavaScript​

مثال Python​

تنسيق الاستجابة​

قيم الحالة​

أنواع الاستجابة​

3) تنزيل المستند المترجم​

نقطة النهاية​

مثال cURL​

مثال JavaScript​

مثال Python​

أنواع الاستجابة​

أفضل ممارسة​

سير العمل

1) تحميل مستند

نقطة النهاية

المصادقة

نوع المحتوى

حقول النموذج

قواعد التحقق

مثال cURL

مثال JavaScript

مثال Python

استجابة النجاح `201`

أنواع الاستجابة

2) التحقق من حالة الترجمة

نقطة النهاية

المصادقة

مثال cURL

مثال JavaScript

مثال Python

تنسيق الاستجابة

قيم الحالة

أنواع الاستجابة

3) تنزيل المستند المترجم

نقطة النهاية

مثال cURL

مثال JavaScript

مثال Python

أنواع الاستجابة

أفضل ممارسة