Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

Audio for a tip

The clip for a queued tip, made on demand. A standard-voice tip’s audio is only made when something comes to play it, so a consumer that plays tips itself asks here before or after claiming; an AI-voice tip’s clip was made at payment and is handed straight back. The words come from the row’s current name, amount and message. The clip you are handed is written to the queue row as tts_url and fires tip.tts_ready (again if it replaces an earlier clip in another voice, such as a dashboard preview).

Say whose voice to read it in: overlay for that overlay’s alert box voice, or voice for a standard voice. Passing neither is deprecated: it reads in Brian for now and will become 400 voice_required. Other voice parameters given directly override the overlay’s. A tip that has already played can be asked for too: you get the clip that played, whatever voice you name (one that played with no audio is made now). No rate limit; up to 8 distinct voice variants per tip. The same parameters are accepted in a JSON body on POST. Requires tts:read.

GET/tts/{orderId}/audio
Authorization
AuthorizationBearer token (tp_live_... or tpat_...) · headerrequired

A TipPage API key (tp_live_..., created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (tpat_..., see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.

Path parameters
orderIdstringrequired

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

Query parameters
overlaystring

An overlay id (o_...). Read the tip the way that overlay's alert box is set to.

voicestring

A standard voice id from /tts/voices.

ratenumber
min 0.5 · max 2
pitchnumber
min 0.7 · max 1.5
readNamesboolean
readAmountsboolean
readMessagesboolean
maxLengthinteger

Cut the message at this many characters.

min 0 · max 1000
Responses
200

One of: the clip (url, with text for a standard tip or ai for an AI-voice tip), pending (an AI voice is still being made, ask again after retryMs), or silent (nothing of this tip is read with these settings).

One of:
object
urlstring<uri>
textstring

The words in the clip.

cachedboolean
providerstring | null
aiobject

Present for an AI-voice tip.

Show properties
voicedboolean | null

False when the AI generation failed and the clip is the standard voice.

turnsobject[] | null
object
pendingboolean
Allowed:true
retryMsinteger
messagestring
object
silentboolean
Allowed:true
400

A voice parameter is out of range or names no standard voice. Later also voice_required (neither overlay nor voice was given).

errorstringrequired

Human-readable message.

codestring

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

401

Missing or invalid credential (missing_api_key / invalid_api_key, or invalid_token for an expired/revoked OAuth access token).

errorstringrequired

Human-readable message.

codestring

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

403

The key lacks the required scope (missing_scope).

errorstringrequired

Human-readable message.

codestring

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

required_scopestring
404

tip_not_found (no tip of yours has that id) or overlay_not_found (no overlay of yours with an alert box has that id).

errorstringrequired

Human-readable message.

codestring

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

429

too_many_variants: the tip has been asked for in too many different voices.

errorstringrequired

Human-readable message.

codestring

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

503

Every synthesiser failed. text carries the words, for a voice of your own.

fallbackboolean
Allowed:true
textstring
errorstring
Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://api.tippage.com/v1/tts/string/audio' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "url": "http://example.com",
  "text": "string",
  "cached": true,
  "provider": "string",
  "ai": {
    "voiced": true,
    "turns": [
      {}
    ]
  }
}