Frequently asked questions
What is a TTS API?
It is a cloud service that converts text into audio files via a POST request to /v1/audio/speech. You send JSON with text, voice, and format settings, then receive an audio file. It follows the OpenAI endpoint shape, allowing you to use standard HTTP libraries or the OpenAI SDK by adjusting the base URL.
How do I install the Python package?
Install the official OpenAI Python library using pip install openai. Since our API mirrors the OpenAI speech endpoint structure, you can use this existing package. Alternatively, use any standard HTTP client like requests to send JSON payloads to https://api.999sl.top/v1. No proprietary Python SDK is required for integration.
How do I authenticate in Python?
Pass your API key in the Authorization header as 'Bearer tts-...'. You obtain this key from your account dashboard at /get-api-key/. Each account has one active key; issuing a new one immediately invalidates the previous one. Include this header in every HTTP request to verify your identity and access billing.
How do I handle long texts?
Split input text into chunks of up to 4096 characters. Send each chunk as a separate request to the API. Then, join the resulting audio files programmatically. This ensures compliance with the character limit per request while allowing you to generate audio for longer lessons or documents efficiently.
Which voice is best for stories?
Q: Which voice is suitable for stories? A: Luna is described as a soft, storytelling voice, making it suitable for narratives. Aria is another option, characterized as a warm, clear narrator. Both are female presets available in the API. Select the voice parameter in your request body to match the tone of your educational material.
How do I set the language in Python?
Include the 'language' field in your JSON body with the ISO code, such as 'en' or 'de'. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly setting the language prevents incorrect voice selection and ensures accurate pronunciation.
How do I save the audio file?
The API returns the audio file directly in the response body. Use your HTTP library to write the response content to a file. Supported formats include mp3, wav, opus, flac, and pcm. Choose the format that best suits your classroom materials or edtech application requirements.
How do I handle errors in Python?
Check the HTTP status code and response body for error details. Failed requests are free, and charges are returned in full if synthesis fails. Implement retry logic for transient network issues. Monitor your balance and character usage to avoid unexpected interruptions during lesson generation workflows.
Can I run this in a Jupyter notebook?
Yes, you can use standard Python libraries like requests or openai within Jupyter. Send POST requests to the API endpoint and save the returned audio bytes to a file. This allows for interactive testing of voices, speeds, and formats directly in your notebook environment before deployment.
How do I monitor my usage?
Visit the /get-api-key/ page to view your balance, trial status, characters left, and usage history. The dashboard provides real-time data on your account. Since billing is per character, you can track costs directly by monitoring the character count of your requests.
Is Python 3.7+ required?
The OpenAI Python package supports Python 3.7+. Since we recommend using this package or standard HTTP libraries, Python 3.7+ is suitable. Ensure your environment supports the library version you choose for consistent JSON handling and API communication.
Do I need async for high volume?
Async is optional but helpful for high-volume scripts. Requests are processed sequentially, so under load, a request may wait in a queue. Using async libraries can manage concurrent requests efficiently without blocking your main thread, improving throughput for large lesson batches.
How do I calculate cost per lesson?
Cost is $0.01 per 1,000 characters, including spaces and punctuation. Count the characters in your text and divide by 100,000 to get the cost in dollars. Failed requests are free, so only successful syntheses incur charges. This allows precise budgeting for classroom materials.
Can I use this for commercial projects?
Yes, the API is available for any use case. Generated audio carries an inaudible watermark marking it as synthetic speech. Input text is not used for training. You can integrate the audio into commercial edtech tools, courses, or applications.
What if the API is down?
We do not provide an SLA or uptime guarantee. If the API is unavailable, requests will fail. Failed requests are free, so you are not charged for downtime. Contact support via email for assistance.
How do I update my API key?
Issue a new key from the /get-api-key/ dashboard page. The new key becomes active immediately, and the old one stops working at once. Update your Python scripts to use the new key. This ensures secure access management without needing to wait for key rotation.
Can I use this with Flask?
Yes, integrate the API into Flask routes by sending POST requests from your view functions. Use the requests library or openai package to generate audio. Return the audio file or a download link to the user. This allows seamless integration into web-based educational platforms.
How do I test my script?
Use the free trial credit of $0.50 (50,000 characters) when signing in with Google. Send small test requests with different voices and formats. Verify the audio output and check the response headers for character counts. This allows safe experimentation before scaling to full lessons.
What are common rate limit errors?
The limit is 60 requests per minute per key (10 before the first top-up). Exceeding this results in a 429 error. Implement exponential backoff in your Python script to retry after the limit resets. Monitor your usage to avoid interruptions during automated lesson generation.
How do I debug my request?
Check the JSON body for correct fields: model, input, voice, and response_format. Verify the Authorization header includes the correct Bearer token. Inspect the response status code and body for error messages. Ensure the text length is under 4096 characters and the language code is valid if specified.
Why Python for TTS?
Python is the standard for edtech development because it abstracts away network complexity, allowing teachers and indie developers to focus on curriculum content rather than HTTP headers. Our API accepts standard JSON payloads, meaning you can generate audio files with minimal boilerplate code.
The language’s dominance in data and education tools means libraries handle text splitting and format conversion natively. This reduces the effort required to build reliable classroom materials or integrate synthetic voice generation into existing lesson plans.
Ease of Integration
Connecting to the SonicLesson API requires only a few lines of code. You send text and receive an audio file without managing complex streaming protocols or WebSocket connections.
The simple request structure allows educators to prototype audio lessons quickly, testing different voices and speeds before committing to a final format for students.
- Direct JSON response handling
- Minimal dependency requirements
- Immediate audio file delivery
Large Library Ecosystem
Python’s extensive package index includes robust HTTP clients and audio processing tools. You can easily combine TTS output with text-to-image or translation libraries for comprehensive educational modules.
Libraries like requests and pydub simplify storing and manipulating the generated MP3 or WAV files locally without needing external services.
Scripting Simplicity
Scripts can run on any machine, from a classroom teacher’s laptop to a low-cost Raspberry Pi device used in edtech projects. No server maintenance is required.
The straightforward syntax makes it easy for non-engineers to modify scripts for specific classroom needs, such as adjusting speed for younger students or changing voices for different characters in a story.
Setup Requirements
Before writing code, you must secure your credentials. SonicLesson issues a single active tts-... key per account, which you can retrieve from the /get-api-key/ dashboard. This key authenticates every request sent to the API base https://api.999sl.top/v1. Since each key is tied to your billing balance, protecting it prevents unauthorized audio generation charges.
API Key Storage
Store your key in an environment variable or a .env file rather than hardcoding it in your scripts. This approach keeps credentials out of version control systems like Git, which is critical for indie developers sharing codebases with students or collaborators. You can regenerate a key at any time via the dashboard; the old key stops immediately, ensuring no lingering access if a leak occurs.
- Use
os.environ['TTS_API_KEY']for clean access. - Add
.envto your.gitignorefile. - Regenerate keys instantly via the /get-api-key/ page.
First Script
The API accepts standard JSON bodies, making it straightforward to call from Python using the requests library or the official OpenAI SDK with a custom base URL. You simply send your text payload to the /v1/audio/speech endpoint and receive the audio file directly in the response.
This approach removes the need for complex webhooks or polling mechanisms, allowing you to integrate synthetic voice generation directly into your classroom materials or edtech scripts with minimal code overhead.
Run Script
To get started, install the requests package via pip. You will need to import the library and set your API key in the header. The request body requires the model, input, and voice fields, adhering to the 4096-character limit per request.
- Install library:
pip install requests - Set header:
Authorization: Bearer YOUR_KEY - Send POST to
/v1/audio/speech
Handling Long Texts
The API enforces a strict 4,096-character limit per request. For longer classroom materials or edtech scripts, you must split the input text into chunks and join the resulting audio files sequentially. This ensures reliable delivery without hitting endpoint constraints.
Under load, requests may queue, so your script should handle timeouts gracefully. Always verify the HTTP status code before saving the file, ensuring that failed synthesis attempts do not corrupt your final audio compilation.
Error Recovery
Implement retry logic with exponential backoff for transient network errors. Since requests are processed sequentially, a temporary queue delay might cause a timeout. Catching these errors prevents your integration from crashing mid-generation.
Always check for a 200 OK response before writing the binary data to disk. If the API returns an error, the request is free, so you can safely retry or split the text further without incurring extra costs.
- Retry on 429 (Rate Limit) with a 5-second delay
- Log specific HTTP status codes for debugging
- Discard partial files if the connection drops unexpectedly
Voice Selection
Choosing the right voice is critical when generating audio for classroom materials or educational news segments. Our API offers eight distinct presets, each designed for specific tonal requirements. For educators creating daily briefings or factual reports, selecting a voice with a neutral, authoritative tone ensures the content remains clear and engaging without distracting listeners with excessive emotion or flair.
Male Voices for News
For news-style content, Atlas provides a neutral tone ideal for factual reporting, while Orion offers a deeper, documentary-style voice suitable for longer educational narratives. Both voices handle complex sentence structures well, making them reliable choices for reading textbooks or current events. You can test these presets directly via the /v1/voices endpoint to hear their distinct characteristics before committing to a script.
- Atlas: Neutral, news-ready tone for factual accuracy
- Orion: Deep, documentary style for narrative depth
- Felix: Energetic option for promotional educational content
- Milo: Friendly, conversational tone for interactive lessons
Language Detection
The API guesses language from script by default, defaulting to English for Latin text. However, relying on auto-detection can misidentify languages with shared scripts, such as distinguishing between English and German or Dutch without explicit cues.
For reliable results, always set the language parameter explicitly. This prevents misinterpretation of polyglot texts or ambiguous character sets, ensuring the correct voice model applies the proper phonetic rules.
Edge Cases
Mixed-language paragraphs pose a specific challenge. Since the API processes up to 4096 characters per request, a single chunk containing both English and Japanese text may yield inconsistent pronunciation if the language is not locked. You must set the language ISO code to the dominant script or split the text manually before sending the request.
Another edge case involves punctuation-heavy technical text. If the input contains many Latin characters but represents a non-English language (e.g., Russian text using Latin transliteration), the default English guess will produce an unnatural accent. Explicitly defining the language code resolves this ambiguity immediately.
- Always specify
languagefor non-English Latin texts - Split mixed-script content before sending to the API
- Verify output audio for polyglot educational materials
Audio Quality
Audio quality and file size depend heavily on the format you select. MP3 is the default choice for most educational tools, offering a good balance between clarity and storage efficiency. WAV files are uncompressed and significantly larger, while FLAC provides lossless compression at a moderate size increase.
The speed setting also influences file duration. Faster speeds reduce file size but may affect intelligibility for language learners. Choose your format based on whether you prioritize streaming bandwidth or archival fidelity.
File Size
For a standard 4096-character request, an MP3 file typically ranges from 100KB to 500KB depending on speed and voice complexity. WAV files for the same text can exceed 5MB. FLAC: ~2-3MB per 4096 chars
PCM files are even larger, suitable only for immediate processing. Use MP3 for web delivery and WAV for high-quality classroom recordings where storage space is not a constraint.
- MP3: Best for web and mobile apps.
- WAV: High quality, large files.
- FLAC: Lossless, moderate size.
- PCM: Raw data, largest size.

Cost Optimization
Tracking your character consumption is essential for budgeting in educational projects. Since pricing is flat at $0.01 per 1,000 characters, even small scripts can accumulate costs if run repeatedly during testing. Keeping a close eye on usage prevents unexpected charges on your TRC-20 balance.
The dashboard on /get-api-key/ provides real-time visibility into your current balance, characters remaining, and historical usage. This transparency allows indie developers and teachers to predict costs accurately before scaling their classroom materials or edtech tools.
Monitoring Usage
Regularly check the usage metrics to ensure your text-splitting logic doesn’t generate redundant requests. Failed requests are free, but successful ones consume your credit. By monitoring the character count against your budget, you can adjust the input length or frequency of calls to stay within your financial limits without interrupting service.
- Check the /get-api-key/ dashboard for real-time balance updates.
- Monitor character counts to avoid over-spending on long lesson plans.
- Review request history to identify inefficient API calls.
Common Pitfalls
Python scripts connecting to the TTS endpoint often fail silently or hang when the network is unstable. Since requests are processed sequentially, a dropped connection can leave your application waiting indefinitely without an explicit timeout.
Configure your HTTP client with reasonable timeout values to prevent your script from blocking during peak usage hours. This ensures your application remains responsive even if the API queue is temporarily full.
Network Errors
Implement retry logic with exponential backoff for transient failures. This handles brief network interruptions without overwhelming the server. Always check the HTTP status code to distinguish between a timeout and a server error.
Log the specific error message returned by the API. This helps identify if the issue is related to rate limits (429) or authentication (401) versus a pure network drop.
- Set a connect timeout of 5 seconds and a read timeout of 30 seconds.
- Retry on 500/502/503 errors, but not on 400/401 errors.
- Log the request ID if provided in the response headers.
Best Practices
Secure your API key like a password. Store it in environment variables rather than hardcoding it in your scripts, especially when sharing code with students or open-sourcing projects. This prevents accidental exposure if your repository becomes public.
Use simple library wrappers or built-in os.environ access to keep credentials out of version control. This small habit ensures that your billing token remains safe while you focus on building educational content.
Security
Keep your tts-... key in an environment variable. Avoid committing it to Git, especially in classroom projects shared on GitHub. Use os.environ.get('TTS_API_KEY') to retrieve it safely at runtime.
Rotate your key regularly from the dashboard. If a key is compromised, issuing a new one immediately invalidates the old one, stopping any unauthorized usage before it impacts your balance.
- Store keys in
.envfiles, not in code. - Rotate keys via the dashboard if leaked.
- Use HTTPS for all API requests by default.
Example Use Case
Educators can automate the creation of audio reading materials for diverse classrooms. By sending student essays or lesson texts to the API, teachers generate audio files, supporting auditory learners without manual recording.
The process handles up to 4096 characters per request, allowing for substantial reading passages. With voices like Sage for instructional content or Luna for storytelling, the output provides clear synthetic speech for independent study time.
Student Engagement
Teachers often struggle to provide accessible audio versions of varied texts for students with reading difficulties or visual impairments. SonicLesson’s API simplifies this by converting any text input into speech.
By integrating the API into lesson plans, educators can offer multiple voice options. For example, using the Nova voice for upbeat reading exercises or Aria for calm narration helps maintain student interest and improves comprehension through multimodal learning.
- Convert textbook chapters to audio in minutes
- Support auditory learners with clear narration
- Customize tone for different reading levels
- Easy Python integration for school portals
Next Steps
You have successfully integrated the SonicLesson API into your Python workflow, handling everything from voice selection to long-text splitting. With your key active and your first audio files generated, you are ready to move from testing to production-grade deployment in your edtech tools or classroom materials.
Join Community
While we do not offer live chat or phone support, you can stay updated on API changes and share your Python integration tips with other developers and educators through our contact page. We encourage you to reach out with specific questions about billing, character limits, or voice presets via email.
Keep your API key secure and monitor your usage through the dashboard at /get-api-key/. As you scale your projects, remember that longer texts are split automatically, so you can focus on content quality rather than chunking logic.
- Contact us for technical or billing questions
- Check the /docs/ page for updated endpoint details
- Monitor your balance and character usage in real-time
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. The language’s dominance in data and education tools means libraries handle text splitting and format conversion natively.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- curl documentation
- TRON developer hub: TRC-20
- LibriVox public-domain audiobooks
- W3C WAI: making audio and video accessible
- LibriTTS-R corpus (OpenSLR 141)
- Node.js documentation
- MDN: Web Speech API
- openai-node on GitHub
- FFmpeg documentation
- OpenAI API reference: create speech
