Integrate Our Text-to-Speech API with OpenAI SDKs

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

This documentation guides developers in integrating our text-to-speech API into children’s book and educational audio applications. You will find step-by-step instructions for making API calls, managing authentication, and handling responses. The guide assumes you are building interactive content and need reliable narration without managing complex audio infrastructure.

We support the standard OpenAI SDK format, allowing you to use existing client libraries by simply adjusting the base URL. This page covers all endpoints, request parameters, and rate limits. You will also find concrete code examples in Python and cURL to help you generate natural-sounding speech from text quickly and efficiently.

Integrate Our Text-to-Speech API with OpenAI SDKs

Frequently asked questions

What is the base_url for the API?

The API base URL is https://api.playpg699.com/v1. You send POST requests to https://api.playpg699.com/v1/audio/speech. Authentication uses a Bearer token in the Authorization header. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences for generating audio files.

Which SDKs work with this API?

The official OpenAI SDKs work by changing the base_url to https://api.playpg699.com/v1 and using your site-specific key. You can also use plain HTTP requests. There is no official proprietary SDK, mobile SDK, or WordPress plugin available for this text-to-speech service.

How do I set the voice parameter?

Set the voice parameter to one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrators to deep documentary styles. You can also specify an optional ISO language code to ensure correct pronunciation.

What is the difference between tts-1 and tts-1-hd?

Both tts-1 and tts-1-hd use the same engine and price. The model field accepts either value without affecting the cost or processing speed. Choose based on your preference, as both deliver the same audio quality for your children's book or educational content generation.

How do I handle rate limits?

You are limited to 60 requests per minute per key, or 10 per minute before the first top-up. Requests are processed sequentially, so under load, a request may wait in a queue. Monitor your usage via the dashboard to avoid throttling during peak generation times.

Can I use WebSocket for streaming?

No, this API does not support streaming, WebSocket connections, or real-time partial audio. You send a text payload and receive the complete audio file in the response. There is no support for SSML or custom pronunciation lexicons within the standard request structure.

What happens if the input text is too long?

The API accepts up to 4096 characters per request. For longer texts, split the content into parts of this size, generate audio for each part, and join the resulting audio files. This ensures consistent quality and avoids exceeding the character limit for a single synthesis.

How do I specify the language?

Include an optional ISO language code in the request body. If omitted, the system guesses the language, defaulting to English for Latin-script text. For non-English Latin-script text, explicitly set the language parameter to ensure accurate pronunciation across the supported 23 languages.

First request

curl

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

Authentication

Sound wave illustration for: Authentication

To use the TaleTTS API, you must authenticate every request with a Bearer token. This ensures secure access to your account’s character quota and billing data.

Bearer token format

Your API key is a string starting with tts-. It is issued when you sign up via Google or email on /get-api-key/.

  • Format: tts-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Case-sensitive string

Authorization header

Include the key in the HTTP header for every API call. This applies to speech generation and metadata endpoints.

  • Header name: Authorization
  • Header value: Bearer tts-...

Key management

Each account has one active key. You can issue a new key at any time via the dashboard; the old key stops immediately.

  • One active key per account
  • Instant invalidation on rotation

Endpoints

Sound wave illustration for: Endpoints

The API exposes three core endpoints for generating and managing audio content. Use POST /v1/audio/speech to convert text into speech files, while GET /v1/voices and GET /v1/models provide metadata about available voices and configuration options.

POST /v1/audio/speech

Send your text payload here to receive synthesized audio. This endpoint accepts JSON bodies with the model, input text, voice selection, and desired response format. It is the primary interface for generating narration for children's stories or educational content.

GET /v1/voices

Retrieve a list of available voice presets, their associated languages, and supported audio formats. This helps you select the right tone for your specific story, from warm narrators to energetic promo styles.

GET /v1/models

Check available model configurations, including tts-1 and tts-1-hd. Both use the same engine and price, so they do not differ in processing speed or output quality.

Endpoints

Request parameters

Sound wave illustration for: Request parameters

Configure your synthesis requests by specifying the model, input text, voice, and language. The API accepts standard parameters to ensure the generated audio matches your children's book or educational content requirements precisely.

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

Use "tts-1" or "tts-1-hd" for the model field. Both use the same engine and price ($0.01 per 1,000 characters). Choose based on your quality preference without worrying about cost differences.

Input text limit

The input field accepts up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer stories, split the text into chunks and join the resulting audio files.

Voice and language fields

Select one of the 8 voices (e.g., aria, nova, felix). Set the language parameter using an ISO code if the text is not English. The API guesses the language from the script if omitted, but explicit setting ensures accuracy for non-English Latin text.

Response formats

Sound wave illustration for: Response formats

The API returns binary audio data in the response body, with the format determined by your response_format parameter. Each generated file includes an inaudible watermark to identify it as synthetic speech, ensuring clear attribution for your children's content or educational materials.

MP3 audio data

MP3 is the default format, offering a balance of quality and file size. This makes it ideal for web delivery in interactive children's books, where bandwidth efficiency matters for smooth playback on various devices.

WAV audio data

WAV provides uncompressed, high-fidelity audio. Use this format when integrating with professional audio editing tools or when your app requires lossless quality for educational narration, avoiding compression artifacts.

OPUS, FLAC, PCM options

OPUS offers efficient compression for storage-constrained environments. FLAC provides lossless compression for archival quality, while PCM delivers raw, uncompressed linear audio for immediate processing in custom audio pipelines.

Rate limits

Sound wave illustration for: Rate limits

The API enforces a limit of 60 requests per minute per active key. This cap applies to all synthesis endpoints, ensuring stable performance for startups generating audio for children's books or educational content without overwhelming the service during peak usage.

60 requests per minute

Each account holds a single active key. The 60 requests per minute limit resets continuously as time passes. If you exceed this threshold, subsequent requests will receive a 429 Too Many Requests error until the window slides forward.

10 requests before first top-up

New accounts start with a restricted rate limit of 10 requests per minute. This lower limit applies until you add your first top-up via USDT (TRC-20). Once the transfer is confirmed, the limit automatically increases to the standard 60 requests per minute.

Queue processing under load

Requests are processed sequentially. During high traffic, a request may wait in a queue before synthesis begins. Longer texts take more time to generate, roughly 25 characters per second, while short phrases may take a few seconds. Plan your integration to handle these delays gracefully.

Rate limits

Error handling

Sound wave illustration for: Error handling

When synthesis fails, the API returns a non-200 HTTP status code alongside a JSON object detailing the issue. Failed requests are free, and any charge is returned in full, ensuring you only pay for successful audio generation. This guarantees cost efficiency even when input texts exceed limits or voices are invalid.

HTTP status codes

The API uses standard HTTP status codes to indicate success or failure. A 200 OK response confirms the audio file is ready in the response body. Common errors include 400 Bad Request for invalid parameters and 429 Too Many Requests when exceeding the 60 requests per minute limit.

  • 200 OK: Successful synthesis
  • 400 Bad Request: Invalid model or voice
  • 429 Too Many Requests: Rate limit exceeded

JSON error bodies

All errors return a JSON object with an error key containing a message string. This message explains the specific cause, such as text exceeding 4096 characters or an unsupported language code. Parse this response to display user-friendly messages in your children's book app.

Retry logic

Implement exponential backoff for 429 errors. Since requests are processed sequentially, under load a request may wait in a queue. Retrying immediately after a 429 response is often unnecessary; wait a few seconds before attempting again to avoid overwhelming the queue.

Code examples

Sound wave illustration for: Code examples

Generate narration for children's books with a single API call. Use these examples to integrate voiceovers into your web platform or app quickly.

The code snippets below handle authentication and payload construction. They assume you have already obtained an API key from the dashboard.

Curl command example

Use this command to verify your key and test voice generation. Replace YOUR_API_KEY and YOUR_VOICE with your actual credentials.

  • curl -X POST https://api.playpg699.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Once upon a time...", "voice": "luna", "response_format": "mp3"}'

OpenAI SDK with base_url

The official OpenAI SDK works directly by changing the base URL. This allows you to use familiar methods for speech synthesis.

  • from openai import OpenAI client = OpenAI(base_url="https://api.playpg699.com/v1", api_key="YOUR_API_KEY") response = client.audio.speech.create( model="tts-1", voice="nova", input="The sun rose over the hill." )

Python integration

For full control, use the requests library. This method handles the audio binary data and saves it directly to a file.

  • import requests url = "https://api.playpg699.com/v1/audio/speech" headers = {"Authorization": "Bearer YOUR_API_KEY"} payload = {"model": "tts-1-hd", "voice": "atlas", "input": "Chapter 1: The Beginning"} response = requests.post(url, headers=headers, json=payload) open("audio.mp3", "wb").write(response.content)
Code examples

Advanced usage

Sound wave illustration for: Advanced usage

Optimize narration pacing and ensure correct linguistic output by adjusting speed and explicitly defining languages. The API accepts speed values from 0.25 to 4.0, allowing you to slow down complex educational content or accelerate simple story segments. While the system guesses the language from the script (defaulting to English for Latin text), you should always set the language parameter for non-English Latin scripts to ensure accurate pronunciation.

Speed adjustment

Set the speed parameter between 0.25 and 4.0 to control the narration pace. Faster speeds suit quick updates, while slower rates help listeners follow detailed instructions or fairy tale descriptions.

Language specification

Explicitly pass the ISO code for the language field to guarantee correct accent and grammar. This is essential for any Latin-script text that is not English, as the default guess may assume English pronunciation otherwise.

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

Splitting long texts

The API limits input to 4,096 characters per request. For longer children's books, split your text into chunks, send each via POST /v1/audio/speech, and join the resulting audio files in your app.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Craft enchanting digital fairy tales that ignite imaginations and inspire the next generation of dreamers.

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-python on GitHub
  3. FFmpeg documentation
  4. IETF RFC 7845: Ogg Opus
  5. LibriVox public-domain audiobooks
  6. Python documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. W3C WAI: making audio and video accessible
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. OpenAI API reference: create speech
  11. MDN: Web Speech API
  12. Tether (USDT)

More on this site