Frequently asked questions
How do I get an API key?
Sign up on /get-api-key/ using Google or email. Accounts are per site. You receive one active key visible on the dashboard. A new key issued stops the old one immediately. Failed requests are free, and you can top up with USDT on the TRON network (TRC-20).
What is the base URL?
The API base URL is https://api.getchickensubway.com/v1. Use this for all requests. The speech endpoint is POST /v1/audio/speech. Voices and models are available via GET /v1/voices and GET /v1/models respectively. All endpoints use JSON bodies.
Does it support OpenAI SDKs?
Yes. The request shape matches the OpenAI speech endpoint. Change your SDK's base_url to https://api.getchickensubway.com/v1. Use the official OpenAI SDKs with your site's key. This allows standard integration without needing a custom client library.
What models are available?
Two models exist: tts-1 and tts-1-hd. They use the same engine and price. Choose based on quality preference. Both accept the same parameters. The model field is required in the JSON request body for every synthesis call.
How do I set the language?
Send the optional language field with an ISO code. If omitted, the system guesses from the script, defaulting to English for Latin text. Set it explicitly for non-English Latin-script text to ensure correct pronunciation and voice selection.
What is the max input length?
The maximum input length is 4096 characters per request. Spaces and punctuation count. For longer texts, split into parts of up to 4096 characters. Join the resulting audio files manually after synthesis. This ensures reliable processing within limits.
Can I stream the audio?
No streaming is supported. The API returns the complete audio file in the response. There is no WebSocket or real-time partial audio. You must wait for the full synthesis to complete before receiving the data. Use standard HTTP requests.
Do you support SSML?
SSML is not supported. The API accepts plain text input. There are no phoneme dictionaries or custom pronunciation lexicons. Emotion tags are also unavailable. Send simple text strings. The voice presets handle natural intonation without additional markup requirements.
How do I handle rate limits?
Limits are 60 requests per minute per key. New accounts start with 10 requests per minute. Monitor your usage via the dashboard. Implement exponential backoff if you hit limits. Queue requests if necessary, as they are processed sequentially under load.
What happens if the server is busy?
Requests are processed one after another. Under load, a request may wait in a queue. Typical speed is roughly real time. Short phrases take a few seconds. Long texts generate at about 25 characters per second. Be patient with delays.
Is the API RESTful?
Yes. It uses standard HTTP methods. POST for speech synthesis, GET for voices and models. Responses are JSON or audio files. Use standard HTTP headers for authentication. The structure is simple and follows common REST conventions for easy integration.
Can I use this with mobile apps?
Yes. Use the API directly from your mobile app. There is no official mobile SDK, but standard HTTP libraries work. Include your API key in the Authorization header. Be mindful of rate limits and character counts per request from the device.
How do I rotate my key?
Issue a new key from the dashboard at any time. The old key stops working immediately. The new key becomes active instantly. This allows seamless rotation without downtime. Use the new key in your application configuration after rotation.
Is there a webhook for status?
No webhooks are provided. There is no real-time status notification system. Check the dashboard for usage and balance. Request status is returned in the immediate response. Monitor your account page for billing and usage details manually.
First request
curl
curl https://api.getchickensubway.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.getchickensubway.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.getchickensubway.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 Keys
Access the /get-api-key/ page to generate your API key. You can sign in with Google or create an account with an email and password. Google sign-ins receive a $0.50 trial credit valid for 7 days, while email accounts start without credit. Your dashboard displays your active key, balance, and usage statistics.
Generate your API key
Navigate to the /get-api-key/ section of this site. Click 'Sign in with Google' for instant access with trial credit, or use 'Email + Password' for a standard account. Once authenticated, your unique Bearer token is displayed immediately on the dashboard.
Bearer token structure
Include your key in every API request header as Authorization: Bearer tts-.... This token authenticates all calls to the https://api.getchickensubway.com/v1 endpoint. Ensure no extra spaces are included in the header value to avoid authentication errors.
Rotating keys safely
You can issue a new key at any time from your dashboard. When you generate a new key, the previous one becomes invalid immediately. This ensures that if a key is compromised, you can revoke access instantly without waiting for a renewal cycle.
Endpoint Overview
The API provides three primary endpoints for generating audio and managing resources. The speech endpoint accepts text and returns audio files, while the list endpoints allow you to discover available voices and models programmatically.
Speech generation endpoint
Send a POST request to /v1/audio/speech with your text payload. The system processes the input and returns the generated audio file in the specified format.
- Endpoint:
POST https://api.getchickensubway.com/v1/audio/speech - Returns audio data directly in the response body
List voices endpoint
Retrieve the full list of available voices, their associated languages, supported formats, and pricing details. This helps you select the most appropriate voice for your tourism app's tone.
- Endpoint:
GET /v1/voices - Returns details on all 8 voice presets and language support
List models endpoint
Query the available models to confirm engine versions. Both tts-1 and tts-1-hd use the same engine and pricing structure.
- Endpoint:
GET /v1/models - Returns model IDs and metadata
Request Parameters
The input field accepts plain text up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer audioguide scripts, split the text into chunks, generate each audio file, and join them seamlessly.
Use the voice parameter to select one of eight presets tailored for tourism narration. Choose aria for clear guides, atlas for news-style updates, or nova for upbeat promotional content. Any voice can speak any of the 23 available languages.
Input text and limits
Send your script text in the input field. The API processes up to 4096 characters per call. If your audioguide exceeds this, divide the text into segments and concatenate the resulting audio files.
Voice selection presets
Select a voice that matches your tour’s tone. Female voices include aria (warm narrator), nova (bright), luna (soft storytelling), and sage (calm instruction). Male options are felix (energetic promo), milo (conversational), atlas (neutral news), and orion (deep documentary).
Speed and language codes
Adjust speed between 0.25 and 4.0 to control playback rate. Set the optional language parameter using ISO codes (e.g., en, fr, de). If omitted, the system guesses the language from the script, defaulting to English for Latin text.
Specify response_format as mp3, wav, opus, flac, or pcm. The model parameter accepts tts-1 or tts-1-hd for identical pricing and engine performance.
Response Formats
The API returns audio data in the requested format, such as MP3, WAV, Opus, FLAC, or PCM. Each generated file includes an inaudible watermark to identify it as synthetic speech. For short phrases, response time is a few seconds; longer texts process at roughly real-time speed (25 characters per second).
Audio file formats
Supported formats include MP3, WAV, Opus, FLAC, and PCM. Select the format that best fits your audioguide app’s playback requirements. All files are standard audio containers, ensuring compatibility with common mobile and web players without additional conversion steps.
Error response structure
Errors return standard JSON with an error code and message. Failed synthesis requests are free, with charges returned in full. Common issues include invalid voice names, exceeding the 4096-character limit, or authentication failures. Check the response body for specific details to resolve the issue quickly.
- 400 Bad Request: Invalid parameters or voice name
- 401 Unauthorized: Invalid or expired API key
- 429 Too Many Requests: Rate limit exceeded
Rate limit headers
Responses include headers indicating your current rate limit status. The limit is 60 requests per minute per key (10 per minute before the first top-up). If you are under load, requests may queue, but you will still receive a response once processed. Monitor these headers to adjust your request frequency and avoid delays.
Integration Examples
Integrating VoxMuse into your tourism app requires minimal boilerplate. The API follows standard REST conventions, allowing you to generate audio files for audioguides using familiar tools. You can test connectivity immediately with a simple command or integrate directly into your backend logic.
cURL command example
Use this command to generate speech for a museum plaque description. Replace YOUR_API_KEY with your token from /get-api-key/.
- curl -X POST https://api.getchickensubway.com/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Welcome to the ancient ruins.", "voice": "sage", "response_format": "mp3"}'
OpenAI SDK base_url setup
Since the request shape matches the OpenAI speech endpoint, you can reuse existing SDK configurations. Simply point your client to our base URL.
- base_url: https://api.getchickensubway.com/v1
- Use any standard OpenAI SDK version.
Python request example
For backend services, use the requests library to handle the POST call. This example demonstrates sending a short tour segment.
- import requests
- response = requests.post('https://api.getchickensubway.com/v1/audio/speech', json={...}, headers={'Authorization': 'Bearer YOUR_KEY'})

Handling Long Texts
Tourism guides often exceed the 4096-character limit per request. You must split your script into chunks that fit within this boundary before sending them to the API.
Each chunk generates a separate audio file. Your application must concatenate these files in order to create a continuous listening experience for the user.
4096 character limit
Each API request accepts a maximum of 4096 characters, including spaces and punctuation. If your guide script is longer, you must divide it manually or via code before calling the endpoint.
Short phrases take a few seconds to generate. Long texts process at roughly real-time speed, but requests are queued sequentially under load.
- Count characters carefully; spaces and punctuation count toward the 4096 limit.
- Split text at logical boundaries like sentences or paragraphs to avoid cutting mid-thought.
Splitting and joining audio
Send each split chunk as a separate POST request to the speech endpoint. The API returns an audio file for each chunk.
Your client code must receive these files and join them sequentially. There is no built-in streaming or real-time partial audio from the API.
Use the OpenAI SDK or standard HTTP libraries to manage these sequential requests efficiently.
Consistency across segments
Since each chunk is generated independently, slight variations in pacing may occur between segments. Choose a stable voice preset like 'aria' or 'nova' to maintain a consistent tone.
The API does not offer custom pronunciation lexicons.
All generated files carry an inaudible watermark, but this does not affect the auditory continuity of your joined audio.
Rate Limits and Queues
Text-to-speech requests are processed sequentially. You are limited to 60 requests per minute per active key. For tourism apps generating audioguide content, this limit applies to each key independently.
Under heavy load, requests may wait in a queue before processing begins. This ensures steady generation without dropping requests, though response times may increase during peak usage periods.
60 requests per minute
Each API key allows up to 60 requests per minute. This limit is strict and resets every minute. Plan your audio generation batches accordingly to avoid hitting the cap during peak tourism hours.
Queue behavior under load
Requests are processed one after another. If you send multiple requests quickly, they may wait in a queue. This can increase total generation time, especially for longer texts requiring multiple segments.
Pre-first top-up limit
Before your first top-up, you are limited to 10 requests per minute. This lower limit helps manage initial usage. Once you add USDT via TRON, the limit increases to 60 requests per minute.
Troubleshooting
Troubleshooting common issues helps keep your audioguide generation smooth. Most errors are resolved by verifying your key format or checking character limits before sending requests.
Common error codes
Use 401 to verify your Bearer token is correct and active. If you see 429, you have exceeded the 60 requests per minute limit, or 10 per minute if no top-up has been made yet.
Invalid voice names
Ensure you use one of the eight preset voices: aria, nova, luna, sage, felix, milo, atlas, or orion. Case sensitivity matters, so match the exact lowercase spelling provided in the /v1/voices endpoint.
Network timeout handling
Short phrases may take a few seconds to generate. If a request hangs, retry with exponential backoff. Under heavy load, requests process sequentially, so queuing delays are normal and do not indicate failure.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. We build immersive audio stories for independent creators who want to bring museums to life through sound.
23 languages
Any voice speaks any of these languages.
