Echtzeitfortschritt mit SSE
Empfangen Sie den Fortschritt von Dateiübersetzungsjobs (/jobs) in Echtzeit über SSE (Server-Sent Events). Wenn SSE nicht verfügbar ist, gibt die Verbindung 404 zurück; prüfen Sie stattdessen den Jobstatus.
Verbindungsfluss
Abschnitt betitelt „Verbindungsfluss“Der Browser EventSource kann keine benutzerdefinierten Header senden, daher erfolgen Anmeldeinformationen in zwei Schritten:
- Ihr Server tauscht den API-Schlüssel gegen ein Ticket ein (gültig für 30 Sekunden, einmalig nutzbar)
- Stellen Sie mit dem Ticket eine Verbindung zu SSE her (dies kann im Browser erfolgen; das Ticket ist kein langfristiges Anmelde-Token).
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript example
Abschnitt betitelt „JavaScript example“Behalten Sie den API-Schlüssel auf dem Server: Der Server erhält das Ticket und übergibt es an den Browser.
// 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();});Ereignistypen
Abschnitt betitelt „Ereignistypen“| Ereignis | Beschreibung |
|---|---|
job_update | Status oder Phase geändert (ein Snapshot des aktuellen Zustands wird unmittelbar nach der Verbindung gesendet) |
job_done | Der Job ist beendet (completed oder failed); Sie können die Verbindung schließen. |
timeout | Der Stream hat seine maximale Dauer erreicht; erneut verbinden |
error | Serverseitiges Problem; holen Sie sich ein neues Ticket und stellen Sie später die Verbindung wieder her. |
Ereignisdaten
Abschnitt betitelt „Ereignisdaten“Der stage_message des Servers ist auf Chinesisch:
event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}Wenn der Job abgeschlossen ist, rufen Sie die Ergebnisliste mit GET /api/v1/artifacts?job_id=... ab.
Python example
Abschnitt betitelt „Python example“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 insteadHinweise
Abschnitt betitelt „Hinweise“- Ein Ticket ist einmalig gültig; holen Sie sich ein neues, bevor Sie die Verbindung wiederherstellen.
- Jedes Konto kann gleichzeitig höchstens 6 SSE-Verbindungen offen halten und maximal 30 Tickets pro Minute austauschen; darüber hinaus lautet die Antwort
429, warten Sie also aufRetry-Afteroder verwenden Sie stattdessen Polling. - Wenn über einen längeren Zeitraum keine Job-Ereignisse auftreten, sendet der Server ein
timeout-Ereignis; holen Sie sich ein neues Ticket und stellen Sie die Verbindung wieder her. - Während die Verbindung im Leerlauf ist, sendet der Server Heartbeat-Kommentare; Clients sollten Kommentarzeilen ignorieren.
- Falls die Verbindung unterbrochen wird, dient das Polling
GET /jobs/{id}als Fallback.