SSE के साथ वास्तविक समय प्रगति
फ़ाइल अनुवाद कार्यों (/jobs) की प्रगति SSE (Server-Sent Events) के माध्यम से वास्तविक समय में प्राप्त करें। जब SSE उपलब्ध न हो, तो कनेक्शन 404 लौटाता है; इसके बजाय कार्य की स्थिति का पोल करें।
कनेक्शन प्रवाह
Section titled “कनेक्शन प्रवाह”ब्राउज़र का EventSource कस्टम हेडर नहीं भेज सकता, इसलिए क्रेडेंशियल्स के लिए दो चरण आवश्यक हैं:
- आपका सर्वर API कुंजी को एक टिकट (30 सेकंड तक मान्य, एक बार उपयोग के लिए) से बदलता है।
- टिकट के साथ SSE से कनेक्ट करें (यह ब्राउज़र में हो सकता है; टिकट लंबे समय तक जीवित रहने वाली क्रेडेंशियल नहीं है)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript उदाहरण
Section titled “JavaScript उदाहरण”एपीआई कुंजी को सर्वर पर रखें: सर्वर टिकट प्राप्त करता है और उसे ब्राउज़र को सौंप देता है।
// 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();});घटना प्रकार
Section titled “घटना प्रकार”| घटना | विवरण |
|---|---|
job_update | स्थिति या चरण बदल गया (कनेक्ट होते ही वर्तमान स्थिति का स्नैपशॉट भेज दिया जाता है) |
job_done | कार्य समाप्त हो गया (completed या failed); आप कनेक्शन बंद कर सकते हैं |
timeout | स्ट्रीम अपनी अधिकतम अवधि तक पहुँच गई; फिर से कनेक्ट करें |
error | सर्वर-पक्षीय समस्या; नया टिकट प्राप्त करें और बाद में फिर से कनेक्ट करें |
घटना डेटा
Section titled “घटना डेटा”सर्वर का stage_message चीनी में है:
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"]
# 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 instead- एक टिकट एक बार ही काम करता है; फिर से कनेक्ट करने से पहले नया टिकट प्राप्त करें
- प्रत्येक खाता एक समय में अधिकतम 6 SSE कनेक्शन खुले रख सकता है और प्रति मिनट अधिकतम 30 टिकटों का आदान-प्रदान कर सकता है; इससे अधिक होने पर प्रतिक्रिया
429होती है, इसलिएRetry-Afterकी प्रतीक्षा करें या इसके बजाय पोल करें। - जब लंबे समय तक कोई जॉब इवेंट्स नहीं होते, तो सर्वर
timeoutइवेंट भेजता है; नया टिकट प्राप्त करें और फिर से कनेक्ट करें। - जब कनेक्शन निष्क्रिय होता है, तो सर्वर हार्टबीट कमेंट भेजता है; क्लाइंटों को कमेंट पंक्तियों को अनदेखा करना चाहिए।
- यदि कनेक्शन टूट जाता है, तो पोलिंग
GET /jobs/{id}एक फ़ॉलबैक के रूप में काम करता है।