Claim and finish

Play tips from your own code - claim one, run your effect, finish it. The same protocol TipPage's overlay uses.

TipPage takes the payment, filters it and queues it. Your code plays it: a phone, a light rig, your own overlay. Our overlay uses this exact protocol, so you can replace it outright.

Call	Does	Refused with
`POST /v1/tts/{orderId}/start`	Claims the item as now playing. Fires `queue.tts.started`. No timeout	`409 queue_paused`, `409 already_playing` (+ `current_order_id`), `404 not_in_queue`
`POST /v1/tts/{orderId}/finish`	It played: moves it to history, frees the slot. Fires `queue.tts.finished`	Never. Works while paused or on an item that was never started; an item already gone returns `tip: null`
`POST /v1/tts/{orderId}/release`	It didn’t play: drops the claim, the item stays queued for anyone to claim again. Fires `queue.tts.released`	Never. Releasing something you don’t hold returns `released: false`; it can’t drop another item’s claim

Media works the same under /v1/media/{orderId}/..., except start skips the already-playing check (pacing videos is up to you).

Every change - yours, the overlay’s, the dashboard’s skip button - goes through one lock per streamer with one now-playing slot, so two consumers can never play the same item. A skip can name the item it means (order_id on skip); one that arrives after that item has finished is refused with 409 not_playing rather than cutting whatever plays next. Nothing about your consumer is registered: if it crashes mid-item, the item stays marked as playing until the streamer skips it or you recover it. No tip is ever lost.

loop:
  q = GET /v1/tts/queue
  if q.is_paused or q.playing or no items: wait, continue
  tip = q.items[0]
  POST /v1/tts/{tip.order_id}/start      -> 409/404: continue
  ... your effect (tts_url, or name/amount/message) ...
      a standard-voice tip has no tts_url until something asks for its audio:
      GET /v1/tts/{tip.order_id}/audio makes it, in the voice you ask for
  worked? POST .../finish   else POST .../release

Rules for a good consumer

Finish or release everything you claim, including on shutdown.
Recover on startup: if GET /v1/tts/now shows an item you don’t remember claiming, your last run crashed - release it, or replay and finish. A 409 already_playing whose current_order_id is the item you were claiming means your earlier claim went through; carry on.
Turn tips off on the alert box while your consumer runs, or the two of you alternate claiming them. It’s the Alert toggle on the Tip row of the Alert box widget in the overlay editor: off, the overlay never claims a tip and keeps showing follows, subs and the rest (turning off its TTS alone is not enough - the box would still claim and show every tip). TipPage sends a multiple_tts_consumers / multiple_media_consumers warning when it sees two consumers.
Treat 409 as normal: back off and check again, don’t retry in a loop.
Ask for the audio yourself. A standard-voice tip’s clip is only made when something comes to play it, so tts_url is null until you call tip audio: the main alert box’s voice by default, a particular overlay’s with overlay, or your own voice, rate and pitch. An AI-voice tip answers pending while its clip is still being made.
Hear about new tips from tip.created or by polling every few seconds - and claim when you’re ready to play, not when the event arrives.