Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.ah777.info/v1. You use this endpoint for all requests, including speech synthesis and voice retrieval. This URL structure allows you to integrate SpotLogic’s text-to-speech capabilities directly into your existing workflows or custom applications without needing additional routing configuration.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work with SpotLogic. You simply change the base_url to https://api.ah777.info/v1 and use your SpotLogic API key. This compatibility allows agencies to leverage familiar SDK tools for making requests to our text-to-speech endpoint without learning a new library.
How do I pass the API key?
Pass your API key using the Authorization: Bearer tts-... header in your HTTP requests. Each account has one active key at a time. If you need a new key, you can issue one at any time, and the previous key stops immediately upon issuance.
What is the maximum text length?
The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, you must split the text into chunks of up to 4096 characters, generate audio for each, and join the resulting audio files manually.
Which models are available?
Two models are available: "tts-1" and "tts-1-hd". Both use the same engine and have identical pricing. You can choose either model based on your quality preferences, as the underlying voice synthesis technology remains consistent across both options for all supported voices and languages.
Can I stream the audio?
No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. There is no WebSocket or real-time partial audio delivery. You must wait for the full file to be generated and returned before playback can begin.
Does the API support SSML?
No, the API does not support SSML. You cannot use Speech Synthesis Markup Language to control pauses, emphasis, or pronunciation. Voice control is limited to the eight preset voices and the speed parameter. Custom pronunciation or fine-grained timing adjustments are not available through this endpoint.
How do I handle long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Once you receive the audio files for each chunk, join them together to create the final audio file. This ensures compliance with the character limit.
What is the speed range?
The speed parameter accepts values between 0.25 and 4.0. This allows you to slow down narration for clarity or speed up text for quick reads. The default speed is 1.0. Adjusting speed does not affect the voice characteristics or the language detection logic.
Do I need to specify the language?
It is optional but recommended for non-English Latin-script text. If not set, the language is guessed from the script, defaulting to English for Latin text. For accurate synthesis in languages like Arabic, Chinese, or Hindi, explicitly set the language field to the ISO code.
What happens if I hit the rate limit?
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. Exceeding the limit will result in errors; failed requests are free.
Are requests processed in parallel?
No, requests are processed one after another. Under load, a request may wait in a queue before synthesis begins. This sequential processing means that longer texts or high-volume bursts may take time to complete, as each request must finish before the next starts.
What audio formats are supported?
The API supports mp3, wav, opus, flac, and pcm formats. You can specify the desired response_format in your request body. Each generated file carries an inaudible watermark marking it as synthetic speech. The format choice affects file size and compatibility.
How do I authenticate requests?
Authenticate using the Authorization: Bearer header followed by your API key (e.g., Bearer tts-...). You obtain this key when you sign up on the /get-api-key/ page. Each account has one active key, and you can issue a new one at any time if needed.
First request
curl
curl https://api.ah777.info/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.ah777.info/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.ah777.info/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
SpotLogic provides a single active API key per account, issued upon registration on the /get-api-key/ page. This key authenticates all requests to the TTS engine and is displayed alongside your current balance and usage statistics.
Keys are generated in the standard tts-... format. Each account maintains one active key; issuing a new key immediately invalidates the previous one, ensuring clear audit trails for agency billing departments tracking character consumption across campaigns.
API Key Format
The API key is a single string starting with tts-, issued when you create your account. It serves as the sole credential for both the dashboard and the API endpoints.
Keys are tied to your specific site account. If you manage multiple agencies, each requires a distinct key generated from its respective /get-api-key/ page.
- Format:
tts-followed by alphanumeric characters - One active key per account
- Visible on the dashboard after login
Bearer Token Header
Include your key in the Authorization header of every request using the Bearer scheme. This standard header ensures your character usage is correctly attributed to your account balance.
Example: Authorization: Bearer tts-abc123def456
- Header name:
Authorization - Scheme:
Bearer - Value: your unique API key
Key Management
You can generate a new key at any time from the dashboard. The old key stops working immediately, which is useful if you suspect a leak or need to rotate credentials between campaign phases.
There is no fee for key rotation. The new key inherits your existing balance and rate limits.
- Generate new keys instantly
- Old keys invalidate immediately
- No cost for rotation
Endpoints
The SpotLogic API provides three primary endpoints for generating and managing audio assets. Agencies can generate speech, retrieve available voice presets, and list supported models. Each endpoint serves a specific function in the audio production workflow, from initial voice selection to final file delivery.
All endpoints require authentication via a Bearer token. The base URL for all requests is https://api.ah777.info/v1. Responses are returned in JSON format for metadata endpoints, while the speech generation endpoint returns the audio file directly.
Speech Generation
POST to /v1/audio/speech to convert text into audio files. The request body includes the text input, selected voice, and desired output format. Audio files are returned directly in the response body, allowing immediate integration into ad production pipelines.
The endpoint supports multiple output formats including MP3, WAV, Opus, and FLAC. Text input is limited to 4096 characters per request. For longer scripts, split the text into segments and join the resulting audio files.
- Endpoint: POST /v1/audio/speech
- Input: JSON body with 'input', 'voice', 'model', 'response_format', and 'speed' fields
- Output: Audio file in the specified format
- Max input length: 4096 characters
List Voices
GET /v1/voices returns a list of all available voice presets, their associated languages, supported output formats, and pricing information. This endpoint allows agencies to preview voice options before committing to a specific tone for their radio spots.
The response includes eight voice presets, each with distinct characteristics suitable for different advertising contexts. Voices are based on licensed recordings: LibriTTS-R (CC BY 4.0), from LibriVox public-domain audiobook readings.
- Endpoint: GET /v1/voices
- Returns voice ID, name, gender, and description
- Lists supported languages and formats per voice
List Models
GET /v1/models returns the available TTS models. Currently, two models are available: 'tts-1' and 'tts-1-hd'. Both models use the same engine and have identical pricing, allowing agencies to choose based on specific quality requirements without cost variation.
The models endpoint provides metadata about each model, including version information and supported features. This information helps agencies configure their integration correctly and understand the capabilities of each model.
- Endpoint: GET /v1/models
- Returns model ID, name, and description
- Includes supported voices and formats
Request Parameters
The API accepts standard TTS models that share the same engine and pricing structure. You may specify either "tts-1" or "tts-1-hd" in the request body; both deliver identical audio quality and cost, allowing agencies to toggle performance preferences without adjusting budget forecasts for radio spot production.
Model Selection
Both models use the same underlying synthesis engine. Both models use the same engine; choose either based on preference, as they have identical pricing and quality. Pricing remains constant at $0.01 per 1,000 characters regardless of the model selected, simplifying cost estimation for large campaign batches.
Input Text Limit
Each request supports up to 4,096 characters of input text. This limit applies to the raw string sent in the input field, including spaces and punctuation. For scripts exceeding this length, your system must split the text into manageable segments, synthesize them individually, and concatenate the resulting audio files.
- Maximum 4,096 characters per request.
- Spaces and punctuation count toward the limit.
- Split longer scripts client-side before sending.
Voice Selection
Select one of eight preset voices from the voice parameter. Each voice has a distinct character, such as the warm narration of Aria or the energetic promo style of Felix. Ensure the selected voice aligns with the target demographic of the radio spot before generating the final audio file.
- aria: Warm, clear narrator.
- nova: Bright, upbeat.
- luna: Soft, storytelling.
- sage: Calm, instructional.
- felix: Energetic, promo.
- milo: Friendly, conversational.
Response Formats
The API returns audio files in the format specified by the response_format parameter. Each generated file carries an inaudible watermark that marks it as synthetic speech, which is standard for broadcast verification.
MP3 Output
MP3 is the default format and is ideal for most radio spot workflows. It offers a good balance between file size and quality, making it easy to integrate into standard audio editing suites.
WAV Output
WAV provides uncompressed audio, preserving the full fidelity of the synthesis engine. This format is preferred for high-end radio production where no lossy compression is desired before final mastering.
Opus and FLAC Options
Opus offers efficient compression for web-based ad delivery, while FLAC provides lossless compression for archival purposes. Choose Opus for smaller file sizes without quality loss, or FLAC if you need a perfect copy of the generated audio for future edits.
Speed Control
The speed parameter allows you to adjust the playback rate of the generated radio spot, accepting values between 0.25 and 4.0. This control lets agencies fine-tune pacing for tight ad slots or dramatic effect without re-generating the entire audio file.
Speed Range 0.25-4.0
Values below 1.0 slow the voice, creating a more deliberate or suspenseful tone. Values above 1.0 accelerate the speech, useful for clearing dense copy within limited broadcast durations.
- Minimum speed: 0.25x
- Maximum speed: 4.0x
- Default speed: 1.0x
Adjusting Pace
Adjust speed per request to match the specific voice preset. You can adjust speed per request to match the specific voice preset or creative direction. Test combinations in your production workflow before finalizing assets.
Default Speed
If the speed field is omitted, the API defaults to 1.0x. This ensures consistent baseline output across all integrations and SDK implementations without requiring explicit parameter specification for standard-paced advertisements.

Language Handling
Language handling in SpotLogic’s TTS API allows precise control over voice delivery, ensuring radio spots sound natural in any target market. You can enforce a specific language or rely on intelligent detection to match the input script. This flexibility supports agencies producing multilingual campaigns without manual format adjustments.
The system automatically guesses the language based on the text script, defaulting to English for Latin characters. For non-English texts using Latin script, explicitly setting the language field prevents mispronunciation. Supported languages include Arabic, Chinese, French, German, Japanese, Spanish, and others; any voice can speak any of these 23 languages.
ISO Code Specification
You can specify the target language using standard ISO codes in the request body. This ensures the TTS engine uses the correct phonetic rules and intonation patterns for the desired output.
This approach is critical when mixing scripts or when the automatic detection might misinterpret the context. Explicit codes guarantee consistent results across different production workflows.
- Supported codes include: ar, zh, da, nl, en, fi, fr, de, el, he, hi, it, ja, ko, ms, no, pl, pt, ru, es, sw, sv, tr
- Any voice preset can speak any of these 23 languages
Automatic Detection
If you omit the language field, the API analyzes the input script to determine the language. This reduces boilerplate for single-language campaigns and speeds up integration.
Detection works based on character sets and common linguistic patterns. It is generally accurate but may fail if the text contains mixed languages or ambiguous characters.
Latin Script Default
Text in Latin script defaults to English if no language is specified. This is useful for quick testing but requires explicit configuration for other Latin-based languages like French, Spanish, or Dutch.
For non-English Latin text, always set the language parameter to avoid English pronunciation artifacts in your radio spots.
Not supported languages include Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali, and others not in the supported list.
Rate Limits
SpotLogic enforces a steady processing rate to ensure consistent audio quality for your ad campaigns. Understanding these limits helps you plan bulk generation without unexpected throttling.
60 Requests Per Minute
Each API key is limited to 60 requests per minute. This allows you to generate multiple radio spots efficiently without overwhelming the service.
10 Requests Before Top-up
New accounts or those without recent top-ups start with a lower limit of 10 requests per minute. This ensures fair usage before scaling up with USDT.
Queue Behavior
Requests are processed sequentially. Under load, additional requests may wait in a queue.
Error Handling
Synthetic speech generation is sensitive to input constraints. Understanding error codes helps agencies debug failed radio spot productions efficiently without wasting credits or delaying campaign timelines.
When requests fail, the API returns standard HTTP status codes. Failed synthesis charges are refunded in full, ensuring you only pay for successfully delivered audio files.
4xx Errors
Client errors typically indicate invalid parameters, such as exceeding the 4,096-character limit or using an unsupported voice ID. Ensure your text payload conforms to the required JSON structure and that the API key is active.
- 400: Invalid JSON or missing required fields
- 401: Unauthorized; check your Bearer token
- 413: Input text exceeds 4,096 characters
5xx Errors
Server errors are rare but may occur during peak processing times. Since requests are processed sequentially, high load can sometimes trigger temporary service interruptions. These errors do not incur charges.
Retry Logic
Implement exponential backoff for 5xx errors. For 4xx errors, verify your input parameters before retrying. Failed requests are free, so aggressive retrying on valid inputs is safe.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Selecting the right format depends on your final distribution channel.
23 languages
Any voice speaks any of these languages.
