Developer Guide to SmartVoice Text-to-Speech API

By SmartVoice API editorial team · Updated 2026-11-18

This guide helps product teams build connected voice experiences for smart home and IoT devices. You will find everything needed to integrate our text-to-speech API, from generating your first API key to handling long-form audio concatenation. We cover the full workflow so you can move from setup to production quickly.

We designed this documentation for developers who need reliable, multilingual audio output without complex infrastructure. Learn how to use the standard OpenAI SDK structure with our endpoint, manage rate limits, and handle errors. Every step is explained with concrete examples to ensure your voice assistant delivers clear, consistent results.

Developer Guide to SmartVoice Text-to-Speech API

Frequently asked questions

How do I get an API key?

Sign up on https://playll88.com/get-api-key/ using Google or email. Accounts created via email start without trial credit, while Google sign-ins receive $0.50 valid for 7 days. You can issue a new key at any time; the old one stops immediately.

What is the base URL?

The API base URL is https://api.playll88.com/v1. Send POST requests to https://api.playll88.com/v1/audio/speech. Other endpoints include GET /v1/voices and GET /v1/models for checking available voices, languages, formats, and pricing information.

Which SDKs work?

The official OpenAI SDKs work by changing the base_url to https://api.playll88.com/v1 and using your site's key. We do not provide an official SDK of our own, so use the OpenAI SDK or plain HTTP requests directly.

How do I change the voice?

Include the voice field in your request JSON with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrator to deep documentary, suitable for various smart home contexts.

What is the character limit?

Each request supports up to 4096 characters in the input field. For longer texts, split the text into parts of this limit and join the resulting audio files. Spaces and punctuation count toward the character total.

Can I change the speed?

Yes, set the speed parameter between 0.25 and 4.0. This allows you to adjust the playback rate to fit your application’s needs, whether for quick alerts or slower, clearer instructions in voice assistants.

How do I specify language?

Use the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set it for non-English Latin-script text to ensure accuracy.

What happens on rate limit?

You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load a request may wait in a queue. Failed requests are free.

Is SSML supported?

No, SSML is not supported. We do not offer phoneme dictionaries or custom pronunciation lexicons. You control pacing and emphasis by adjusting the speed parameter or splitting text into separate requests for precise control.

Do I need streaming?

Streaming is not available; the API returns the complete audio file in the response. We do not support WebSocket or real-time partial audio. This fits workflows where the full audio asset is needed rather than live playback.

How do I handle errors?

If synthesis fails, the charge is returned in full. Monitor your response status codes. Failed requests incur no cost, so you can safely retry or adjust parameters without worrying about wasting your account balance.

Can I use custom voices?

No, custom voice cloning is not offered. You cannot upload your own voice or design new voices. The eight presets are based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings.

How do I revoke a key?

Issue a new key from your account dashboard. The old key stops working immediately when the new one is active. This allows you to rotate credentials securely without manual deactivation steps or waiting for expiration.

What is the response format?

Specify response_format as mp3, wav, opus, flac, or pcm. The API returns the generated audio file directly in the response. Each file carries an inaudible watermark marking it as synthetic speech, ensuring clear identification of AI-generated audio.

First request

curl

curl https://api.playll88.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playll88.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playll88.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Quickstart with Curl

Sound wave illustration for: Quickstart with Curl

SmartVoice API is designed for embedded systems and voice assistants, providing clear multilingual audio for smart home devices. Generate your key via /get-api-key/ and start sending requests immediately.

Generate your API key

Generate your API key

Sign up on the /get-api-key/ page using Google or email. Your account provides a single active Bearer token starting with tts-.

  • Accounts are per site (playll88.com).
  • One active key per account; issuing a new one invalidates the old immediately.

Send a POST request

Send a POST request

Use the endpoint POST https://api.playll88.com/v1/audio/speech. The JSON body mirrors the OpenAI structure: specify model (tts-1 or tts-1-hd), input text (max 4096 characters), and voice.

Curl example: curl -X POST https://api.playll88.com/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Hello", "voice": "nova"}'

Receive audio file

Receive audio file

The API returns the audio file directly in the response body. Supported formats include MP3, WAV, OPUS, FLAC, and PCM.

Audio generation takes roughly real-time for long texts (25 chars/sec) but may queue under load.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The SmartVoice API mirrors the OpenAI speech endpoint structure, allowing you to leverage existing OpenAI SDKs with minimal configuration. This compatibility ensures a smooth integration for teams already familiar with OpenAI’s developer tools.

Use official OpenAI SDKs

You can use the official OpenAI SDKs for your preferred language. This reduces boilerplate code and leverages established client libraries for handling requests and responses.

Change base_url to our endpoint

Update your SDK configuration to point to our API base URL: https://api.playll88.com/v1. This directs all API calls to our infrastructure while maintaining standard request formats.

Use same request structure

The request body remains identical to the OpenAI speech endpoint. Pass your model, input, voice, response_format, and speed parameters as usual. Authentication uses a Bearer token in the header.

  • Model: "tts-1" or "tts-1-hd"
  • Input: text string up to 4096 characters
  • Voice: select from 8 presets
  • Response format: mp3, wav, opus, flac, or pcm

Request Parameters

Sound wave illustration for: Request Parameters

Configure your TTS requests by selecting the engine, inputting your text, and choosing a voice preset. The API accepts standard JSON bodies, making it easy to integrate with existing smart home or IoT workflows without learning a new protocol.

Model: tts-1 or tts-1-hd

Choose between tts-1 and tts-1-hd. Both use the same underlying engine and pricing model, so your choice depends only on whether you prioritize the slight quality difference of the HD variant for your specific audio output needs.

Input text up to 4096 characters

Each request can process up to 4096 characters of text. Spaces, punctuation, and emojis count toward this limit. For longer content, split the text into chunks and join the resulting audio files in your application logic.

  • Maximum 4096 characters per request
  • Spaces and punctuation count as characters
  • Split and join for longer texts

Voice selection from 8 presets

Select from eight distinct voice presets optimized for clarity and natural speech. Each voice supports all 23 supported languages, allowing you to maintain consistent audio branding across your multilingual smart device fleet.

  • Aria: Warm, clear narrator
  • Felix: Energetic, promo style
  • Milo: Friendly, conversational
  • Atlas: Neutral, news style
  • Luna: Soft, storytelling tone
  • Nova: Bright, upbeat delivery

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

SmartVoice API returns audio in five standard formats: mp3, wav, opus, flac, and pcm. Choose the format that best balances file size, quality, and compatibility for your smart home or IoT device.

MP3 for small file sizes

MP3 is ideal for bandwidth-constrained environments. It provides a good balance between audio quality and file size, making it suitable for devices with limited storage or slower network connections.

WAV for high quality

WAV offers uncompressed audio, ensuring the highest fidelity for voice assistants and premium smart speakers. Use this format when audio quality is prioritized over file size.

OPUS, FLAC, PCM options

OPUS provides efficient compression for audio files. FLAC offers lossless compression for archival quality. PCM provides raw, uncompressed audio data for direct processing.

  • OPUS: Efficient compression, low latency
  • FLAC: Lossless compression, smaller than WAV
  • PCM: Raw, uncompressed audio data

Rate Limits

Sound wave illustration for: Rate Limits

SmartVoice API enforces rate limits to ensure stable generation for your smart home devices. Each API key allows 60 requests per minute, which is sufficient for most voice assistant integrations. Requests are processed one after another, so under load a request may wait in a queue.

Under heavy load, longer texts may take a few seconds to generate, so plan your polling intervals accordingly to avoid timeouts.

60 requests per minute per key

Once you have topped up your account, your key supports up to 60 requests per minute. This is the standard limit for production use, allowing your voice assistant to handle multiple user queries smoothly.

  • Applies per API key
  • Stable limit for top-up accounts

10 requests per minute initially

New keys start with a lower limit of 10 requests per minute.

  • Default for new keys
  • Prevents initial overload

Limit increases after top-up

To increase your rate limit, simply top up your balance using USDT on the TRON network. The increase is automatic and usually takes effect within minutes after the transfer is confirmed.

  • USDT (TRC-20) only
  • Automatic credit and limit update

Handling Long Texts

Sound wave illustration for: Handling Long Texts

SmartVoice API processes text in chunks of up to 4096 characters per request. For longer content, split your input into smaller segments and send each as a separate POST request to the /v1/audio/speech endpoint.

Split text into parts

Divide your script into segments that stay under the 4096-character limit. This ensures each request is processed efficiently without truncation.

Join audio files

Receive individual audio files for each segment. Concatenate these files in your application to create a seamless playback experience for your users.

Manage character limits

Remember that spaces and punctuation count toward the character limit. Plan your splits to maintain natural pauses between audio segments for better listening quality.

Error Handling

Sound wave illustration for: Error Handling

SmartVoice API returns standard HTTP status codes to indicate request outcomes. A 200 OK response contains the generated audio file, while 4xx errors indicate client-side issues like invalid keys or malformed requests. Understanding these codes helps you integrate smoothly into your smart home or IoT application workflows.

Check response status codes

Always inspect the HTTP status code before attempting to parse the response body. Codes in the 2xx range indicate success, while 4xx and 5xx codes signal errors that require attention. For example, a 401 Unauthorized error means your API key is invalid or expired.

  • 200: Success, audio data returned
  • 400: Bad Request, check input format
  • 401: Unauthorized, verify your API key
  • 429: Too Many Requests, rate limit exceeded
  • 500: Internal Server Error, try again later

Handle network errors

Network interruptions can occur during audio generation, especially in distributed IoT environments. Ensure your client library handles timeouts gracefully and retries failed connections. Since requests are processed sequentially, high latency might indicate queueing rather than a failure.

Retry failed requests

Implement exponential backoff for transient errors like 500 Internal Server Error or 429 Too Many Requests. Avoid immediate retries to prevent overwhelming the API. Remember that failed requests are free, so retrying is safe.

Authentication

Sound wave illustration for: Authentication

Secure your API key and include it in every request header. This token authenticates your account and tracks usage against your balance.

Bearer token in header

Include Authorization: Bearer tts-... in your HTTP headers. The key must be valid and active to process synthesis requests.

One active key per account

Each account holds a single active key. If you issue a new key, the previous one stops immediately. Use this to rotate credentials without delay.

Revoke key to invalidate

Issue a new key to effectively revoke the old one. This provides immediate security control without waiting for session timeouts.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Connect devices seamlessly to deliver intuitive, responsive living experiences.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. openai-node on GitHub
  3. IETF RFC 7845: Ogg Opus
  4. openai-python on GitHub
  5. TRON developer hub: TRC-20
  6. Node.js documentation
  7. Python documentation
  8. MDN: Web Speech API
  9. LibriVox public-domain audiobooks
  10. OpenAI API reference: create speech
  11. curl documentation
  12. Tether (USDT)

More on this site