Originally published by Tokenhot Team on 2026-10-11. The DEV edition was formatted with AI assistance.
A successful MiMo speech request returns JSON containing audio data; saving the JSON body with a .wav extension will not create an audio file. The useful sequence is to keep the response, decode the audio, validate the WAV container, and then listen to the result.
This guide uses our preset-voice mimo-v2.5-tts route. The preset-voice reference specifies POST https://api.tokenhot.ai/v1/chat/completions, Bearer authentication, and an important message convention: spoken text belongs in an assistant message; an optional user message controls style. This is a speech route, so do not replace that convention with a generic chat example.
Build a preset-voice request
The following non-streaming request uses the documented English preset Mia:
Local tests use artificial PCM WAV data to check file handling and failures. Synthesize and listen to a short sample to check model output before production.
{
"model": "mimo-v2.5-tts",
"messages": [
{"role": "user", "content": "Read clearly at a steady conversational pace."},
{"role": "assistant", "content": "Your project is ready. Open the dashboard to review the result."}
],
"audio": {"format": "wav", "voice": "Mia"}
}
Keep the spoken copy separate from delivery directions so that changing the voiceover does not accidentally change its tone instruction. Use a voice explicitly listed for your intended language. The helper chooses an explicit preset rather than relying on a cluster-dependent default.
The preset route is not the voice-design or voice-cloning route. Their separate model IDs appear in the same documentation, but reference-audio submission, voice design and streaming output are outside this tutorial. Start with this small request before designing a more complex voice pipeline.
Prepare the JSON without spending API usage
Save mimo_wav.py beside a UTF-8 text file named voiceover.txt. The helper uses the Python standard library. Local checks used Python 3.13.5; verify compatibility with your Python version and operating system.
Run the local preparation command:
python mimo_wav.py prepare \
--text-file voiceover.txt \
--voice Mia \
--style "Read clearly at a steady conversational pace." \
--output mimo-request.json
This writes the JSON request and stops. It does not require a key, open a connection or contact a synthesis service. Review the actual text and preset before proceeding. The file is intentionally not overwritten by a later prepare command; use a new name for an intentional revision.
For credentials, follow our setup guide. Set TOKENHOT_API_KEY in your environment rather than in the request JSON or Python source. Do not commit the key, a terminal dump containing it, or an unredacted account response.
Synthesize once and retain the response
After authorizing the actual request and its possible charge, run:
python mimo_wav.py synthesize \
--request mimo-request.json \
--run runs/mimo-001 \
--execute
The --execute flag is an explicit network gate. The command reserves a new run directory before sending one POST. It stores your request, safe request metadata and the raw response locally. When decoding succeeds, the directory also contains speech.wav.
Do not infer permanent free use from a zero price displayed elsewhere. Check the terms and price for your actual route before sending requests, and reconcile its usage afterward; a displayed zero price does not establish your account's entitlement or charges.
The response is saved before decoding because synthesis and local file creation are different operations. A full response can arrive even if an audio field is malformed or the output directory is unavailable. Repeating the synthesis is not the right first response to that local failure.
Decode audio bytes, not the surrounding JSON
In the documented response, the Base64 payload is at choices[0].message.audio.data, and the illustrated completion uses finish_reason: "stop". The helper checks that structure before decoding. The documentation abbreviates its audio string, so that sample cannot be used as a real audio test fixture.
The relevant local operations are:
import base64
import io
import wave
def inspect_pcm_wav(encoded):
"""Local container inspection, not a speech-quality check."""
raw = base64.b64decode(encoded, validate=True)
with wave.open(io.BytesIO(raw), "rb") as audio:
return {
"channels": audio.getnchannels(),
"sample_rate_hz": audio.getframerate(),
"sample_width_bytes": audio.getsampwidth(),
"frames": audio.getnframes(),
}
This small excerpt only inspects the header. The complete companion additionally rejects empty audio, checks that the declared PCM frames are present, and refuses to overwrite an existing output. It returns sanitized diagnostics rather than printing arbitrary provider error text.
Python 3.13's wave module supports uncompressed PCM WAV and the applicable PCM extensible headers. An unsupported format should trigger investigation, not an attempt to manufacture a header. In particular, do not add a second WAV header to bytes that already include one. PCM streaming is a different framing problem and is deliberately not handled by this script.
The helper reads the sample rate and channel count from the returned container instead of assuming the settings of a different streaming mode. That makes an unexpected format visible before it becomes a hard-to-debug playback issue.
Recover locally when saving failed
When a complete response already exists, use the local save command:
python mimo_wav.py save \
--response runs/mimo-001/response.json \
--output output/recovered-voiceover.wav
This command has no network path and needs no API key. It reads the saved response, decodes its audio and writes to a fresh destination. Keep the original response until you have accepted the output.
| Observation | Next action |
|---|---|
| HTTP rejection with a saved body | Inspect that body privately and correct the request or account issue; do not blindly retry. |
| Missing, invalid or abbreviated audio data | Check the actual response and route. A documentation placeholder is not downloadable audio. |
| Valid JSON but unsupported audio container | Confirm the returned format and decoder; do not guess the encoding. |
| Existing output file | Inspect it or choose a deliberate new output name. |
| Timeout without a usable response | Treat the synthesis outcome as unknown and reconcile the attempt before sending another POST. |
The HTTP helper has a local 64 MiB response guard. This is an implementation limit for the example, not a documented MiMo maximum. It also rejects redirects. A redirected endpoint or substantially larger response requires an intentional implementation change and another check of credential and memory handling.
Listen before using the voiceover
Open the saved WAV in a player. Confirm the entire text is present, product names and numbers are pronounced acceptably, the pacing works, and no unwanted spoken instruction appears. Container validation cannot answer those questions.
Keep content and delivery decisions separate when revising: changing text, preset, style and punctuation simultaneously makes a later result harder to evaluate. Record the exact request for each intentional version, and count all actual synthesis attempts when measuring cost.
Use an authorized real run to check voice quality, latency, account entitlement and billing after handling the documented response and saving the audio.
Top comments (0)