API de traduction

1. 01

   Créer une clé API

   Connectez-vous à belindoc.com, ouvrez le menu de votre avatar en haut à droite, allez dans Espace développeur et créez une clé. Les clés commencent par ft_ et la valeur complète n'apparaît qu'une seule fois, juste après la création.

2. 02

   Envoyer le fichier

   Demandez une URL présignée, puis envoyez le fichier directement dessus en PUT. L'URL reste valable 10 minutes ; conservez l'objectKey renvoyé pour l'étape suivante.

   bash

   Copier

   # 1. Obtenir une URL d'upload présignée (valable 10 minutes)
   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. Envoyer le fichier directement sur cette URL avec PUT
   curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

3. 03

   Soumettre la traduction

   fileList, sourceLanguage, targetLanguage et model sont obligatoires. Passez AnyLanguage pour détecter la langue source automatiquement, et lisez la liste des modèles via getModelList plutôt que de la coder en dur.

   bash

   Copier

   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

   Interroger, puis télécharger

   Interrogez le batchNo jusqu'à ce que status vaille 3, puis demandez l'URL de téléchargement. Ce point d'entrée répond en flux SSE : le lien arrive dans l'événement [DONE].

   bash

   Copier

   # Interroger la tâche — status = 3 signifie que la traduction est prête
   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>"}'
   
   # Récupérer l'URL de téléchargement — réponse SSE, le lien arrive dans l'événement [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
  }
}

Les erreurs propres à la traduction — quota insuffisant, fichier non pris en charge, soumission en double — ont leurs propres codes et arrivent toujours avec un msg localisé. Branchez sur code, jamais sur msg.

Même quota, pas de facturation à part

Les appels API consomment le même quota de pages et de vidéo que le site, avec les mêmes coefficients par modèle. Il n'existe pas de tarif propre à l'API.

Mêmes règles de filigrane

En offre gratuite, les PDF traduits portent un filigrane, exactement comme dans le navigateur. Passer par l'API ne le retire pas.

Seules les soumissions comptent comme appels

Le compteur d'appels d'une clé n'avance que sur batchSubmitTranslateTask, submitVideoTranslate et submitVideoRewrite. Les lectures de statut et de détail peuvent être interrogées librement.

Une soumission à la fois

Les soumissions sont sérialisées par compte. Une seconde soumission pendant que la première est encore acceptée renvoie une erreur de tâche en double : réessayez un instant plus tard plutôt qu'en parallèle.

L'OCR est désactivé par défaut

N'activez isOcr que pour les documents scannés. L'OCR consomme un sous-quota dédié en plus du quota de pages : le laisser actif sur un PDF texte revient à payer deux fois. En cas de doute, appelez d'abord le point de terminaison isOcr.