Tiến trình thời gian thực với SSE
Nhận thông tin tiến trình của các công việc dịch tệp (/jobs) theo thời gian thực qua SSE (Server-Sent Events). Khi SSE không khả dụng, kết nối sẽ trả về 404; thay vào đó, hãy kiểm tra trạng thái công việc.
Luồng kết nối
Phần tiêu đề “Luồng kết nối”Trình duyệt EventSource không thể gửi tiêu đề tùy chỉnh, vì vậy thông tin xác thực phải trải qua hai bước:
- Máy chủ của bạn trao đổi khóa API để nhận một vé (có hiệu lực trong 30 giây, sử dụng được một lần)
- Kết nối với SSE bằng vé (điều này có thể xảy ra trong trình duyệt; vé không phải là thông tin xác thực tồn tại lâu dài)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript example
Phần tiêu đề “JavaScript example”Giữ khóa API trên máy chủ: máy chủ lấy ticket và chuyển nó cho trình duyệt.
// Server (Node.js 18+): exchange the key for a 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;}// Browser: connect to SSE with the ticket from your serverconst source = new EventSource( `https://omnidoc.top/api/v1/sse/jobs/${jobId}?ticket=${encodeURIComponent(ticket)}`);
// The events are named, so use addEventListener (onmessage does not receive them)source.addEventListener('job_update', (event) => { const data = JSON.parse(event.data); console.log(`status: ${data.status}, stage: ${data.stage}, progress: ${data.stage_progress}%`);});
source.addEventListener('job_done', (event) => { const data = JSON.parse(event.data); console.log(`finished: ${data.status}`); source.close();});Các loại sự kiện
Phần tiêu đề “Các loại sự kiện”| Sự kiện | Mô tả |
|---|---|
job_update | Trạng thái hoặc giai đoạn đã thay đổi (một ảnh chụp nhanh về trạng thái hiện tại được gửi ngay sau khi kết nối) |
job_done | Công việc đã kết thúc (completed hoặc failed); bạn có thể đóng kết nối |
timeout | Luồng đã đạt đến thời lượng tối đa; hãy kết nối lại |
error | Lỗi phía máy chủ; hãy lấy một vé mới và kết nối lại sau |
Dữ liệu sự kiện
Phần tiêu đề “Dữ liệu sự kiện”stage_message của máy chủ đang ở dạng tiếng Trung:
event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}Khi công việc hoàn tất, hãy lấy danh sách kết quả bằng GET /api/v1/artifacts?job_id=....
Ví dụ Python
Phần tiêu đề “Ví dụ 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"]
# Read timeout longer than the 15-second heartbeat; no API key while connectedresponse = 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: get a new ticket and reconnect, or poll insteadGhi chú
Phần tiêu đề “Ghi chú”- Một vé chỉ dùng được một lần; hãy lấy vé mới trước khi kết nối lại
- Mỗi tài khoản chỉ có thể duy trì tối đa 6 kết nối SSE đồng thời và trao đổi tối đa 30 vé mỗi phút; nếu vượt quá giới hạn này, phản hồi sẽ là
429, vì vậy hãy đợiRetry-Afterhoặc sử dụng phương pháp polling thay thế. - Khi không có sự kiện công việc nào trong một thời gian dài, máy chủ sẽ gửi sự kiện
timeout; hãy lấy vé mới và kết nối lại. - Khi kết nối ở trạng thái rảnh rỗi, máy chủ gửi các nhận xét heartbeat; khách hàng nên bỏ qua các dòng nhận xét này.
- Nếu kết nối bị mất, việc polling
GET /jobs/{id}sẽ được sử dụng như một phương án dự phòng.