Speech synthesis (TTS)
Choose the TTS interface for your model: Gemini uses its native API; Audio-group models use the speech and task API below.
Gemini native text-to-speech
Use a key from the gemini aistudio group. Confirm model access with GET /v1/models; availability and prices depend on your key. These models generate speech from text and are not general chat models.
- gemini-3.8-flash-tts
- gemini-3.8-flash-lite-tts
Generate and save a WAV file
POST /v1beta/models/{model}:generateContent uses x-goog-api-key, contents and generationConfig.responseModalities=[AUDIO]. The response is JSON: decode candidates[].content.parts[].inlineData.data from Base64. The models below return audio/wav for synchronous requests: save the decoded bytes directly, without another WAV header.
curl --fail-with-body --max-time 120 \
"https://apixly.ai/v1beta/models/gemini-3.8-flash-lite-tts:generateContent" \
-H "x-goog-api-key: YOUR_GEMINI_AISTUDIO_GROUP_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Hello, welcome!"}]}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}
},
"maxOutputTokens": 512
}
}' > response.jsonimport base64
import json
with open("response.json", encoding="utf-8") as source:
response = json.load(source)
audio = next(
part["inlineData"]
for candidate in response.get("candidates", [])
for part in candidate.get("content", {}).get("parts", [])
if "inlineData" in part
)
if audio["mimeType"].split(";", 1)[0] != "audio/wav":
raise ValueError("Expected synchronous WAV audio")
with open("speech.wav", "wb") as target:
target.write(base64.b64decode(audio["data"], validate=True))Stream audio
POST /v1beta/models/{model}:streamGenerateContent?alt=sse returns SSE events. Decode each inlineData.data audio chunk in order. Streamed audio/l16 is 24 kHz, 16-bit, mono PCM; use a PCM player or add one WAV header after collecting the samples. Do not save SSE text as an audio file.
curl --no-buffer --fail-with-body --max-time 120 \
"https://apixly.ai/v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: YOUR_GEMINI_AISTUDIO_GROUP_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Hello, welcome!"}]}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}
},
"maxOutputTokens": 512
}
}'
# Parse data: JSON events; Base64-decode each inlineData.data audio chunk.
# Streamed audio/l16 is PCM, not a WAV file or an async task.Gemini billing and interface scope
Text input and generated audio are billed by their respective token counts, not by characters. One second of audio corresponds to 25 audio tokens. Check the TTS model cards for current USD prices and your group discount. This native API does not return task_id or use async:true; /v1/audio/speech, /v1/audio/config and the Audio task endpoints below apply to Audio-group models.
Audio API · Endpoint and API key
POST /v1/audio/speech · Authorization: Bearer YOUR_API_KEY · Audio
Use async: true for both STT and TTS. Submission returns task_id; poll the task without keeping the original connection open. Synchronous models also support async submission.
Supply model and input. Voice, language, reference audio and emotion parameters depend on the model; GET /v1/audio/config lists current parameters. See /models for character, request or second billing and current prices.
curl --max-time 190 "https://apixly.ai/v1/audio/speech" -H "Authorization: Bearer YOUR_API_KEY" -H "Idempotency-Key: UNIQUE_GENERATION_ID" -H "Content-Type: application/json" -d '{"model":"Qwen3-TTS","input":"Hello!","voice":"Ryan","language":"English","response_format":"mp3","async":true}'Audio API · Async tasks
Use async: true for both STT and TTS. Submission returns task_id; poll the task without keeping the original connection open. Synchronous models also support async submission.
A model that requires asynchronous execution rejects synchronous requests with 400 async_required before creating an upstream task or charging. Check GET /v1/audio/config for supported execution modes.
waiting means queued; in_progress means processing; only success confirms completion. TTS audio is in output.result or output.file_url; STT results are in output.transcription. Download audio before expires_at.
Use a unique Idempotency-Key per generation. After a disconnect, reuse the original key and identical parameters or query task_id. Cancelling an unstarted queued task releases its reservation; submitted tasks need confirmed cancellation. unknown is not a confirmed free failure: keep the task ID and check with support.
curl "https://apixly.ai/v1/task/TASK_ID" -H "Authorization: Bearer YOUR_API_KEY"curl -X POST "https://apixly.ai/v1/task/TASK_ID/cancel" -H "Authorization: Bearer YOUR_API_KEY"Audio API · Billing
Submission reserves the estimated fee at the model price, billing unit and discount fixed for this task. Queuing is not final charging. Completed work is settled once; the final USD amount appears in usage.cost_request and usage records.
Audio API · Response examples
waiting means queued; in_progress means processing; only success confirms completion. TTS audio is in output.result or output.file_url; STT results are in output.transcription. Download audio before expires_at.
Audio API · TTS parameters and model-specific options
Supply input (1–10000 Unicode characters), or model-supported inputs[] (1–32 prompt objects), never both. Qwen3-TTS voices: Vivian, Serena, Uncle_Fu, Dylan, Eric, Ryan, Aiden, Ono_Anna, Sohee; language Chinese (default) or English. response_format: mp3/wav; url requests a URL result, with response_data_format=url as an alternative. Use returned expires_at, not a hard-coded download lifetime.
Voice cloning: prompt_audio_url is required by reference-based models; CosyVoice2/3 and Step-Audio-TTS-3B also need prompt_text. Reference URLs must be public HTTP(S). IndexTTS-2 emotion controls: emo_text, use_emo_text, emo_alpha (0–1), emo_vector (8 values, each 0–1), emo_audio_prompt_url. ChatTTS: temperature, top_P, top_K. speed is usually 0.5–2; CosyVoice3 and Spark-TTS-0.5B use 1–5. Aliases speaker→voice, prompt_wav_url→prompt_audio_url, instruction/instruct_text→instructions, output_format→response_format, top_p/top_k→top_P/top_K must not conflict. All options depend on the model contract; check /v1/audio/config.
Audio API · Additional model options
ChatTTS: voice_url is a public HTTP(S) voice-feature URL. Spark-TTS-0.5B: gender=male/female and pitch=1–5. CosyVoice2/3: seed accepts an integer or integer string. Support is model-specific; a fixed seed does not guarantee identical audio.
Audio API · Model-specific request contracts
Discover available IDs with GET /v1/models using your key. The public price catalog is not a guarantee of current routing. Existing valid requests need no changes; optional fields are model-specific.
Existing valid single-input requests do not need changes. Use input for ChatTTS, CosyVoice2, GLM-TTS and Step-Audio-TTS-3B and send each generation as a separate request. async:true gives a durable task; it does not add batch support to a synchronous-only model. Multi-item inputs[] are now rejected before supplier submission for those models, rather than merging the texts and quoting multiple request charges.
IndexTTS-2 and GLM-TTS require prompt_audio_url. GLM-TTS prompt_text is optional. The current GLM-TTS provider rejects requests without reference audio; supply the URL even though its published schema marks it optional. CosyVoice2/3 and Step-Audio-TTS-3B require both prompt_audio_url and prompt_text. Spark-TTS-0.5B has a gender/pitch/speed mode and a reference-audio mode; pitch/speed use1–5. All model access is subject to GET /v1/models with your key.
- ChatTTS
- CosyVoice2
- CosyVoice3
- GLM-TTS
- IndexTTS-2
- Qwen3-TTS
- Spark-TTS-0.5B
- Step-Audio-TTS-3B
curl --max-time 190 "https://apixly.ai/v1/audio/speech" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"GLM-TTS","input":"你好,这是一个语音测试。","prompt_audio_url":"https://your-server.example.com/reference.mp3","response_format":"mp3"}' \
--output speech.mp3