Get Started with Our Cloud Text-to-Speech API

By IoT TTS Lab editorial team · Updated 2026-11-19

This guide helps indie developers integrate voice capabilities into smart home assistants and IoT devices. You will learn how to send text and receive audio files using a simple, character-based API without complex streaming dependencies. We cover authentication, endpoint structures, and practical code examples tailored for embedded systems and backend services.

Readers will find clear instructions on generating API keys, selecting voices, and handling long text inputs. The guide explains rate limits, error handling, and SDK integration so you can build reliable voice features quickly. All examples use standard HTTP requests compatible with the OpenAI SDK, ensuring easy adoption for your existing workflows.

Get Started with Our Cloud Text-to-Speech API

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Your account is specific to k665.info. The dashboard displays your active API key, which you use with the Bearer token format. You can issue a new key at any time, which immediately invalidates the previous one.

What is the base URL for the API?

The API base URL is https://api.k665.info/v1. You send POST requests to https://api.k665.info/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.

Can I use the OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.k665.info/v1 and providing your site-specific API key. This allows you to integrate TTS into existing workflows without learning a new client library.

What are the rate limits?

You are limited to 60 requests per minute per API key. If you have not yet topped up your account, the limit is lower at 10 requests per minute. Requests are processed sequentially, so under load, synthesis may wait in a queue before generating audio.

How do I handle long texts?

Split your input text into parts of up to 4096 characters. Send each part as a separate request and join the resulting audio files. This ensures compliance with the character limit per request while allowing you to generate audio for longer documents or scripts.

What audio formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format field in your JSON request body. The API returns the generated audio file directly in the response, ready for playback or storage in your IoT device.

How do I specify a 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. For non-English Latin-script text, explicitly set the language to ensure accurate synthesis across the 23 supported languages.

What happens if the API fails?

Failed requests are free. If synthesis fails, the charge is returned in full to your account balance. You can retry the request or split the text differently. Check the /v1/voices endpoint for details on available voices and formats to ensure your request parameters are correct.

First request

curl

curl https://api.k665.info/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.k665.info/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.k665.info/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

Authentication and API Keys

Sound wave illustration for: Authentication and API Keys

Access the /get-api-key/ dashboard to generate your unique API key. You can sign up using Google or email. The dashboard displays your active key, current balance, and a ready-to-use curl example for immediate testing.

Include your key in the request header as Authorization: Bearer tts-.... Only one active key is allowed per account. If you need to reset access, you can issue a new key immediately, which invalidates the old one at once.

Generate API Key on Dashboard

Generate API Key on Dashboard

Navigate to the /get-api-key/ page to create your account via Google or email. The dashboard provides your API key, balance, and usage stats. A ready curl example is available for quick verification.

Bearer Token Authorization

Bearer Token Authorization

Include your key in the header: Authorization: Bearer tts-.... This authenticates all requests to the /v1/ endpoints. Ensure the key is kept secure in your IoT device or backend configuration.

Key Revocation and Regeneration

Only one key is active per account. Generating a new key immediately invalidates the previous one. This ensures secure access management for your smart home or IoT projects.

Endpoints and Request Structure

Sound wave illustration for: Endpoints and Request Structure

Interact with the TTS API through three primary endpoints. The speech endpoint converts text to audio, while the voices and models endpoints provide metadata for configuration.

POST /v1/audio/speech

Send text to generate audio files. Submit a JSON body with your model, input text, voice selection, and desired format. The API returns the audio file directly in the response.

GET /v1/voices

Retrieve available voice presets, supported languages, and format options. Use this endpoint to verify which voices are active and compatible with your target languages before making speech requests.

GET /v1/models

List available models, such as tts-1 and tts-1-hd. This endpoint confirms the engine options and helps you select the appropriate quality level for your IoT device's processing capabilities.

Request Parameters Explained

Sound wave illustration for: Request Parameters Explained

Configure your synthesis requests by selecting the engine model, defining the input text constraints, and specifying the voice and language parameters. The API accepts standard JSON bodies with these core fields to generate audio files efficiently.

Model Selection (tts-1, tts-1-hd)

Both "tts-1" and "tts-1-hd" use the same underlying engine and pricing. Choose based on your quality preference; there is no performance difference between the two model identifiers.

Input Text Length Limit

Each request supports up to 4096 characters. Spaces, punctuation, and special characters count toward this limit. For longer scripts, split the text into chunks and join the resulting audio files.

Voice and Language Codes

Select one of eight voice presets (e.g., aria, nova, felix) for your audio output. You can optionally specify a language ISO code (e.g., "en", "de") to ensure correct pronunciation, as the system guesses the language from the script otherwise.

  • 8 voice presets available
  • 23 supported languages
  • Optional ISO language code

Response Formats and Codes

Sound wave illustration for: Response Formats and Codes

The API returns audio data directly in the response body, allowing your IoT device or backend service to immediately play or store the generated speech file.

You can choose from five supported formats—mp3, wav, opus, flac, and pcm—depending on your device’s decoding capabilities and bandwidth constraints.

Audio File Return Formats

Select your preferred format via the response_format parameter. MP3 offers a good balance of quality and file size, while WAV provides uncompressed clarity for local playback. OPUS and FLAC are ideal for storage efficiency, and PCM is useful for raw audio processing pipelines.

  • Supported formats: mp3, wav, opus, flac, pcm

Success Response Structure

A successful request returns an HTTP 200 status code with the audio binary data in the response body. The Content-Type header indicates the selected format (e.g., audio/mpeg).

Ensure your client handles binary data correctly without interpreting it as JSON. No additional metadata is included in the response body itself.

Error Handling and Status Codes

Errors return standard HTTP status codes. A 401 Unauthorized indicates an invalid or revoked API key. A 429 Too Many Requests signals you have exceeded the 60 requests per minute limit.

A 400 Bad Request occurs if input exceeds 4096 characters or uses an invalid voice or format. Failed synthesis requests are free, so no charge is applied to your balance.

  • 401: Invalid API key
  • 429: Rate limit exceeded
  • 400: Invalid parameters or input length

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

Manage your API usage carefully to ensure reliable voice generation for your IoT devices. Understanding the request limits helps you avoid interruptions during critical voice interactions.

60 Requests Per Minute Limit

Each API key is allowed a maximum of 60 requests per minute. This limit applies to the POST /v1/audio/speech endpoint. If you exceed this threshold, subsequent requests will receive a rate limit error response.

Initial Rate for New Accounts

New accounts start with a lower limit of 10 requests per minute. This restriction remains in effect until you complete your first top-up. Once the transfer is confirmed, your rate increases to the standard 60 requests per minute.

Queue Behavior Under Load

Requests are processed sequentially. If you send multiple requests rapidly, they are queued and handled one after another. For long texts, send the next chunk after receiving the previous audio file to maintain a steady flow without overwhelming the queue.

Rate Limits and Throttling

Code Examples: Curl and SDK

Sound wave illustration for: Code Examples: Curl and SDK

Integrate voice synthesis into your IoT device or smart home assistant with minimal code. You can send raw HTTP requests using curl or leverage the official OpenAI SDK for structured object handling by changing the base_url.

Both methods require your API key and follow the same JSON payload structure, ensuring consistent results across different programming environments.

Basic Curl Request Example

Use this command to generate speech directly from the terminal. Replace YOUR_API_KEY with your token from the dashboard.

```bash curl -X POST https://api.k665.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3 ```

OpenAI SDK Integration

The API mirrors the OpenAI speech endpoint, allowing you to use their Python or Node.js SDKs with a simple configuration change.

Initialize the client by pointing it to our base URL, then call the audio.speech.create() method with your parameters.

Base URL Configuration

Set the base_url to https://api.k665.info/v1 in your SDK client configuration. This directs all requests to our processing cluster while maintaining standard request shapes.

Ensure you use the correct Authorization: Bearer tts-... header for authentication.

Handling Long Text Inputs

Sound wave illustration for: Handling Long Text Inputs

Our API accepts up to 4096 characters per request. This limit applies to the input text field, including spaces and punctuation. If your content exceeds this length, you must split the text into smaller chunks before sending them to the endpoint.

Each chunk generates a separate audio file. You will need to concatenate these files in your application logic to create the final audio stream or file for playback in your IoT device or smart home assistant.

4096 Character Limit per Request

The input field in your POST request is strictly limited to 4096 characters. Exceeding this limit will result in a 400 Bad Request error. Spaces, punctuation, and special characters count toward this total. For long-form content like audiobook chapters or detailed device instructions, you must handle the splitting logic in your client code.

Splitting and Joining Audio

When you split text, each API call returns a distinct audio file. Your application must join these files sequentially to maintain continuity. Since requests are processed one after another, there may be slight gaps between segments. Ensure your playback logic can handle these discrete file boundaries without abrupt stops.

  • Use standard audio libraries to concatenate MP3 or WAV files.
  • Maintain the original order of text chunks to preserve narrative flow.

Batch Processing Strategy

For optimal performance, send requests sequentially rather than in parallel. The queue processes requests one by one, so parallel requests may experience increased latency. Send the next chunk only after receiving the previous audio file. This approach minimizes queue wait times and ensures predictable generation speeds of roughly 25 characters of text per second of generation.

Troubleshooting Common Issues

Sound wave illustration for: Troubleshooting Common Issues

When your IoT device or script fails to generate audio, the most common causes are authentication errors, rate limit caps, or language detection mismatches. This section helps you resolve these issues quickly so your voice features stay online.

Ensure your API key is active and correctly formatted. Check your balance and verify that you haven’t exceeded the 60 requests per minute limit. If language detection fails, explicitly set the language parameter for non-English text.

Invalid API Key Errors

Check the Authorization: Bearer header. Ensure the key starts with tts- and matches the one on your dashboard. Keys expire immediately upon regeneration.

If you created an account with email/password, you may lack trial credit. Verify your balance on the dashboard.

Ensure you are using the correct base URL: https://api.k665.info/v1.

  • Verify key format: tts-...
  • Check dashboard for active keys
  • Confirm base URL

Rate Limit Exceeded Responses

New accounts start with 10 requests per minute. After your first top-up, this increases to 60 requests per minute.

If you exceed the limit, you receive a 429 error. Wait before retrying, or split long texts into smaller chunks under 4096 characters.

Requests are processed sequentially; under load, queuing may occur.

  • 10 req/min for new accounts
  • 60 req/min after top-up
  • Split text to stay under limit

Language Detection Failures

If language is not set, the API guesses based on the script. Latin script defaults to English.

For non-English Latin text (e.g., Spanish, French), explicitly set the language parameter to avoid incorrect pronunciation.

Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

  • Set language explicitly for non-English
  • Latin script defaults to English
  • Verify language support list

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Beginners can start generating speech in minutes using the provided curl examples or standard HTTP clients.

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. FFmpeg documentation
  3. ISO 639 language codes
  4. Python documentation
  5. TRON developer hub: TRC-20
  6. Tether (USDT)
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. openai-python on GitHub
  9. Node.js documentation
  10. OpenAI API reference: create speech
  11. MDN: Web Speech API
  12. curl documentation

More on this site