API переводчик

1. 01

   Создать API-ключ

   Войдите на belindoc.com, откройте меню аватара в правом верхнем углу, выберите «Центр разработчика» и создайте ключ. Ключи начинаются с ft_, полное значение показывается только один раз — сразу после создания.

2. 02

   Загрузить файл

   Сначала запросите предподписанную ссылку, затем отправьте файл на неё методом PUT. Ссылка живёт 10 минут; возвращённый objectKey понадобится на следующем шаге.

   bash

   Копировать

   # 1. Получить предподписанный URL для загрузки (действует 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. Загрузить файл прямо по этому URL методом 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 всегда приходит на языке из заголовка language. Ветвитесь по code, а не по msg.

Та же квота, без отдельной тарификации

Вызовы API списывают ту же квоту страниц и видео, что и веб-интерфейс, с теми же коэффициентами моделей. Отдельного тарифа для API нет.

Те же правила водяного знака

На бесплатном тарифе переведённые PDF содержат водяной знак — ровно как в браузере. Обращение через API его не убирает.

В счётчик идут только отправки

Счётчик вызовов ключа растёт только на batchSubmitTranslateTask, submitVideoTranslate и submitVideoRewrite. Запросы статуса и деталей можно опрашивать свободно.

Одна отправка за раз

Отправки сериализуются по аккаунту. Вторая отправка, пока принимается первая, вернёт код ошибки о повторной задаче — повторите чуть позже, а не параллельно.

OCR по умолчанию выключен

Ставьте isOcr только для сканов. OCR списывает отдельную подквоту сверх страничной, поэтому на текстовом PDF он расходует квоту дважды. Если не уверены, сначала вызовите эндпоинт isOcr.