Suivi en temps réel avec SSE
Recevez en temps réel l’avancement des tâches de traduction de fichiers (/jobs) via SSE (Server-Sent Events). Lorsque SSE n’est pas disponible, la connexion renvoie 404 ; consultez alors l’état de la tâche par interrogation.
Flux de connexion
Section intitulée « Flux de connexion »Le EventSource du navigateur ne peut pas envoyer d’en-têtes personnalisés, de sorte que les informations d’authentification nécessitent deux étapes :
- Votre serveur échange la clé API contre un ticket (valable 30 secondes, utilisable une seule fois)
- Connectez-vous à SSE avec le ticket (cela peut se faire dans le navigateur ; le ticket n’est pas un jeton persistant).
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript example
Section intitulée « JavaScript example »Conservez la clé API sur le serveur : le serveur obtient le ticket et le transmet au navigateur.
// 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();});Types d’événements
Section intitulée « Types d’événements »| Événement | Description |
|---|---|
job_update | État ou étape modifié (un instantané de l’état actuel est envoyé immédiatement après la connexion) |
job_done | La tâche s’est terminée (completed ou failed) ; vous pouvez fermer la connexion. |
timeout | Le flux a atteint sa durée maximale ; reconnecter |
error | Problème côté serveur ; obtenez un nouveau ticket et reconnectez-vous ultérieurement |
Données d’événement
Section intitulée « Données d’événement »Le stage_message du serveur est en chinois :
event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}Lorsque le travail est terminé, récupérez la liste des résultats avec GET /api/v1/artifacts?job_id=....
Python example
Section intitulée « 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 insteadRemarques
Section intitulée « Remarques »- Un ticket est valable une seule fois ; obtenez-en un nouveau avant de vous reconnecter.
- Chaque compte peut maintenir au maximum 6 connexions SSE ouvertes simultanément et échanger au plus 30 tickets par minute ; au-delà, la réponse est
429, attendez doncRetry-Afterou utilisez une requête itérative à la place. - Lorsqu’il n’y a pas d’événements de tâche pendant une longue période, le serveur envoie un événement
timeout; obtenez un nouveau ticket et reconnectez-vous. - Pendant que la connexion est inactive, le serveur envoie des commentaires de cœur de réseau ; les clients doivent ignorer les lignes de commentaire.
- En cas de perte de connexion, le polling
GET /jobs/{id}sert de solution de secours.