跳到內容

將文件工作流程接入您的應用程式

從上傳一份文件,到翻譯、查詢進度和下載結果。這裡按接入順序說明每一步,也提供檔案管理、文件處理與音視訊服務的介面入口。

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API 密鑰認證 · 文件翻譯採用非同步任務

這裡介紹雲端 HTTP API。

請先確認密鑰和網路正常,再開始上傳檔案。餘額查詢不會扣除積分,也不會建立翻譯任務。

  1. 準備 API Key

    登入 API 控制台 ,建立以 sk_ 開頭的金鑰。建議每個應用程式使用一個獨立的金鑰,並為其設定預算。

    Key 代表建立它的帳號。僅在伺服器端儲存,透過環境變數讀取,切勿寫入網頁原始碼或公開倉庫。

  2. 查詢餘額

    設定環境變數 OMNIDOC_API_KEY,然後執行下列任一範例。成功時返回 JSON;返回 401 表示金鑰有問題,請檢查。請勿在工單、截圖或日誌中顯示完整金鑰。

    Terminal window
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

上傳成功僅表示檔案已入库。建立任務後需等待其進入終態,再查詢並下載產物。

步驟方法與路徑保留的結果
申請上傳POST /upload/presignupload_url、upload_headers、finalize_token
傳輸原始檔案PUT 返回的 upload_url成功回應;此請求不帶 API Key
確認上傳POST /upload/finalizedocument.id
建立翻譯POST /jobs任務 id
查詢狀態GET /jobs/{job_id}completed 或 failed
列出產物GET /artifacts?job_id={job_id}產物 ID 與格式
下載結果GET /artifacts/{artifact_id}/download檔案位元組與回應檔名

直傳時,原樣使用服務端返回的 upload_headers,不要把 X-API-Key 發給儲存位址。上傳位址過期或傳輸失敗時,重新申請一個。完整說明見 上傳協議 、 快速開始 、 Node.js 完整工作流程 和 翻譯請求欄位 。

每個入口都寫了具體路徑、請求欄位和範例。帳號的開放狀態與 Key 的限制同樣適用。

API Key 代表一個帳號的身份,並非某個檔案的公開下載口令。

請求標頭

統一使用 X-API-Key: sk_…,或 Authorization: Bearer sk_…,每個請求選一種即可。發送 JSON 時設定 Content-Type: application/json。

帳戶與 Key 的邊界

只能存取當前帳號有權使用的資源;服務開放狀態、Key 預算和允許的翻譯配置仍然生效。帳號資訊變更,以及 Key 的建立、輪換、撤銷,都在控制台完成。

詳見 認證、預算與輪換 和 服務權限與記錄範圍 。

超時並不等於任務尚未建立。必須區分可重試的錯誤與需修正的請求,以避免重複提交及重複處理。

  • 冪等創建 :每次新的創建操作會生成一個 Idempotency-Key;重試同一操作時,沿用原來的鍵和完全相同的請求體。文檔操作、音視頻任務和音色創建要求帶冪等鍵,其他創建接口以對應參考頁為準。
  • ** 異步通知 ** :初次接入可以輪詢任務;要持續追蹤進度用 SSE ,要在後台接收終態用 Webhook 。
狀態先檢查處理方式
401 / 403密鑰、權限、資源歸屬修正憑證或權限,不要盲目重試
402可用積分補足積分後重新提交
409冪等鍵與請求體、資源狀態先查詢原操作,再決定是否發起新操作
422回應中的欄位錯誤修正參數或檔案內容
429業務 code 與 Retry-After頻率或佇列限制可以等待;Key 預算用完要先調整預算
5xx服務暫時性錯誤有上限的指數退避;建立請求保留冪等鍵

保存響應標頭 X-Request-Id、請求時間和路徑,方便排查;請勿記錄完整密鑰。所有錯誤碼與重試範例請參閱 錯誤碼參考 。

不扣積分

上傳、查詢任務、下載結果、查詢餘額與憑證不扣積分;術語表、項目、標籤、搜尋和分享也不扣積分。

產生處理用量

文件翻譯、文檔工具、即時翻譯和音視訊服務按對應價格和實際用量結算,建立任務並不等於最終扣款。

開始前只檢查餘額是否夠門檻,任務結束後按實際用量扣費;餘額不足的部分記為欠款,之後到账的積分先抵扣。可以按任務或積分操作記錄核對實扣與退款。Key 預算用完後,仍然可以查詢它名下的任務、產物和憑證。