इसे छोड़कर कंटेंट पर जाएं

SSE के साथ वास्तविक समय प्रगति

फ़ाइल अनुवाद कार्यों (/jobs) की प्रगति SSE (Server-Sent Events) के माध्यम से वास्तविक समय में प्राप्त करें। जब SSE उपलब्ध न हो, तो कनेक्शन 404 लौटाता है; इसके बजाय कार्य की स्थिति का पोल करें।

ब्राउज़र का EventSource कस्टम हेडर नहीं भेज सकता, इसलिए क्रेडेंशियल्स के लिए दो चरण आवश्यक हैं:

  1. आपका सर्वर API कुंजी को एक टिकट (30 सेकंड तक मान्य, एक बार उपयोग के लिए) से बदलता है।
  2. टिकट के साथ SSE से कनेक्ट करें (यह ब्राउज़र में हो सकता है; टिकट लंबे समय तक जीवित रहने वाली क्रेडेंशियल नहीं है)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}
GET /api/v1/sse/jobs/{job_id}?ticket=...

एपीआई कुंजी को सर्वर पर रखें: सर्वर टिकट प्राप्त करता है और उसे ब्राउज़र को सौंप देता है।

// 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();
});
घटनाविवरण
job_updateस्थिति या चरण बदल गया (कनेक्ट होते ही वर्तमान स्थिति का स्नैपशॉट भेज दिया जाता है)
job_doneकार्य समाप्त हो गया (completed या failed); आप कनेक्शन बंद कर सकते हैं
timeoutस्ट्रीम अपनी अधिकतम अवधि तक पहुँच गई; फिर से कनेक्ट करें
errorसर्वर-पक्षीय समस्या; नया टिकट प्राप्त करें और बाद में फिर से कनेक्ट करें

सर्वर का stage_message चीनी में है:

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":""}

जब कार्य पूर्ण हो जाता है, तो 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
  • एक टिकट एक बार ही काम करता है; फिर से कनेक्ट करने से पहले नया टिकट प्राप्त करें
  • प्रत्येक खाता एक समय में अधिकतम 6 SSE कनेक्शन खुले रख सकता है और प्रति मिनट अधिकतम 30 टिकटों का आदान-प्रदान कर सकता है; इससे अधिक होने पर प्रतिक्रिया 429 होती है, इसलिए Retry-After की प्रतीक्षा करें या इसके बजाय पोल करें।
  • जब लंबे समय तक कोई जॉब इवेंट्स नहीं होते, तो सर्वर timeout इवेंट भेजता है; नया टिकट प्राप्त करें और फिर से कनेक्ट करें।
  • जब कनेक्शन निष्क्रिय होता है, तो सर्वर हार्टबीट कमेंट भेजता है; क्लाइंटों को कमेंट पंक्तियों को अनदेखा करना चाहिए।
  • यदि कनेक्शन टूट जाता है, तो पोलिंग GET /jobs/{id} एक फ़ॉलबैक के रूप में काम करता है।