Frequently asked questions
What is the API endpoint?
Send a POST request to https://api.playsc8.com/v1/audio/speech. The JSON body accepts model, input, voice, response_format, speed, and optional language parameters. This endpoint returns the generated audio file directly in the response, allowing you to integrate TTS into your application with a simple HTTP call.
How do I authenticate?
Include your API key in the request header as Authorization: Bearer tts-... You receive one active key per account. If you generate a new key, the previous one stops working immediately. Ensure your key is valid before sending requests to avoid authentication errors.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playsc8.com/v1 and using your site's key. The request shape matches the OpenAI speech endpoint, allowing you to use familiar libraries without rewriting your integration logic for this specific API.
What models are available?
You can choose between tts-1 and tts-1-hd. Both models use the same engine and pricing. Select the model that fits your requirements, keeping in mind that both deliver speech for your text-to-speech generation tasks.
How do I set the language?
Pass an optional ISO language code in the request body. 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 pronunciation and synthesis results.
What voices are supported?
Eight presets are available: aria, nova, luna, sage, felix, milo, atlas, and orion. Each voice can speak any of the 23 supported languages. Choose the voice that matches your content’s tone, from warm narrators to neutral news readers.
What formats are supported?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format in the response_format field. This flexibility allows you to integrate the audio directly into your existing media pipelines or player infrastructure without additional conversion.
What are the rate limits?
The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Monitor your usage to avoid throttling. The limit increases to 60 requests per minute once you add credit.
What happens if I exceed limits?
Requests are processed sequentially, so exceeding limits may cause your request to wait in a queue. If synthesis fails, the charge is returned in full. You do not lose credit for failed attempts, but you may experience latency during high load.
How do I handle errors?
Check the HTTP status code and response body for error details. Failed requests are free, with charges returned in full. Ensure your input text is under 4096 characters and your key is valid. Review the documentation for specific error codes and resolutions.
Is the response streaming?
No, the API does not support streaming or WebSocket connections. You receive the complete audio file in the response after generation. For real-time needs, you may need to implement client-side buffering or pre-generate audio files for your content.
Can I send long texts?
Each request supports up to 4096 characters. For longer texts, split the input into parts, generate audio for each, and join the files. This approach ensures compatibility with the API limits while allowing you to create full-length audio content.
How do I rotate my API key?
Generate a new key from your account dashboard. The old key stops working immediately upon issuing the new one. Update your application configuration to use the new key to maintain uninterrupted service. You can issue a new key at any time.
Where do I find my API key?
Sign up at /get-api-key/ using Google or email. Your key, balance, and usage details are displayed on that page. Keep your key secure and include it in the Authorization header for all API requests to authenticate your account.
First request
curl
curl https://api.playsc8.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playsc8.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.playsc8.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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication and API Key
To start using the Spanish Text Reader API, you need an API key. Create your account at https://playsc8.com/get-api-key/ using Google or an email address. Once signed in, your dashboard displays your active key, current balance, and usage statistics.
Get your key from dashboard
Your key appears immediately after sign-up. You can copy it directly from the dashboard interface. Keep it secure, as it authorizes all your API requests.
- Access key at https://playsc8.com/get-api-key/
- Supported sign-up via Google or email/password
Bearer token format
Include your key in the HTTP header for every request. Use the format: Authorization: Bearer tts-.... This ensures your usage is tracked correctly against your balance.
Key rotation policy
You can issue a new key at any time from the dashboard. When you generate a new key, the previous one stops working immediately. This allows you to revoke access without delay if needed.
- Issue new keys instantly
- Old keys stop at once
First Request with cURL
Send a POST request to https://api.playsc8.com/v1/audio/speech with your Bearer token in the Authorization header. The API accepts JSON and returns an audio file directly, making it easy to integrate into your accessibility workflows.
This quickstart demonstrates the simplest integration using cURL, allowing you to verify connectivity and format handling before building your application logic.
Basic JSON body
Include the model, input text, voice, and response format in your JSON payload. For example, generate a narration using the nova voice in MP3 format, ensuring the text stays within the 4096-character limit per request.
The API processes the text sequentially, so long documents should be split into chunks. Each chunk returns a separate audio file that you can join later.
Required fields
You must provide model ("tts-1" or "tts-1-hd"), input (your text string), voice (one of the 8 presets), and response_format (mp3, wav, opus, flac, or pcm).
Set the Authorization header to Bearer your-api-key. If the language is not obvious from the script, explicitly set the language field to "es" for Spanish to ensure accurate pronunciation.
Response structure
On success, the API returns the audio file directly in the response body with the appropriate content-type header (e.g., audio/mpeg).
If synthesis fails, you receive an error JSON object, and the charge is refunded in full. Check the status code and message to debug issues like invalid characters or rate limits.
Using the OpenAI SDK
Integrate ClearRead into your existing Python or Node.js apps by simply overriding the API base URL. Point your OpenAI SDK client to https://api.playsc8.com/v1 instead of OpenAI’s endpoint. This allows you to keep your familiar code structure while leveraging our text-to-speech engine.
The request shape remains identical to the standard OpenAI speech endpoint. You send a JSON payload with the model, input text, voice selection, and response format. The SDK handles the serialization and HTTP transport, requiring minimal code changes.
Change base_url
Update your SDK client configuration to direct requests to our API gateway. Set the base URL to https://api.playsc8.com/v1. This single change routes your standard speech generation calls through our infrastructure, maintaining compatibility with all official OpenAI SDKs.
- Base URL: https://api.playsc8.com/v1
- Works with official OpenAI Python and Node.js SDKs
- No custom client library required
Same request shape
Use the standard JSON body structure with fields like model, input, voice, and response_format. The API accepts the same parameters as the OpenAI speech endpoint, ensuring a drop-in replacement for existing integrations. You can specify tts-1 or tts-1-hd models with identical behavior.
- Standard JSON payload
- Fields: model, input, voice, response_format, speed
- Compatible with existing OpenAI request patterns
Official SDK compatibility
Leverage the robust error handling and retry logic of the official OpenAI SDKs. Since the request and response schemas match, you can use the same authentication headers and client instances. Just ensure you inject your ClearRead API key in the standard Authorization header.
- No new learning curve
- Standard Bearer token auth
- Familiar client behavior
Supported Audio Formats
The API returns audio in five standard formats: mp3, wav, opus, flac, and pcm. Choose the format that best fits your player’s capabilities or your storage constraints. All formats support the same 8 voice presets and speed settings.
MP3, WAV, Opus, FLAC, PCM
MP3 is a widely compatible choice for web players. WAV offers uncompressed quality for local storage. Opus provides efficient compression for mobile data. FLAC ensures lossless archival. PCM delivers raw data for custom processing pipelines.
Format selection field
Set the response_format field in your JSON request body. The API ignores unsupported formats and returns an error. You can switch formats without changing your voice or speed settings.
- Use
mp3for broad compatibility. - Use
wavfor simple playback testing. - Use
opusto reduce bandwidth costs.
Quality variations
All formats deliver the same synthetic speech quality. The difference lies only in file size and decoding requirements. Opus files are typically smallest, while WAV and FLAC are larger.
Voice Selection and Language
ClearRead’s API supports 23 languages, including Spanish, with eight distinct voice presets. Each voice is a preset based on licensed recordings, suitable for accessibility and language learning workflows. You can choose from female voices like Aria or Nova, or male voices like Felix or Atlas, depending on your content’s tone.
8 voice presets
Select a voice that matches your audience’s needs. Our presets range from warm narrators to energetic promo voices, all generated from licensed recordings. Every audio file includes an inaudible watermark to identify synthetic speech.
- Aria: warm, clear narrator
- Felix: energetic, promo
- Atlas: neutral, news
- Orion: deep, documentary
Language detection
The API automatically detects the language from the input text. For Latin-script text, it defaults to English if no language is specified. This works well for English, but non-English Latin scripts may require explicit settings.
Explicit language setting
To ensure accurate pronunciation for Spanish or other supported languages, always set the language field to the ISO code (e.g., es). This prevents misinterpretation and ensures the selected voice speaks clearly in the correct language.
Rate Limits and Queues
Each API key is limited to 60 requests per minute. New accounts start with a stricter limit of 10 requests per minute until the first top-up is processed. This ensures stable performance while you integrate the text reader into your accessibility workflow.
60 requests per minute
The rate limit applies per key, not per IP or project. If you exceed 60 requests in a minute, the API returns a 429 status code. You can monitor your usage directly in the dashboard to plan your batching strategy effectively.
- Limit: 60 requests/minute per key
- New accounts: 10 requests/minute initially
- Limit resets every 60 seconds
Queue behavior
Requests are processed sequentially during high load. Short phrases may take a few seconds to generate, while longer texts are split into parts. If the queue is busy, your request waits in line rather than failing immediately. This ensures every character is processed accurately.
- Requests are queued, not dropped
- Processing is sequential under load
- Long texts are split automatically
Retry strategy
Implement exponential backoff for 429 errors. Start with a short delay and increase it gradually. Avoid sending rapid retries, as they will just re-enter the queue. If a request fails completely, you are refunded automatically, so retrying is safe.
- Use exponential backoff for 429 errors
- Wait before retrying to avoid queue congestion
- Failed requests are refunded automatically
Error Handling and Codes
Understanding error responses helps you maintain smooth audio delivery for your users. When synthesis fails, the charge is returned in full.
Use the provided error codes to quickly identify issues and adjust your integration strategy accordingly.
Common error codes
We return standard HTTP status codes to indicate the result of your request. A 200 OK means the audio file is ready in the response body. Common errors include 400 Bad Request for invalid parameters, 401 Unauthorized if your API key is missing or incorrect, and 429 Too Many Requests when you exceed the rate limit.
Failure refund policy
If a synthesis request fails due to server-side issues or invalid input that prevents audio generation, the charge is returned in full. You only pay for successfully generated audio files. This ensures that temporary glitches do not impact your character credit balance unexpectedly.
Debugging tips
Always check the response body for a JSON object containing an error message. Verify that your text input stays within the 4096-character limit. Ensure your API key is correctly formatted as a Bearer token in the Authorization header. If issues persist, contact support via email.
Endpoint Reference
The API exposes three primary endpoints for managing speech synthesis and discovery. The core POST /v1/audio/speech endpoint converts text into audio, while GET /v1/voices and GET /v1/models provide metadata for configuration without consuming credits.
POST /v1/audio/speech
Send a JSON payload with model, input, and voice to receive an audio file. Supports mp3, wav, opus, flac, and pcm formats. Text input is limited to 4,096 characters per request.
Use the speed parameter (0.25–4.0) to adjust playback rate. The language field is optional but recommended for non-English Latin text to ensure correct pronunciation.
- Maximum input: 4,096 characters
- Models: tts-1, tts-1-hd
- Formats: mp3, wav, opus, flac, pcm
GET /v1/voices
Returns a list of available voice presets (e.g., aria, nova, felix) along with supported languages and formats. This endpoint helps you verify which voices support specific languages like Spanish or Arabic.
- Returns voice ID, name, and metadata
- Lists supported languages and formats
- No character limit applied
GET /v1/models
Lists available models (tts-1 and tts-1-hd). Both models share the same engine and pricing structure, allowing you to choose based on your preference without changing integration logic.
- Returns model ID and name
- Includes pricing metadata
- Static configuration list
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.