Bỏ qua để đến nội dung

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.

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:

  1. 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)
  2. 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=...

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 ticket
async 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 server
const 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();
});
Sự kiệnMô tả
job_updateTrạ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_doneCông việc đã kết thúc (completed hoặc failed); bạn có thể đóng kết nối
timeoutLuồng đã đạt đến thời lượng tối đa; hãy kết nối lại
errorLỗi phía máy chủ; hãy lấy một vé mới và kết nối lại sau

stage_message của máy chủ đang ở dạng tiếng Trung:

event: job_update
data: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_done
data: {"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=....

Terminal window
pip install requests sseclient-py
import json
import requests
import 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 connected
response = 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 instead
  • 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 đợi Retry-After hoặ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.