請求標頭
統一使用 X-API-Key: sk_…,或 Authorization: Bearer sk_…,每個請求選一種即可。發送 JSON 時設定 Content-Type: application/json。
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API 密鑰認證 · 文件翻譯採用非同步任務
這裡介紹雲端 HTTP API。
請先確認密鑰和網路正常,再開始上傳檔案。餘額查詢不會扣除積分,也不會建立翻譯任務。
準備 API Key
登入 API 控制台 ,建立以 sk_ 開頭的金鑰。建議每個應用程式使用一個獨立的金鑰,並為其設定預算。
Key 代表建立它的帳號。僅在伺服器端儲存,透過環境變數讀取,切勿寫入網頁原始碼或公開倉庫。
查詢餘額
設定環境變數 OMNIDOC_API_KEY,然後執行下列任一範例。成功時返回 JSON;返回 401 表示金鑰有問題,請檢查。請勿在工單、截圖或日誌中顯示完整金鑰。
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+,保存为 balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('请设置 OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());上傳成功僅表示檔案已入库。建立任務後需等待其進入終態,再查詢並下載產物。
| 步驟 | 方法與路徑 | 保留的結果 |
|---|---|---|
| 申請上傳 | POST /upload/presign | upload_url、upload_headers、finalize_token |
| 傳輸原始檔案 | PUT 返回的 upload_url | 成功回應;此請求不帶 API Key |
| 確認上傳 | POST /upload/finalize | document.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;重試同一操作時,沿用原來的鍵和完全相同的請求體。文檔操作、音視頻任務和音色創建要求帶冪等鍵,其他創建接口以對應參考頁為準。| 狀態 | 先檢查 | 處理方式 |
|---|---|---|
401 / 403 | 密鑰、權限、資源歸屬 | 修正憑證或權限,不要盲目重試 |
402 | 可用積分 | 補足積分後重新提交 |
409 | 冪等鍵與請求體、資源狀態 | 先查詢原操作,再決定是否發起新操作 |
422 | 回應中的欄位錯誤 | 修正參數或檔案內容 |
429 | 業務 code 與 Retry-After | 頻率或佇列限制可以等待;Key 預算用完要先調整預算 |
5xx | 服務暫時性錯誤 | 有上限的指數退避;建立請求保留冪等鍵 |
保存響應標頭 X-Request-Id、請求時間和路徑,方便排查;請勿記錄完整密鑰。所有錯誤碼與重試範例請參閱 錯誤碼參考 。
不扣積分
上傳、查詢任務、下載結果、查詢餘額與憑證不扣積分;術語表、項目、標籤、搜尋和分享也不扣積分。
產生處理用量
文件翻譯、文檔工具、即時翻譯和音視訊服務按對應價格和實際用量結算,建立任務並不等於最終扣款。
開始前只檢查餘額是否夠門檻,任務結束後按實際用量扣費;餘額不足的部分記為欠款,之後到账的積分先抵扣。可以按任務或積分操作記錄核對實扣與退款。Key 預算用完後,仍然可以查詢它名下的任務、產物和憑證。