SSE সহ রিয়েল-টাইম অগ্রগতি
SSE (Server-Sent Events) এর মাধ্যমে /jobs ফাইল অনুবাদ কাজগুলির অগ্রগতি রিয়েল-টাইমে পান। যখন 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}পোলিং একটি ব্যাকআপ হিসেবে কাজ করে।