Realtime: connecting and subscribing

Order statuses arrive over WebSocket using a Pusher-compatible protocol: pusher-js and Laravel Echo both work, and Lumean has no SDK of its own. Subscribing is free and doesn't consume the key's windows; only REST uses them.

Connection

The app key is public: it identifies the application, not you, and is published openly in the spec. The only secret here is X-API-KEY, and it goes only to the auth endpoint, never into WebSocket frames.

import Pusher from 'pusher-js'

const pusher = new Pusher('7c4dd881d8116ac76fe89aff71d8c2ff', {
  wsHost: 'ws.lumean.app', wsPort: 443, wssPort: 443,
  forceTLS: true, enabledTransports: ['ws', 'wss'], cluster: '',
  channelAuthorization: {
    endpoint: 'https://api.lumean.app/api/public/broadcasting/auth',
    headers: { 'X-API-KEY': process.env.LUMEAN_API_KEY },
  },
})

const ch = pusher.subscribe('private-orders.42')      // 42 = user_id of the key owner
ch.bind('status.changed', (e) => console.log(e.previous_status, '→', e.new_status))

Laravel Echo takes the same parameters (authEndpoint + auth.headers), but it adds the private- prefix itself: echo.private('orders.42').

Subscription authorization

A private channel requires a signature, and the library obtains it on its own: the socket_id from the pusher:connection_established frame is sent along with channel_name (with the private- prefix) to POST /broadcasting/auth with the X-API-KEY header, and the returned auth string goes into the pusher:subscribe frame. The required scope depends on the channel: orders.read for the order channels and the preview channel, voices.read for the voice clone channels, reseller.read for the codes channel. The response comes outside the standard API envelope: it has no success and no data, only auth.

Channels

Account channel (14): created, status.changed, item.status.changed, progress, bulk_retry.completed, paragraph_regenerate.completed, voice_search.queue.updated, renamed, stitch.changed, policy_cooldown.applied/.cleared, archive.progress/.ready/.failed. Order channel (8): the same, except created, archive.*, and policy_cooldown.*. Preview channel (1): ready (status, preview_id, summary, page). It contains no chunks; fetch them with GET /orders/chunks/preview/{previewId}?page=1. Clone channels (1 each): voice_clone.updated on every clone status change (pending → cloning → ready or failed); without WebSocket, poll the status through the clone list. Codes channel (4): issued, status.changed, reseller.status.changed, reseller.application.status.changed. Events carry no code values, only masks; the full code is returned by GET /reseller/codes and GET /reseller/codes/{uuid}.

Detect completion by status.changed (previous_status → new_status), not by progress counters: the last chunk and the terminal status are different moments.

Trap: two different progress events

The progress event exists on both order channels, but its payload is different, and you can tell them apart only by the channel: the name is the same, and a shared handler reads fields that don't exist.

Both progress events count only the original chunks: retries and regenerations are not included, so the percentage of a reworked order may never reach 100 at all.

Trap: the leading dot in the event name

What the payload doesn't contain

• created and status.changed carry an order snapshot without the chunk list; instead there is items_summary: { total, by_status }. Get the chunks from GET /orders/{order}.
• Files arrive as metadata: the download link always comes from POST /storage/url.
• renamed and archive.* can't be triggered with an API key; they exist only in the web dashboard. The event arrives if the owner did it manually.
• policy_cooldown.applied warns about a cooldown before you hit a 429: the restriction is applied when a failed task is finalized, not in response to a request. Go by retry_at (ISO-8601): the event travels through a queue, and retry_after goes stale in transit.

When you don't need WebSocket

For a single short order, polling GET /orders/{order} is cheaper: the connection and event parsing pay off with a stream of orders or where the user watches the progress. And even with a subscription, REST remains the source of truth, because an event may never arrive. Waiting without WS is covered in the Asynchronous order model guide.