ClipSpeak: Cloud Text-to-Speech API for Developers

By ClipSpeak editorial team · Updated 2026-11-18

This page provides the technical documentation for the ClipSpeak text-to-speech API, designed for developers integrating synthetic voiceovers into automated content pipelines for TikTok, Reels, and Shorts. You will find precise specifications for endpoints, parameters, and authentication methods required to generate audio files via standard HTTP requests.

The documentation details the request structure, supported voices, and rate limits to ensure reliable integration. Examples are provided for cURL, Python, and JavaScript, enabling developers to quickly implement the API. All technical details reflect the current capabilities of the ClipSpeak service without requiring external dependencies or custom SDKs.

ClipSpeak: Cloud Text-to-Speech API for Developers

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playa001.com/v1. You can verify available models and voices by sending a GET request to https://api.playa001.com/v1/voices or https://api.playa001.com/v1/models. All audio synthesis requests use the POST endpoint at https://api.playa001.com/v1/audio/speech with a JSON body containing your text and parameters.

How do I get an API key?

Sign up at https://playa001.com/get-api-key/ using Google or an email and password combination. Once registered, your account page displays your active API key, starting with 'tts-'. Accounts created via Google receive a $0.50 free trial valid for seven days. Email-based accounts start without trial credit.

Does the API support streaming?

No, the API does not support streaming, WebSockets, or real-time partial audio delivery. The endpoint returns the complete audio file in the response body after synthesis finishes. You must wait for the full response before processing or playing the audio file in your application.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base URL to https://api.playa001.com/v1. Use your ClipSpeak API key for authentication. The request shape matches the OpenAI speech endpoint, allowing you to use standard SDK methods without modifying the core logic of your integration code.

What is the maximum text length?

Each request supports a maximum of 4096 characters in the input field. For longer texts, split the content into parts of up to 4096 characters, generate audio for each part, and join the resulting audio files. Spaces and punctuation count toward this character limit.

How do I set the language?

Include the 'language' field with an ISO code in your request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script text to ensure accurate synthesis and voice selection.

What audio formats are available?

The API supports five audio formats: mp3, wav, opus, flac, and pcm. Specify your preferred format in the 'response_format' field of the request body. All generated files include an inaudible watermark to mark them as synthetic speech, ensuring clear identification of the audio source.

How fast is the generation?

Generation speed is roughly real-time, averaging about 25 characters of text per second of audio. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue before synthesis begins, potentially increasing total latency.

What happens if I exceed rate limits?

The rate limit is 60 requests per minute per key, or 10 per minute before the first top-up. Exceeding this limit will likely result in temporary delays or errors until the quota resets. Failed requests do not consume your character balance or incur charges.

Can I change the API key?

Yes, you can issue a new API key at any time from your account dashboard. When a new key is generated, the old key stops working immediately. You must update your applications to use the new key to maintain uninterrupted service for your API requests.

Is there an SDK for other languages?

We do not provide an official SDK for other languages. You can use the official OpenAI SDKs by adjusting the base URL, or use plain HTTP requests for any programming language. The API follows a standard JSON structure compatible with most modern HTTP client libraries.

How do I handle errors?

Failed requests are free, and the charge is returned in full if synthesis fails. Monitor your HTTP response status codes to detect errors. Check the request body for valid parameters like model, voice, and format. Ensure your API key is active and has sufficient balance.

First request

curl

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

Authentication is handled via the Authorization header using a Bearer token. This key is unique to each account and must be included in every request to the API base URL.

Keys are issued upon account creation. You can generate a new key at any time via the dashboard; the previous key becomes invalid immediately upon issuance, ensuring precise control over access.

API Key Header

Include your key in the HTTP header: Authorization: Bearer tts-.... This standard format allows the official OpenAI SDKs to work by simply adjusting the base URL.

Key Management

Each account holds one active key. Issuing a replacement revokes the old key instantly. Use the dashboard to view and regenerate keys as needed.

  • Single active key per account
  • Instant invalidation of old keys
  • Regenerate via dashboard

Security

The key is the sole credential for API access. Keep it secure in your environment variables. Lost keys can be replaced immediately without affecting your balance.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The core synthesis function is exposed via a single HTTP endpoint. Send a POST request to https://api.playa001.com/v1/audio/speech with your JSON payload. The API processes the text and returns the generated audio file directly in the response body.

POST Request

Direct all synthesis requests to the specified endpoint. Ensure your client sends the correct content type header. The endpoint accepts standard JSON bodies containing the model, input text, voice selection, and optional parameters like speed and language.

JSON Body

Structure your payload with required fields: model (tts-1 or tts-1-hd), input (up to 4096 characters), and voice. Include response_format and speed as needed. The API validates character counts and voice existence before processing.

  • model: tts-1 or tts-1-hd
  • input: string, max 4096 chars
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, or pcm

Response Format

On success, the response contains the raw audio data in the requested format. Failed requests return an error object with a descriptive message. Audio files are generated synchronously; for longer texts, split input into chunks under the character limit.

Speech Endpoint

Voices Endpoint

Sound wave illustration for: Voices Endpoint

The /v1/voices endpoint provides a complete inventory of available voice presets, allowing developers to integrate the correct audio profiles into their content pipelines. This endpoint returns metadata for all eight presets, enabling dynamic selection based on the target platform or video style.

GET Request

Send a simple GET request to https://api.playa001.com/v1/voices. The response includes all available voice identifiers, their associated languages, and supported audio formats. This data is static per model version, ensuring consistent integration behavior.

List Voices

The API returns eight distinct voice presets: Aria, Nova, Luna, and Sage (female); Felix, Milo, Atlas, and Orion (male). Each voice is designed for specific tonal requirements, from upbeat promo to calm instructional content, all supporting the full range of 23 languages.

  • Aria: Warm, clear narrator
  • Felix: Energetic, promo
  • Atlas: Neutral, news
  • Orion: Deep, documentary

Language Support

All voices support 23 languages, including Arabic, Chinese, English, German, Japanese, and Spanish. The system guesses the language from Latin script by default (English), but you must explicitly set the language parameter for non-English Latin text. Vietnamese and Thai are not supported.

Models and Formats

Sound wave illustration for: Models and Formats

ClipSpeak offers two model variants, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. Both models accept identical request parameters and support the full range of eight voice presets across 23 languages. The distinction lies solely in the audio fidelity; both models use the same engine and price.

tts-1 vs tts-1-hd

Although both models share the same price point of $10 per 1 million characters, creators should select based on their output requirements. The audio quality difference is measurable in spectral detail but does not affect character limits or speed constraints. Since both use the same engine, latency characteristics are consistent regardless of the model chosen.

  • Same engine and $0.01 per 1,000 character price
  • Identical parameter support and voice availability
  • tts-1-hd offers enhanced spectral fidelity

Audio Formats

The API supports five distinct audio formats: mp3, wav, opus, flac, and pcm. Each format serves different integration needs within your content creation workflow. MP3 is standard for web playback, while WAV and FLAC provide lossless options for editing. OPUS offers efficient compression, and PCM provides raw uncompressed data.

  • mp3: Standard compressed audio for web delivery
  • wav: Lossless format for editing workflows
  • opus: Efficient compression for streaming
  • flac: Lossless format
  • pcm: Raw uncompressed audio data

Format Selection

Specify the desired format using the response_format field in your JSON body. The choice does not affect pricing or processing time. Select the format that best integrates with your video editing software or content delivery pipeline. All generated audio files include an inaudible watermark to identify them as synthetic speech.

Request Parameters

Sound wave illustration for: Request Parameters

Configure synthesis parameters to match content style. The API accepts up to 4096 characters per request, with spaces and punctuation counted toward the limit. Longer texts require client-side splitting and audio joining.

Input Text

Send the script via the input field. The system processes text sequentially, taking a few seconds for short phrases and roughly real-time for longer segments. Ensure the text fits within the 4096-character constraint to avoid truncation.

  • Maximum 4096 characters per request
  • Spaces and punctuation count as characters
  • Client-side splitting required for longer scripts

Voice Selection

Choose from eight presets optimized for video content. Each voice supports all 23 listed languages. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text.

  • 8 distinct voice presets
  • Supports 23 languages
  • Language detection defaults to English for Latin script

Speed Control

Adjust the playback speed using the speed parameter. Values range from 0.25 to 4.0, allowing precise synchronization with video cuts.

  • Range: 0.25 to 4.0
  • Adjustable for video synchronization
  • Higher speeds may impact audio clarity
Request Parameters

Rate Limits

Sound wave illustration for: Rate Limits

ClipSpeak enforces a strict rate limit of 60 requests per minute per API key. This limit applies to all endpoints and ensures stable performance for automated content pipelines. Before your first top-up, the limit is reduced to 10 requests per minute.

Requests Per Minute

Each API key allows a maximum of 60 requests per minute. This cap is consistent across all usage types, including free trial credits. Requests are processed sequentially, meaning high-volume bursts may queue behind previous requests.

  • Standard limit: 60 requests/minute
  • Pre-top-up limit: 10 requests/minute
  • Applied per API key

Queue Handling

Requests are processed one after another. If you exceed the per-minute limit, subsequent requests enter a queue. Processing time depends on text length, typically generating about 25 characters of audio per second.

Limit Exceeded

When the limit is exceeded, new requests wait in the queue until capacity frees up. No data is lost during queuing. Once the minute resets, queued requests are processed in order.

Error Handling

Sound wave illustration for: Error Handling

Synthetic audio generation is subject to specific failure conditions. Failed requests incur no charge, with the cost returned in full to your balance. This ensures that transient network issues or invalid parameters do not result in financial loss.

Common Errors

Errors typically stem from exceeding the 4096-character input limit or providing an invalid voice ID. The API also rejects requests with malformed JSON or missing required fields like model and input.

  • Invalid JSON structure
  • Character limit exceeded (4096 chars)
  • Unknown voice identifier

Status Codes

The API returns standard HTTP status codes. A 200 OK indicates successful synthesis. Use 400 Bad Request for parameter validation failures and 401 Unauthorized for invalid API keys.

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 429: Too Many Requests

Retry Logic

Implement exponential backoff for transient errors. If a request fails due to server overload, wait briefly before retrying. Since requests are processed sequentially, under-load queues may cause delays, but failed requests remain free.

Error Handling

Code Examples

Sound wave illustration for: Code Examples

The API accepts standard HTTP requests, allowing immediate integration into existing automation pipelines for TikTok and Shorts production. Developers can verify connectivity and generate audio files using minimal code snippets across popular languages.

Each example demonstrates the required authentication header, model selection, and voice parameters to ensure consistent, copyright-safe voiceovers for short-form video content.

cURL Example

Send a POST request with your Bearer token to generate MP3 audio instantly.

`curl -X POST https://api.playa001.com/v1/audio/speech \ -H "Authorization: Bearer tts-your-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "aria", "response_format": "mp3"}'`

Python SDK

Use the official OpenAI Python library by overriding the base URL to point to ClipSpeak’s endpoint.

`import openai client = openai.OpenAI(api_key='tts-your-key', base_url='https://api.playa001.com/v1') response = client.audio.speech.create(model='tts-1', voice='nova', input='Demo text', response_format='wav')`

JavaScript Fetch

Implement synchronous speech generation using standard fetch APIs within Node.js or browser environments.

`const res = await fetch('https://api.playa001.com/v1/audio/speech', { method: 'POST', headers: { 'Authorization': 'Bearer tts-your-key', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'tts-1-hd', voice: 'felix', input: 'Promo script', response_format: 'mp3' }) });`

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Selecting the correct voice ensures consistent audio branding across TikTok, Reels, and Shorts videos.

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. OpenAI API reference: create speech
  4. LibriVox public-domain audiobooks
  5. IETF RFC 7845: Ogg Opus
  6. LibriTTS-R corpus (OpenSLR 141)
  7. FFmpeg documentation
  8. Node.js documentation
  9. Creative Commons Attribution 4.0
  10. curl documentation
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. MDN: Web Speech API

More on this site