botnoi-voice-py

Python client for the Botnoi Voice Text-to-Speech API.

• ✅ Zero dependencies (stdlib only)
• ✅ Python 3.8+
• ✅ Type hints throughout
• ✅ Simple .save() helper to download audio

---

Installation

pip install botnoi-voice-py

---

Quick Start

from botnoi_tts import BotnoiTTS

client = BotnoiTTS(token="YOUR_BOTNOI_TOKEN")

# v1
response = client.v1("สวัสดีครับ", speaker="1")
print(response.audio_url)
response.save("output_v1.mp3")

# v2
response = client.v2("สวัสดีครับ", speaker="3")
print(response.audio_url)
response.save("output_v2.mp3")

---

API Reference

BotnoiTTS(token, timeout=30)

Parameter	Type	Description
token	str	Your Botnoi API token
timeout	int	Request timeout in seconds (default: 30)

---

client.v1(text, ...) / client.v2(text, ...)

Parameter	Type	Default	Description
text	str	—	Text to synthesise
speaker	str	"1"	Speaker ID
volume	float	1.0	0.0 – 2.0
speed	float	1.0	0.5 – 2.0
media_type	str	"mp3"	"mp3", "wav", "ogg"
language	str	"th"	"th" or "en"
save_file	bool	True	Persist file on Botnoi servers

ความแตกต่างระหว่าง v1 และ v2:

	v1	v2
Endpoint	/v1/generate_audio	/v1/generate_audio_v2
Speaker support	รุ่นเก่า	รุ่นใหม่ รองรับ speaker มากกว่า

Returns an AudioResponse object.

---

AudioResponse

Attribute	Type	Description
audio_url	str	Direct URL to the generated audio
media_type	str	Format of the audio file
text	str	Input text that was synthesised
speaker	str	Speaker ID used
version	str	API version used — "v1" or "v2"
raw	dict	Full raw API response

.save(path) -> str

Downloads the audio and saves it to path. Returns the absolute file path.

response.save("output")      # saves as output.mp3
response.save("output.wav")  # saves as output.wav

---

Error Handling

from botnoi_tts import BotnoiTTS, BotnoiAuthError, BotnoiAPIError

client = BotnoiTTS(token="...")

try:
    response = client.v2("สวัสดีครับ", speaker="3")
except BotnoiAuthError:
    print("Invalid token")
except BotnoiAPIError as e:
    print(f"API error {e.status_code}: {e}")

Exception	When raised
BotnoiAuthError	Token is invalid or missing
BotnoiAPIError	Non-200 HTTP response or connection error

---

License

MIT