SpokenWave Text-to-Speech API: Integration Guide for Developers

By SpokenWave editorial team · Updated 2026-11-18

This guide provides the technical specifications for integrating SpokenWave’s text-to-speech API into your advertising and radio spot production workflows. You will find precise details on authentication, endpoint structures, and parameter configurations required to convert text into audio files via a standard REST interface.

Developers targeting startup environments will learn how to configure the OpenAI-compatible SDK, manage API keys, and handle rate limits. The documentation covers model selection, voice presets, and output formats to ensure seamless automation of audio generation for your campaigns.

SpokenWave Text-to-Speech API: Integration Guide for Developers

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. The dashboard displays your active API key, which starts with 'tts-'. You can issue a new key at any time, causing the previous one to stop immediately.

What is the base URL for the API?

The API base URL is https://api.playgo90.com/v1. You send POST requests to https://api.playgo90.com/v1/audio/speech. Other endpoints like /v1/voices and /v1/models are also available under this base path.

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.playgo90.com/v1 and providing your SpokenWave API key for authentication.

What are the rate limits?

You are limited to 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays.

How do I handle errors?

Failed requests are free, and the charge is returned in full. You should check the HTTP status code and response body for error details. Implement retry logic for transient failures, keeping rate limits in mind.

What models are available?

Two models are available: 'tts-1' and 'tts-1-hd'. Both use the same engine and pricing. You can list all available models by sending a GET request to /v1/models.

Can I change the voice speed?

Yes. The 'speed' parameter accepts values between 0.25 and 4.0. This allows you to adjust the playback speed of the generated audio to fit your specific advertising or radio spot requirements.

How do I specify a language?

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

What happens if a request fails?

If synthesis fails, the charge is returned in full. You are not billed for failed requests. Ensure your input text is within the 4096 character limit and your audio format is valid.

How do I rotate my API key?

You can issue a new API key from your account dashboard at any time. The new key becomes active immediately, and the old key stops working at once, ensuring secure access management.

Is the API RESTful?

Yes. The API uses standard HTTP methods. You POST to /v1/audio/speech for synthesis and GET /v1/voices or /v1/models for metadata. It follows standard REST conventions for request and response structures.

Can I stream audio?

No. The API returns the complete audio file in the response. There is no streaming, WebSocket, or real-time partial audio support. You receive the final file after synthesis completes.

Do I need to install extra libraries?

No. You can use the official OpenAI SDKs or plain HTTP requests. No proprietary SpokenWave SDK or extra libraries are required. Standard HTTP clients are sufficient for integration.

How do I test the API?

Use the curl example provided on the /get-api-key/ dashboard page. You can also use the free trial credit of $0.50 (valid for 7 days) to test synthesis without immediate payment.

First request

curl

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

Access the SpokenWave API by including your unique key in the request header. You generate this key on the /get-api-key/ dashboard after signing in with Google or an email account.

Each account maintains one active key at a time. Use the format Bearer tts-... to authenticate your requests securely.

API Key format

API Key format

Your API key is a string starting with "tts-" followed by alphanumeric characters. It is issued when you create an account on playgo90.com.

Bearer token

Bearer token

Include the header Authorization: Bearer <your_key> in every POST request to /v1/audio/speech. This authenticates the request against your account balance.

Key rotation

Issuing a new key immediately invalidates the old one. Only one key is active per account at any given time.

Endpoints

Sound wave illustration for: Endpoints

The SpokenWave API provides three core endpoints for integration. The speech generation endpoint accepts text and parameters to return audio files. The list voices endpoint returns available presets, languages, and formats. The list models endpoint returns available model identifiers.

Speech generation

Send a POST request to /v1/audio/speech with a JSON body containing model, input, voice, response_format, and optional speed or language. The API returns the audio file directly in the response body. Text is limited to 4096 characters per request.

  • Endpoint: POST /v1/audio/speech
  • Returns: Audio file (MP3, WAV, OPUS, FLAC, PCM)

List voices

Use GET /v1/voices to retrieve the full list of available voice presets. This endpoint also returns supported languages, audio formats, and current pricing information. Use this data to configure your application's voice selection interface.

  • Endpoint: GET /v1/voices
  • Returns: Voice presets, languages, formats, price

List models

Call GET /v1/models to retrieve available model identifiers. Both tts-1 and tts-1-hd use the same engine and price. This endpoint allows dynamic configuration of your integration based on available model versions.

  • Endpoint: GET /v1/models
  • Returns: Model identifiers (e.g., tts-1, tts-1-hd)

Request parameters

Sound wave illustration for: Request parameters

The API accepts a JSON body to generate audio. You must specify the model, input text, voice, and response format. The request is processed synchronously, returning the audio file directly in the response.

Model selection

Use "tts-1" or "tts-1-hd" for synthesis. Both models use the same engine and price structure ($10 per 1 million characters). There is no performance difference between them for standard advertising spots.

Input text limits

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

Voice selection

Select from eight presets such as "aria" (warm narrator) or "atlas" (neutral news). Each voice supports 23 languages. If the language is not set, it is guessed from the script.

Response formats

Sound wave illustration for: Response formats

The API returns synthesized audio files directly in the response body, allowing your application to process or store the output immediately. The format you choose depends on your downstream requirements for file size, quality, or compatibility with existing audio pipelines.

SpokenWave supports five distinct audio formats, ensuring compatibility with various advertising platforms and radio spot delivery systems without requiring additional conversion steps on your end.

MP3 output

MP3 is one of the supported response formats.

  • Default format for most integrations
  • Optimal balance of quality and file size
  • Broad compatibility with ad delivery platforms

WAV output

WAV provides uncompressed audio.

  • Uncompressed audio quality
  • Ideal for radio spot production
  • No data loss during synthesis

Other formats

SpokenWave also supports Opus, FLAC, and PCM formats to accommodate specific technical requirements. Opus and FLAC are supported formats. PCM delivers raw audio data.

  • Opus: efficient compression for web apps
  • FLAC: lossless compression for archiving
  • PCM: raw audio for specialized pipelines

Error handling

Sound wave illustration for: Error handling

Synthesis failures return a 4xx or 5xx status with a JSON error object. Common issues include invalid API keys, unsupported voice names, or text exceeding the 4096-character limit. Failed requests incur no charge, and the credit is returned immediately.

Common errors

Review the error message in the response body to identify the specific cause. Ensure the input text is within character limits and the voice exists in the /v1/voices list. Invalid models or formats will also trigger a 400 error.

Rate limits

Accounts are limited to 60 requests per minute per key. New accounts start with a 10 requests per minute limit until the first top-up is processed. Exceeding these limits returns a 429 status code, blocking further synthesis until the window resets.

  • 60 requests/minute after top-up
  • 10 requests/minute for new accounts
  • 429 status on limit breach

Retry logic

Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, queueing delays may occur under load. Retry after the specified Retry-After header duration if provided, or use a standard backoff strategy to avoid hammering the endpoint.

Error handling

SDK integration

Sound wave illustration for: SDK integration

The SpokenWave API follows the same request shape as the OpenAI speech endpoint, allowing teams to reuse existing integrations with minimal code changes. By updating the base URL and providing a valid Bearer token, your application can generate audio files directly without requiring a dedicated client library.

This approach is particularly efficient for startup engineering teams that need to integrate TTS into advertising workflows quickly. The standard HTTP library or any compatible SDK can handle the JSON body and return the audio file.

OpenAI SDK config

Configure the SDK by pointing the base URL to the SpokenWave API domain. Use the standard tts-1 or tts-1-hd model identifier. The authentication header must include your API key in the Authorization: Bearer <key> format.

  • - Base URL: https://api.playgo90.com/v1
  • - Model: tts-1 or tts-1-hd
  • - Auth: Bearer token required

Base URL change

Replace the default provider URL with https://api.playgo90.com/v1. This ensures all requests, including speech generation and voice listing, route to SpokenWave servers. The structure remains identical to the OpenAI standard, so no parameter mapping is needed.

Python example

```python import openai client = openai.OpenAI( base_url="https://api.playgo90.com/v1", api_key="tts-your-api-key-here" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Generate a radio spot for our new product." ) response.stream_to_file("output.mp3") ``` This script demonstrates a basic integration using the OpenAI Python SDK. Adjust the voice and input text as needed for your advertising campaign.

Rate limits

Sound wave illustration for: Rate limits

SpokenWave enforces a strict rate limit of 60 requests per minute per API key. This cap applies uniformly across all endpoints, ensuring stable service during high-volume advertising spot generation. Requests are processed sequentially, meaning concurrent bursts may queue briefly before synthesis begins.

Requests per minute

The standard limit is 60 requests per minute. Exceeding this threshold results in a 429 Too Many Requests error until the window resets.

  • Limit: 60 requests/minute/key
  • Processing: Sequential queue under load
  • Error: HTTP 429 on breach

New account limits

New accounts start with a reduced limit of 10 requests per minute. This applies until the first top-up is processed. This restriction ensures fair usage during the initial trial period, which provides $0.50 in credit valid for 7 days.

  • Initial rate: 10 requests/minute
  • Upgrade: After first top-up
  • Trial credit: $0.50 (7 days)

Top-up impact

Once your first top-up is confirmed via USDT (TRC-20), the rate limit increases immediately to the full 60 requests per minute. Balance does not expire, and limits are per key, not per account, allowing separate scaling for different projects.

  • Trigger: First USTRC-20 top-up
  • Result: Full 60 req/min
  • Scope: Per API key

Voice parameters

Sound wave illustration for: Voice parameters

The API allows precise control over speech characteristics through speed adjustment and language specification. Developers can tune generation parameters to match specific advertising or radio spot requirements, ensuring the output aligns with brand voice and timing constraints.

Speed control

Set the speed parameter between 0.25 and 4.0 to adjust playback rate. This allows acceleration for quick announcements or deceleration for clarity in instructional content. The default speed is 1.0.

Language code

Specify the language parameter using an ISO code (e.g., 'en', 'de', 'fr') to ensure correct pronunciation. If omitted, the system guesses the language, defaulting to English for Latin-script text. Explicitly setting the language is recommended for non-English content.

Voice presets

Choose from eight distinct voice presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each voice is designed for specific tones, from warm narration to energetic promo. All voices support all 23 available languages.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational
  • Atlas: Neutral, news
  • Orion: Deep, documentary

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Launch your startup with clarity, capturing attention instantly through compelling audio storytelling that resonates deeply with your target audience.

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. W3C WAI: making audio and video accessible
  3. LibriVox public-domain audiobooks
  4. ISO 639 language codes
  5. LibriTTS-R corpus (OpenSLR 141)
  6. Tether (USDT)
  7. Creative Commons Attribution 4.0
  8. OpenAI API reference: create speech
  9. openai-python on GitHub
  10. openai-node on GitHub
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. MDN: Web Speech API

More on this site