Progreso en tiempo real con SSE
Reciba el progreso de los trabajos de traducción de archivos (/jobs) en tiempo real a través de SSE (Server-Sent Events). Cuando SSE no esté disponible, la conexión devuelve 404; consulte el estado del trabajo en su lugar.
Flujo de conexión
Sección titulada «Flujo de conexión»El EventSource del navegador no puede enviar encabezados personalizados, por lo que las credenciales requieren dos pasos:
- Su servidor intercambia la clave API por un ticket (válido durante 30 segundos, utilizable una sola vez)
- Conéctese a SSE con el ticket (esto puede ocurrir en el navegador; el ticket no es una credencial de larga duración)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript example
Sección titulada «JavaScript example»Mantenga la clave API en el servidor: el servidor obtiene el ticket y se lo entrega al navegador.
// 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();});Tipos de eventos
Sección titulada «Tipos de eventos»| Evento | Descripción |
|---|---|
job_update | Estado o etapa cambiado (se envía una instantánea del estado actual justo después de la conexión) |
job_done | El trabajo finalizó (completed o failed); puede cerrar la conexión |
timeout | La transmisión alcanzó su duración máxima; reconectar |
error | Problema del servidor; obtenga un nuevo ticket y vuelva a conectarse más tarde |
Datos del evento
Sección titulada «Datos del evento»El stage_message del servidor está en chino:
event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}Cuando finalice el trabajo, obtenga la lista de resultados con GET /api/v1/artifacts?job_id=....
Python example
Sección titulada «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 instead- Un ticket funciona una sola vez; obtenga uno nuevo antes de volver a conectarse.
- Cada cuenta puede mantener abiertas como máximo 6 conexiones SSE a la vez e intercambiar como máximo 30 tickets por minuto; de lo contrario, la respuesta es
429, así que espereRetry-Aftero realice una consulta en su lugar. - Cuando no hay eventos de trabajo durante un largo período, el servidor envía un evento
timeout; obtenga un nuevo ticket y vuelva a conectarse. - Mientras la conexión está inactiva, el servidor envía comentarios de latido; los clientes deben ignorar las líneas de comentario.
- Si se interrumpe la conexión, el sondeo
GET /jobs/{id}funciona como solución alternativa.