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

1. 01

   أنشئ مفتاح API

   سجّل الدخول إلى belindoc.com، وافتح قائمة الصورة الرمزية أعلى اليمين، ثم اختر «مركز المطورين» وأنشئ مفتاحًا. تبدأ المفاتيح بالبادئة ft_ ولا تظهر قيمتها الكاملة إلا مرة واحدة بعد الإنشاء مباشرة.

2. 02

   ارفع الملف

   اطلب رابطًا موقّعًا مسبقًا ثم ارفع الملف إليه مباشرة بطريقة PUT. الرابط صالح لعشر دقائق، واحتفظ بقيمة objectKey العائدة للخطوة التالية.

   bash

   نسخ

   # 1. احصل على رابط رفع موقَّع مسبقًا (صالح 10 دقائق)
   curl -X POST https://belindoc.com/api/external/translate/batchPresignedUploadUrl \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"fileNameList": ["contract.pdf"]}'
   
   # → data[0].persignedUploadUrl / data[0].objectKey
   
   # 2. ارفع الملف مباشرة إلى هذا الرابط باستخدام PUT
   curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

3. 03

   أرسل مهمة الترجمة

   الحقول fileList وsourceLanguage وtargetLanguage وmodel إلزامية. مرّر AnyLanguage لاكتشاف لغة المصدر تلقائيًا، واقرأ قائمة النماذج من getModelList بدل كتابتها في الشيفرة.

   bash

   نسخ

   curl -X POST https://belindoc.com/api/external/translate/batchSubmitTranslateTask \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "fileList": [{ "fileName": "contract.pdf", "fileObjectKey": "<objectKey>" }],
       "sourceLanguage": "AnyLanguage",
       "targetLanguage": "zh-CN",
       "model": "Gemini-2.5-Flash"
     }'
   
   # → { "code": "200", "data": { "batchNo": "...", "fileList": [ ... ] } }

4. 04

   تابع الحالة ثم نزّل

   تابع باستخدام batchNo حتى تصبح قيمة status هي 3، ثم اطلب رابط التنزيل. تستجيب هذه النقطة ببث SSE، ويصل الرابط ضمن حدث [DONE].

   bash

   نسخ

   # استعلم عن المهمة: القيمة status = 3 تعني أن الترجمة جاهزة
   curl -X POST https://belindoc.com/api/external/translate/searchTranslateFileByBatchNo \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"batchNo": "<batchNo>"}'
   
   # احصل على رابط تنزيل الترجمة: استجابة SSE، والرابط يصل في حدث [DONE]
   curl -N -X POST https://belindoc.com/api/external/translate/getTranslateS3DownloadUrl \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"translateOrderNo": "<translateOrderNo>", "urlType": 2}'
   
   # event:[DONE]
   # data:{"url":"https://..."}

POST /api/external/translate/getModelList HTTP/1.1
Host: belindoc.com
Content-Type: application/json
X-Api-Key: ft_xxxxxxxxxxxxxxxxxxxxxxxx
language: zh

{}

{
  "code": "200",
  "msg": null,
  "requestId": "8f1c…",
  "data": { }
}

{
  "fileNameList": ["contract.pdf"]
}

{
  "code": "200",
  "data": [
    {
      "persignedUploadUrl": "https://s3.../contract.pdf?X-Amz-Signature=…",
      "objectKey": "translate/10086/2026/contract.pdf",
      "fileName": "contract.pdf",
      "storageType": 1
    }
  ]
}

{
  "fileObjectKey": "translate/10086/2026/contract.pdf",
  "storageType": 1
}

{
  "code": "200",
  "data": { "isOcr": 1, "isDoubleDeck": 0 }
}

{
  "fileList": [
    { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
  ],
  "sourceLanguage": "AnyLanguage",
  "targetLanguage": "zh-CN",
  "model": "Gemini-2.5-Flash",
  "isOcr": 0,
  "terminologyCollectionId": "66f1c2a4b8d3e5f7a9c1b2d3"
}

{
  "code": "200",
  "data": {
    "batchNo": "B20260828173001",
    "fileList": [
      { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
    ],
    "balanceHint": 0
  }
}

{
  "batchNo": "B20260828173001"
}

{
  "code": "200",
  "data": [
    {
      "translateOrderNo": "T20260828173002",
      "batchNo": "B20260828173001",
      "sourceFileName": "contract.pdf",
      "status": 3,
      "textNumber": 4820,
      "targetFileUrl": "https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"
    }
  ]
}

{
  "translateOrderNo": "T20260828173002",
  "urlType": 2,
  "isWatermark": 0
}

event:[PROCESS]
data:

event:[DONE]
data:{"translateOrderNo":"T20260828173002","url":"https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"}

{
  "code": "200",
  "data": {
    "en": {
      "AnyLanguage": "Any language",
      "zh-CN": "Simplified Chinese",
      "…": "…"
    },
    "zh": {
      "AnyLanguage": "任意语言",
      "zh-CN": "简体中文",
      "…": "…"
    },
    "…": {}
  }
}

{
  "sourceLanguage": "ja",
  "targetLanguage": "zh-CN",
  "sourceFileObjectKey": "video/10086/2026/lecture.mp4",
  "videoFileName": "lecture.mp4",
  "videoTaskParam": { "voiceRole": "clone", "subtitleType": 1 }
}

{}

{
  "code": "200",
  "data": {
    "userId": 10086,
    "translateQuota": 12000,
    "advancedTranslateQuota": 0,
    "ocrTranslateQuota": 800,
    "totalFreeTranslateQuota": 500,
    "useFreeTranslateQuota": 132
  }
}

أخطاء الترجمة نفسها — نفاد الحصة، أو ملف غير مدعوم، أو إرسال مكرر — لها رموزها الخاصة ويأتي معها دائمًا نص msg بلغتك. اعتمد في التفريع على code لا على msg.

الحصة نفسها بلا فوترة منفصلة

تستهلك استدعاءات الواجهة حصة الصفحات والفيديو نفسها المستخدمة في الموقع وبمعاملات النماذج نفسها، ولا يوجد سعر خاص بالواجهة.

قواعد العلامة المائية نفسها

في الباقة المجانية تحمل ملفات PDF المترجمة علامة مائية تمامًا كما في المتصفح، والمرور عبر الواجهة لا يزيلها.

الإرسال وحده يُحتسب استدعاءً

لا يتحرك عدّاد استدعاءات المفتاح إلا مع batchSubmitTranslateTask وsubmitVideoTranslate وsubmitVideoRewrite، أما استعلامات الحالة والتفاصيل فيمكن تكرارها بحرية.

إرسال واحد في كل مرة

يُنفَّذ الإرسال بالتتابع لكل حساب. إرسال ثانٍ أثناء قبول الأول يعيد رمز خطأ المهمة المكررة، فأعد المحاولة بعد لحظات بدل الإرسال المتوازي.

التعرّف الضوئي مغلق افتراضيًا

فعّل isOcr للمستندات الممسوحة ضوئيًا فقط. فالتعرّف الضوئي يخصم حصة فرعية إضافية فوق حصة الصفحات، وتركه مفعّلًا مع ملفات PDF النصية يستهلك الحصة مرتين. وعند الشك استدعِ نقطة isOcr أولًا.