Text-to-speech API

Use these actions to manage AI text-to-speech (TTS): the settings, the voices on your channel, auto read, TTS moderation, the queue and voice clones.

Each action is a REST endpoint under https://kickbot.com/api/v1 and an MCP tool with the same name. The MCP area name is tts. Use it to load only this area: https://kickbot.com/api/v1/mcp?areas=tts.

A team member needs the TTS permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See Permissions and security.

How the feature works in the dashboard: Set up TTS, TTS voices, Auto read, TTS moderation, Voice cloning.

Actions

Tool	REST	Access
get_tts_settings	GET /tts/settings	Read
update_tts_settings	PATCH /tts/settings	Write
get_tts_preview_settings	GET /tts/preview	Read
update_tts_preview_settings	PATCH /tts/preview	Write
get_tts_moderation_settings	GET /tts/moderation	Read
update_tts_moderation_settings	PATCH /tts/moderation	Write
list_tts_blocked_messages	GET /tts/moderation/blocked-messages	Read
list_tts_voices	GET /tts/voices	Read
get_tts_voice	GET /tts/voices/{voice_id}	Read
add_tts_voice	POST /tts/voices	Write
update_tts_voice	PATCH /tts/voices/{voice_id}	Write
update_tts_voice_permissions	PATCH /tts/voices	Write
remove_tts_voice	DELETE /tts/voices/{voice_id}	Write
enable_all_tts_voices	POST /tts/voices/enable-all	Write
disable_all_tts_voices	POST /tts/voices/disable-all	Write
list_tts_library_voices	GET /tts/library	Read
list_tts_library_filters	GET /tts/library/filters	Read
get_tts_stats	GET /tts/stats	Read
list_recent_tts_messages	GET /tts/messages	Read
skip_tts_message	POST /tts/queue/skip	Write
clear_tts_queue	POST /tts/queue/clear	Write
list_custom_tts_voices	GET /tts/custom-voices	Read
create_custom_tts_voice	POST /tts/custom-voices	Write
train_custom_tts_voice	POST /tts/custom-voices/{voice_id}/train	Write
finalize_custom_tts_voice	POST /tts/custom-voices/{voice_id}/finalize	Write
delete_custom_tts_voice	DELETE /tts/custom-voices/{voice_id}	Write
get_auto_read_settings	GET /tts/auto-read	Read
update_auto_read_settings	PATCH /tts/auto-read	Write
list_auto_read_rules	GET /tts/auto-read/rules	Read
create_auto_read_rule	POST /tts/auto-read/rules	Write
update_auto_read_rule	PATCH /tts/auto-read/rules/{id}	Write
delete_auto_read_rule	DELETE /tts/auto-read/rules/{id}	Write
reorder_auto_read_rules	PUT /tts/auto-read/rules/order	Write

get_tts_settings

Get TTS settings. Get the channel TTS settings: on/off, cooldowns, volume, max length, delay, read sender, public voice list, and on-screen preview. Also the TTS widget URL (add it as a browser source in OBS), when the widget was last open, and the public voice list URL. Null means the value was never set. Auto read has its own tools (get_auto_read_settings).

GET /api/v1/tts/settings

No input fields.

update_tts_settings

Update TTS settings. Change some TTS settings. Only the fields you send change. Requires a verified account. The TTS widget gets the new on/off, volume, and delay at once.

PATCH /api/v1/tts/settings

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream).

Field	Type	Required	Description
tts_enabled	boolean	No	Master switch. When false, TTS commands and Auto read do nothing.
auto_tts	boolean	No	Deprecated: use enabled in update_auto_read_settings. Auto read on or off (the same setting).
auto_tts_voice	"male" or "female" or "male_us" or "female_us"	No	Deprecated: use voice in update_auto_read_settings, which takes any voice id. Setting this old field also sets “read everyone” on and replaces the Auto read voice for everyone.
global_tts_cooldown	integer	No	Seconds between any two TTS commands in the channel, 0-120.
user_tts_cooldown	integer	No	Seconds a viewer must wait before using another TTS command, 0-120.
global_tts_volume	number	No	Volume of all TTS voices, 0 (mute) to 1 (full).
global_tts_max_chars	integer	No	Longest TTS message, 0 to 300 characters. Longer messages are not read (they are not cut off).
tts_delay	integer	No	Seconds of silence between TTS messages, 0-30.
tts_read_sender	boolean	No	Read the sender name before the message.
tts_voice_list_enabled	boolean	No	Public voice list page where viewers see the enabled voices, recent messages, and a leaderboard.
on_screen_preview	boolean	No	Show the message text on the TTS widget while it plays. Change its look with update_tts_preview_settings.

get_tts_preview_settings

Get the TTS on-screen preview look. Get how the on-screen TTS preview looks (position, animation, text, background). Turn the preview on or off with on_screen_preview in update_tts_settings.

GET /api/v1/tts/preview

No input fields.

update_tts_preview_settings

Update the TTS on-screen preview look. Change how the on-screen TTS preview looks. Only the fields you send change. To show or hide the preview, use on_screen_preview in update_tts_settings.

PATCH /api/v1/tts/preview

Needs a read and write key or connection.

Field	Type	Required	Description
position	"center" or "top" or "bottom"	No	Where the text shows: center, top, or bottom. Default center.
animation	"none" or "fade" or "slide-left" or "slide-right" or "slide-top" or "slide-bottom"	No	How the text appears: none, fade, slide-left, slide-right, slide-top, or slide-bottom. Default fade.
text_size	integer	No	Text size in pixels, 8 to 48. Default 24.
text_color	string	No	Text color as a 6-digit hex, for example FFFFFF (a leading # is removed). Default white.
background	boolean	No	Show a dark box behind the text. Default true.
background_opacity	integer	No	Background opacity in percent, 0 to 100. Default 100.
show_sender	boolean	No	Show who sent the message. Default true.
show_voice	boolean	No	Show the voice name. Default true.

get_tts_moderation_settings

Get TTS moderation filters. Get the filters that block TTS messages before they play: bad words, repeats, links, custom words and regex, banned usernames, and AI filters.

GET /api/v1/tts/moderation

No input fields.

update_tts_moderation_settings

Update TTS moderation filters. Change some TTS moderation filters. Only the fields you send change. The list fields replace the whole list: read it with get_tts_moderation_settings first, then send the full new list (one entry per line).

PATCH /api/v1/tts/moderation

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
bad_word_filter	boolean	No	Block messages with common bad words.
excessive_repeat_filter	boolean	No	Block messages with lots of repeated characters or words.
url_filter	boolean	No	Block messages that contain links.
custom_bad_words	string	No	Extra words to block. One entry per line.
custom_regex	string	No	Regular expressions; a message that matches one is blocked. One entry per line.
banned_usernames	string	No	Kick usernames that can never use TTS. One entry per line.
ai_filter_sexual	boolean	No	AI filter: sexual content.
ai_filter_hate	boolean	No	AI filter: hate speech.
ai_filter_violence	boolean	No	AI filter: violence.
ai_filter_harassment	boolean	No	AI filter: harassment.
ai_filter_illicit	boolean	No	AI filter: illicit activity.
ai_filter_self_harm	boolean	No	AI filter: self-harm.
ai_filter_gibberish	boolean	No	AI filter: gibberish or spam.
ai_filter_offensive_name	boolean	No	AI filter: offensive sender names.

list_tts_blocked_messages

List blocked TTS messages. List TTS messages the moderation filters blocked, newest first, with the reason.

GET /api/v1/tts/moderation/blocked-messages

Field	Type	Required	Description
limit (query)	integer	No	Max items to return (1-100, default 50).
offset (query)	integer	No	Number of items to skip (default 0).

list_tts_voices

List the TTS voices on the channel. List the voices added to the channel. Each one has a chat command (for example !male hello) and who can use it. Add more with add_tts_voice (find them with list_tts_library_voices).

GET /api/v1/tts/voices

Field	Type	Required	Description
enabled (query)	boolean	No	Only enabled (true) or only disabled (false) voices.
limit (query)	integer	No	Max items to return (1-100, default 50).
offset (query)	integer	No	Number of items to skip (default 0).

get_tts_voice

Get a TTS voice on the channel. Get one voice added to the channel, with its chat command and permissions.

GET /api/v1/tts/voices/{voice_id}

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).

add_tts_voice

Add a TTS voice to the channel. Add a voice from the library to the channel. It starts enabled for everyone with its default command. Premium voices need a premium plan. Change the command with update_tts_voice.

POST /api/v1/tts/voices

Needs a read and write key or connection.

Field	Type	Required	Description
voice_id	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).

update_tts_voice

Update a TTS voice command. Change the chat command, on/off, or who can use one voice on the channel. Only the fields you send change. Premium voices need a premium plan.

PATCH /api/v1/tts/voices/{voice_id}

Needs a read and write key or connection.

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).
command	string	No	Chat command without ”!”, letters and digits only, max 15 characters. For example “goku” for !goku.
enabled	boolean	No	Turn the voice command on or off.
everyone_only	boolean	No	Everyone can use the command.
sub_only	boolean	No	Subscribers can use the command.
vip_only	boolean	No	VIPs can use the command.
mod_only	boolean	No	Moderators can use the command.

update_tts_voice_permissions

Set who can use several TTS voices. Bulk edit: set everyone_only, sub_only, vip_only, and mod_only on several voices at once. Flags you do not send are not changed.

PATCH /api/v1/tts/voices

Needs a read and write key or connection.

Field	Type	Required	Description
voice_ids	array of integer	Yes	Voice ids to change (from list_tts_voices). Up to 500 per call; send more in batches.
everyone_only	boolean	No	Everyone can use the command.
sub_only	boolean	No	Subscribers can use the command.
vip_only	boolean	No	VIPs can use the command.
mod_only	boolean	No	Moderators can use the command.

remove_tts_voice

Remove a TTS voice from the channel. Remove a premium voice and its command from the channel. The voice stays in the library and can be added again. Free voices and your own clones stay on the channel, the same as on the dashboard: turn them off with update_tts_voice, or delete a clone with delete_custom_tts_voice.

DELETE /api/v1/tts/voices/{voice_id}

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).

enable_all_tts_voices

Enable all TTS voices. Turn on every voice on the channel. Requires a verified account. On the free plan only the free voices (male, female, brian, tiktok) are turned on and every other voice is turned off.

POST /api/v1/tts/voices/enable-all

Needs a read and write key or connection.

No input fields.

disable_all_tts_voices

Disable all TTS voices. Turn off every voice command on the channel. The voices stay added.

POST /api/v1/tts/voices/disable-all

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

No input fields.

list_tts_library_voices

Browse the TTS voice library. Search the voice library: public voices and your own cloned voices. Filter by category, language, and gender (get the values with list_tts_library_filters). added tells if the voice is on the channel; can_add tells if add_tts_voice will work (premium voices need a premium plan). installs is how many channels added the voice; messages_sent is how many TTS messages it read. KickBot tags voices with AI: categories (category keys), gender (male or female), voice_language (ISO 639-1 code of the language spoken in the training audio), and identity (who the voice imitates). They are empty or null until a voice is tagged. tags is the old user-chosen tag list (deprecated, kept for old clients).

GET /api/v1/tts/library

Field	Type	Required	Description
search (query)	string	No	Find voices whose name, default command, or identity (who the voice is, and other names for it) contains this text. Only letters, numbers, spaces, and - _ ’ are used; other characters count as spaces.
category (query)	"streamers" or "musicians" or "athletes" or "politicians" or "actors_tv" or "cartoons" or "anime" or "video_games" or "tv_movie_characters" or "memes" or "narrators"	No	Only voices in this AI category (a key from list_tts_library_filters).
language (query)	string	No	Only voices made in this language: an ISO 639-1 code such as en, es, or tr (see list_tts_library_filters).
gender (query)	"male" or "female"	No	Only male or only female voices.
tag (query)	string	No	Deprecated: use category. Only voices with this old user-chosen tag, for example: cartoon, content creator, politics, celebrity, movie, video game, TV, anime, fantasy, male, female.
sort (query)	"popular" or "most_installed" or "newest" or "trending"	No	popular (most TTS messages, default), most_installed (on the most channels: the dashboard library “Popular”), newest (the dashboard “Recent”), or trending (the top 50 public voices this week).
premium (query)	boolean	No	Only premium (true) or only free (false) voices.
added (query)	boolean	No	Only voices already on the channel (true) or not yet added (false).
limit (query)	integer	No	Max items to return (1-100, default 50).
offset (query)	integer	No	Number of items to skip (default 0).

list_tts_library_filters

List the TTS voice library filters. List the values for the list_tts_library_voices filters: the categories (key and English label), the languages that have library voices (ISO 639-1 code, English name, and number of voices, most voices first), and the genders.

GET /api/v1/tts/library/filters

No input fields.

get_tts_stats

Get TTS usage stats. Number of TTS messages in the last 24 hours, 7 days, 30 days, and all time.

GET /api/v1/tts/stats

No input fields.

list_recent_tts_messages

List recent TTS messages. List recent TTS messages, newest first. Use an id with skip_tts_message to skip a message that has not played yet.

GET /api/v1/tts/messages

Field	Type	Required	Description
limit (query)	integer	No	Max messages to return (1-100, default 20).
offset (query)	integer	No	Number of items to skip (default 0).

skip_tts_message

Skip a TTS message. Skip one TTS message in the live queue on the TTS widget (stops it if it is playing). Use the id from list_recent_tts_messages. A message that already played is not affected.

POST /api/v1/tts/queue/skip

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

Field	Type	Required	Description
tts_id	integer	Yes	TTS message id from list_recent_tts_messages.

clear_tts_queue

Clear the TTS queue. Remove every waiting TTS message from the live queue on the TTS widget.

POST /api/v1/tts/queue/clear

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

No input fields.

list_custom_tts_voices

List your cloned TTS voices. List the custom voices you cloned (premium) and how many clone slots you have. ready = true once the voice has a sample (finalize_custom_tts_voice done). KickBot tags each new clone with AI in the background: categories, gender, voice_language, and identity appear a little after finalize_custom_tts_voice (usually within a few minutes). Until then, or when KickBot cannot tell, they are empty or null.

GET /api/v1/tts/custom-voices

No input fields.

create_custom_tts_voice

Start cloning a TTS voice (step 1 of 4). Premium only. Clone a voice from audio samples. This is step 1 of 4: 1) create_custom_tts_voice: creates the voice and returns upload URLs (valid for 30 minutes). 2) Upload each audio file with HTTP PUT to its upload_url: body = the raw file, with the headers in its headers (Content-Type must be exactly the content_type you sent, and the body must be exactly size_bytes long, or the upload fails). Upload the square icon (200x200 is enough) to icon_upload.upload_url the same way. Audio files: Allowed types: audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav, audio/vnd.wave, audio/ogg, audio/opus, audio/webm, audio/mp4, audio/x-m4a, audio/m4a, audio/aac, audio/x-aac, audio/flac, audio/x-flac. Max size: 10 MiB (10485760 bytes). Icon: Allowed types: image/png, image/jpeg, image/gif, image/webp. Max size: 5 MiB (5242880 bytes). 3) train_custom_tts_voice with the audio_url values. Each file must be under 10 MB; use 10 to 90 seconds of clear speech in total, up to 5 files. 4) finalize_custom_tts_voice: makes the sample clip and sets the icon (takes about 10 to 20 seconds). The voice also gets a disabled command on the channel; enable it with update_tts_voice after step 4. After step 4 KickBot tags the voice with AI (categories, gender, and the language spoken in the audio) in the background; the tags show in list_custom_tts_voices and list_tts_library_voices a little later. You do not need to send tags.

POST /api/v1/tts/custom-voices

Needs a read and write key or connection. Rate limit: 5 per minute, 30 per day.

Field	Type	Required	Description
name	string	Yes	Voice name shown in the library, max 20 characters.
command	string	Yes	Default chat command without ”!”, letters and digits only, max 20 characters.
tags	array of "cartoon" or "content creator" or "politics" or "celebrity" or "movie" or "video game" or "TV" or "anime" or "fantasy" or "male" or "female"	No	Deprecated and optional: KickBot now sets AI categories after the voice is finished. Old tags you may still send: cartoon, content creator, politics, celebrity, movie, video game, TV, anime, fantasy, male, female.
audio_files	array of object	Yes	The audio samples you will upload (1 to 5), for example [{ “file_name”: “take1.mp3”, “content_type”: “audio/mpeg”, “size_bytes”: 812345 }].
icon	object	Yes	The voice icon you will upload (a square image). Required, the same as on the dashboard: finalize_custom_tts_voice sets it as the voice picture.
public	boolean	No	Ask KickBot to make the voice public for all users (reviewed by staff). Default false.
consent	boolean	Yes	Must be true: you confirm that you have the rights to upload and clone these voice samples.

train_custom_tts_voice

Train a cloned TTS voice (step 3 of 4). Premium only. After you uploaded the audio files from create_custom_tts_voice, send them to the voice clone service. Files of 10 MB or more are skipped. Then call finalize_custom_tts_voice.

POST /api/v1/tts/custom-voices/{voice_id}/train

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 5 per minute, 30 per day.

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).
audio_urls	array of string	Yes	The audio_url values from create_custom_tts_voice for the files you uploaded.

finalize_custom_tts_voice

Finish a cloned TTS voice (step 4 of 4). Premium only. After train_custom_tts_voice, make the sample clip and set the uploaded icon. Takes about 10 to 20 seconds. If it fails, wait a minute and call it again. The voice command starts disabled; enable it with update_tts_voice. KickBot then tags the voice with AI in the background, so categories, gender, voice_language, and identity are still empty in this answer; read them later with list_custom_tts_voices.

POST /api/v1/tts/custom-voices/{voice_id}/finalize

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 5 per minute, 30 per day.

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).

delete_custom_tts_voice

Delete a cloned TTS voice. Delete a custom voice you cloned and remove its command from your channel. This frees a clone slot. It cannot be undone.

DELETE /api/v1/tts/custom-voices/{voice_id}

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
voice_id (in the path)	integer	Yes	Voice id (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices).

get_auto_read_settings

Get Auto read settings. Auto read: KickBot reads chat messages that are not commands aloud. Returns the settings, the filters, and the voice rules for viewers and Kick badges. KickBot uses the first rule that matches: viewer rules first, then badge rules in their order, then the voice for everyone else. rules_active is false without Premium: the rules stay saved but are not used.

GET /api/v1/tts/auto-read

No input fields.

update_auto_read_settings

Update Auto read settings. Change some Auto read settings or filters. Only the fields you send change. Requires a verified account.

PATCH /api/v1/tts/auto-read

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
enabled	boolean	No	Auto read on or off. It also needs TTS on (update_tts_settings tts_enabled) and the TTS widget open in OBS.
read_everyone	boolean	No	false = “Do not read” for everyone without a rule, so only viewers and badges with a rule are read. Premium only.
voice_id	null or integer	No	Voice for everyone without a rule (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices). Free plans can use free voices only. null = use legacy_voice.
max_reads_per_minute	integer	No	Most messages read per minute, 1 to 30.
read_sender	boolean	No	Read the sender name before the message.
min_chars	integer	No	Shorter messages are not read, 0 to 300. 0 = no minimum.
max_chars	integer	No	Longer messages are not read (they are not cut off), 1 to 300.
skip_links	boolean	No	true = a message with a link is not read. false = the link is removed and the rest is read.
skip_emote_only	boolean	No	true = a message with only emotes is not read. false = emote names are read.
skip_bots	boolean	No	Skip known bot accounts (BotRix, Kicklet, Lumia Stream, …) and accounts with the Kick bot badge.
ignored_viewers	array of string	No	Kick usernames that are never read, up to 100. Replaces the whole list.

list_auto_read_rules

List Auto read voice rules. List the Auto read voice rules in the order KickBot checks them. KickBot uses the first rule that matches: viewer rules first, then badge rules in their order, then the voice for everyone else.

GET /api/v1/tts/auto-read/rules

No input fields.

create_auto_read_rule

Add an Auto read voice rule. Give one viewer (kind “user”) or a Kick badge (kind “badge”) its own voice, or “Do not read” (voice_id null). Premium only. Up to 100 viewer rules; one rule per badge (subscriber can have one per length). A new badge rule goes last, except a subscriber length, which goes above the shorter subscriber rules.

POST /api/v1/tts/auto-read/rules

Needs a read and write key or connection.

Field	Type	Required	Description
kind	"user" or "badge"	Yes	“user” for one viewer, “badge” for a Kick badge.
username	string	No	For kind “user”: the Kick username.
badge	"broadcaster" or "moderator" or "vip" or "og" or "founder" or "subscriber" or "sub_gifter" or "verified" or "staff" or "sidekick"	No	For kind “badge”: broadcaster, moderator, vip, og, founder, subscriber, sub_gifter, verified, staff, sidekick.
min_months	null or integer	No	For badge “subscriber” only: subscribed for at least this many months. 0 or null = every subscriber.
voice_id	null or integer	Yes	Voice for this rule (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices). Any public voice or your own voices. null = “Do not read”.

update_auto_read_rule

Update an Auto read voice rule. Change the voice, the username, the badge, or the subscriber length of a rule. Only the fields you send change. Premium only.

PATCH /api/v1/tts/auto-read/rules/{id}

Needs a read and write key or connection.

Field	Type	Required	Description
id (in the path)	integer	Yes	The item id.
username	string	No	For kind “user”: the Kick username.
badge	"broadcaster" or "moderator" or "vip" or "og" or "founder" or "subscriber" or "sub_gifter" or "verified" or "staff" or "sidekick"	No	For kind “badge”: broadcaster, moderator, vip, og, founder, subscriber, sub_gifter, verified, staff, sidekick.
min_months	null or integer	No	For badge “subscriber” only: subscribed for at least this many months. 0 or null = every subscriber.
voice_id	null or integer	No	Voice for this rule (voice_id from list_tts_voices, list_tts_library_voices, or list_custom_tts_voices). Any public voice or your own voices. null = “Do not read”.

delete_auto_read_rule

Remove an Auto read voice rule. Remove a voice rule. Works without Premium too, so saved rules can be cleaned up.

DELETE /api/v1/tts/auto-read/rules/{id}

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
id (in the path)	integer	Yes	The item id.

reorder_auto_read_rules

Reorder Auto read badge rules. Set the order of the badge rules: send every badge rule id, first = checked first. Viewer rules always come before badge rules and are not in this list. Premium only.

PUT /api/v1/tts/auto-read/rules/order

Needs a read and write key or connection.

Field	Type	Required	Description
ids	array of integer	Yes	Every badge rule id, in the new order.