SSE 即時進度
透過 SSE(Server-Sent Events)即時接收檔案翻譯任務(/jobs)的進度。SSE 未開放時連線回傳 404,請改為輪詢任務狀態。
瀏覽器的 EventSource 不支援自訂 Header,因此採用兩步驟憑證方式:
- 您的伺服器端使用 API Key 權杖來換取票證(30 秒內有效,僅能使用一次)
- 使用 ticket 建立 SSE 連線(可在瀏覽器中進行,ticket 不是長期憑證)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript 範例
Section titled “JavaScript 範例”API Key 僅放置於服務端:由服務端換取 ticket,再將 ticket 交給瀏覽器。
// 服务端(Node.js 18+):换取 ticketasync function createSseTicket(jobId) { const response = await fetch( `https://omnidoc.top/api/v1/sse/ticket/${jobId}`, { method: 'POST', headers: { 'X-API-Key': process.env.OMNIDOC_API_KEY } } ); if (!response.ok) throw new Error(`ticket failed: ${response.status}`); return (await response.json()).ticket;}// 浏览器:用服务端给的 ticket 连接 SSEconst source = new EventSource( `https://omnidoc.top/api/v1/sse/jobs/${jobId}?ticket=${encodeURIComponent(ticket)}`);
// 事件是命名事件,用 addEventListener(onmessage 收不到)source.addEventListener('job_update', (event) => { const data = JSON.parse(event.data); console.log(`状态: ${data.status}, 阶段: ${data.stage}, 进度: ${data.stage_progress}%`);});
source.addEventListener('job_done', (event) => { const data = JSON.parse(event.data); console.log(`结束: ${data.status}`); source.close();});| 事件 | 說明 |
|---|---|
job_update | 狀態/階段變化(連線後先推一次當前快照) |
job_done | 任務結束(completed 或 failed),此後可關閉連線 |
timeout | 串流達到最長時限,需重新連線 |
error | 服務端異常,稍後重新取得票證連線 |
事件資料格式
Section titled “事件資料格式”event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}任務完成後,透過 GET /api/v1/artifacts?job_id=... 獲取產物清單。
Python 範例
Section titled “Python 範例”pip install requests sseclient-pyimport json
import requestsimport sseclient # sseclient-py
BASE = "https://omnidoc.top/api/v1"HEADERS = {"X-API-Key": "sk_your_key"}job_id = "q3f8s6c2a9m1k4tx"
ticket_response = requests.post( f"{BASE}/sse/ticket/{job_id}", headers=HEADERS, timeout=20)ticket_response.raise_for_status()ticket = ticket_response.json()["ticket"]
# 读超时大于 15 秒心跳间隔;连接期间不发送 API Keyresponse = requests.get( f"{BASE}/sse/jobs/{job_id}", params={"ticket": ticket}, stream=True, timeout=(10, 60),)response.raise_for_status()client = sseclient.SSEClient(response)
for event in client.events(): data = json.loads(event.data) print(f"[{event.event}] {data.get('stage')} {data.get('stage_progress', 0)}%") if event.event in {"job_done", "timeout", "error"}: break # timeout / error:重新换取 ticket 再连接,或改为轮询- ticket 一次有效,重新連線前需重新取得
- 每個帳號最多同時保持 6 條 SSE 連線,每分鐘最多兌換 30 個 ticket;超出回傳
429,請按Retry-After稍後再試或改為輪詢 - 當長時間沒有任務事件時,服務端會發送
timeout事件;需重新換取 ticket 並連線 - 連線閒置期間服務端會發送心跳註解,客戶端應忽略該註解行
- 如果連線中斷,可用輪詢
GET /jobs/{id}作為兜底