SSEによるリアルタイム進捗
SSE (Server-Sent Events) を介して、ファイル翻訳ジョブ (/jobs) の進捗をリアルタイムで受け取ります。SSE が利用できない場合は、接続は 404 を返します。その代わりにジョブのステータスをポーリングしてください。
ブラウザーの EventSource はカスタムヘッダーを送信できないため、認証情報の伝達には2段階が必要です:
- サーバーはAPIキーをチケット(有効期限30秒、一度限り利用可能)と交換します。
- チケットを使用して SSE に接続します(これはブラウザ上で発生する可能性があります。チケットは長期間有効な認証情報ではありません)。
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript 例
Section titled “JavaScript 例”APIキーはサーバー側に保持します。サーバーがチケットを取得し、それをブラウザーに渡します。
// 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接続を保持でき、1分間に最大30枚のチケットを交換できます。それ以上の場合、レスポンスは
429となるため、Retry-Afterを待つか、代わりにポーリングしてください。 - 長時間ジョブイベントがない場合、サーバーは
timeoutイベントを送信し、新しいチケットを取得して再接続します。 - 接続がアイドル状態の間、サーバーはハートビートコメントを送信します。クライアントはコメント行を無視してください。
- 接続が切断された場合、ポーリング
GET /jobs/{id}がフォールバックとして機能します。