Claim a TTS as now playing

Marks a queued TTS as currently playing - the same call the overlay makes. Fires queue.tts.started. While claimed, other consumers get 409 already_playing. If your effect then fails and the tip should not count as played, undo the claim with release instead of finishing. See the claim, do your thing, finish guide for the full pattern. Requires tts:control.

POST/tts/{orderId}/start

Authorization

AuthorizationBearer token (tp_live_...) · headerrequired

A TipPage API key, created in Dashboard → Settings → Developer.

Path parameters

orderIdstringrequired

The tip's order id (e.g. `tip_1755100000000_ab12cd`) - the only external row reference.

Responses

200Claimed.

successboolean

tipQueueTip

A tip in the pending TTS queue.

Show properties

order_idstring

namestring

Display name (post-filter).

amountnumber | null

messagestring | null

The tip message (post-filter - what shows on stream).

tts_urlstring<uri> | null

Pre-rendered audio; `null` until rendering completes.

is_replayboolean

is_sub_rewardboolean

twitch_user_idstring | null

Present when the donor tipped signed in with Twitch.

name_was_filteredboolean

message_was_filteredboolean

queued_atstring<date-time>

401Missing or invalid API key (`missing_api_key` / `invalid_api_key`).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

403The key lacks the required scope (`missing_scope`).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

required_scopestring

404No such resource.

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

409`queue_paused` (the queue is paused) or `already_playing` (another tip holds the slot; `current_order_id` names it).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

current_order_idstring

429Rate limit exceeded - check the `RateLimit-*` headers.

errorstring

Request

curl -X POST "https://api.tippage.com/v1/tts/string/start" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.tippage.com/v1/tts/string/start", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "https://api.tippage.com/v1/tts/string/start",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "success": true,
  "tip": {
    "order_id": "tip_1755100000000_ab12cd",
    "name": "string",
    "amount": 5,
    "message": "string",
    "tts_url": "http://example.com",
    "is_replay": true,
    "is_sub_reward": true,
    "twitch_user_id": "string",
    "name_was_filtered": true,
    "message_was_filtered": true,
    "queued_at": "2019-08-24T14:15:22Z"
  }
}