Übersetzung API

1. 01

   API-Key anlegen

   Auf belindoc.com anmelden, oben rechts das Avatar-Menü öffnen, Entwicklerbereich wählen und einen Key anlegen. Keys beginnen mit ft_; der vollständige Wert wird nur ein einziges Mal direkt nach dem Anlegen angezeigt.

2. 02

   Datei hochladen

   Erst eine vorsignierte URL anfordern, dann die Datei per PUT direkt dorthin schicken. Die URL gilt 10 Minuten; den zurückgegebenen objectKey brauchen Sie im nächsten Schritt.

   bash

   Kopieren

   # 1. Vorsignierte Upload-URL anfordern (10 Minuten gültig)
   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. Datei per PUT direkt an diese URL hochladen
   curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

3. 03

   Übersetzung einreichen

   fileList, sourceLanguage, targetLanguage und model sind Pflicht. AnyLanguage erkennt die Ausgangssprache automatisch; Modellnamen nicht fest verdrahten, sondern aus getModelList lesen.

   bash

   Kopieren

   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

   Status abfragen, dann herunterladen

   Über batchNo abfragen, bis status den Wert 3 hat, anschließend die Download-URL anfordern. Dieser Endpunkt antwortet als SSE-Stream — der Link steckt im Ereignis [DONE].

   bash

   Kopieren

   # Aufgabe abfragen: status = 3 bedeutet, die Übersetzung ist fertig
   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>"}'
   
   # Download-URL abrufen: SSE-Antwort, der Link kommt im [DONE]-Event
   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
  }
}

Fehler der Übersetzung selbst — zu wenig Kontingent, nicht unterstützte Datei, doppelte Einreichung — haben eigene Codes und liefern immer ein übersetztes msg. Verzweigen Sie über code, nie über msg.

Gleiches Kontingent, keine getrennte Abrechnung

API-Aufrufe verbrauchen dasselbe Seiten- und Videokontingent wie das Web-Frontend, mit denselben Modellfaktoren. Einen eigenen API-Preis gibt es nicht.

Gleiche Wasserzeichen-Regeln

Im kostenlosen Kontingent tragen übersetzte PDFs ein Wasserzeichen, genau wie im Browser. Über die API verschwindet es nicht.

Nur Einreichungen zählen als Aufrufe

Der Aufrufzähler eines Keys steigt nur bei batchSubmitTranslateTask, submitVideoTranslate und submitVideoRewrite. Status- und Detailabfragen dürfen frei gepollt werden.

Eine Einreichung zur Zeit

Einreichungen werden pro Konto serialisiert. Wird eingereicht, während die vorherige noch angenommen wird, kommt ein Fehlercode für doppelte Aufgaben zurück — kurz warten und erneut senden statt parallel feuern.

OCR ist standardmäßig aus

isOcr nur für Scans setzen. OCR zieht zusätzlich zum Seitenkontingent ein eigenes OCR-Unterkontingent ab; bei Text-PDFs verbraucht es damit doppelt. Im Zweifel vorher den Endpunkt isOcr aufrufen.