Text-to-Speech API
Turn text into audio with Qwen TTS. Set the voice and format, then save and validate the audio response.
/v1/audio/speech1. Getting started
| Item | Value |
|---|---|
| Console | https://api.sinorouter.ai |
| API Base URL | https://api.sinorouter.ai/v1 |
| Full endpoint | POST https://api.sinorouter.ai/v1/audio/speech |
| Authentication | Authorization: Bearer <API_KEY> |
| Request content type | Content-Type: application/json |
| Token group | Voice All in One; account access to this group is required |
- Sign in to the console and create an API token with access to the voice models. Store it only in the server-side
API_KEYenvironment variable; do not include it in public code or a browser frontend. - This reference applies only to
api.sinorouter.ai. Tokens, model permissions and access from another site are not interchangeable; match the key to this domain. - Use the API Base URL above in SDK settings. For raw HTTP, use the full endpoint. Avoid omitting or duplicating
/v1.
2. Models and request parameters
Exact model value | Capability | Response |
|---|---|---|
qwen-audio-3.0-tts-flash | Text to speech | Audio bytes in the same request |
qwen-audio-3.0-tts-plus | Text to speech | Audio bytes in the same request |
2.1 Available fields and actual behavior
| Field | Requirement | Current site behavior |
|---|---|---|
model | Required string | Use a complete model ID above. -plus is not a standalone model ID |
input | Required string | Non-empty plain text; leading/trailing whitespace is trimmed. SSML support is not promised. Split long text into shorter synthesis requests |
voice | Optional string | Explicit longanhuan_v3.6 is recommended; see §2.2 |
response_format | Optional string | Default mp3. Current code maps mp3, wav, pcm, opus; other values fall back to MP3 rather than guaranteeing the requested format |
speed | Adjustment unavailable | The synthesis path uses fixed speed 1.0; passing speed does not change it |
| Other extension fields | Not documented capabilities | instructions, stream_format and similar fields do not enable instruction control or SSE. Do not infer support from a generic SDK's field list |
This reference does not specify a verified maximum input length, complete supported-language list or complete voice catalogue. Confirm those details before building language-dependent or long-text workflows. English documentation does not by itself establish English synthesis support for a particular voice.
2.2 Voices and capability boundaries
- Both models use platform-supported
_v3.6preset voices only. Start withlonganhuan_v3.6. - If
voiceis omitted or does not contain_v3.6—including values such asalloyorCherry—the current implementation falls back tolonganhuan_v3.6. It does not select the named voice. - A string containing
_v3.6is passed through, but the suffix does not prove that the voice exists. Misspelled or incompatible names can still fail; arbitrary_v3.6names are not guaranteed to work. - Voice cloning and custom voices are not currently available. There is no reference-audio upload or cloning endpoint in this reference.
- The implementation uses plain text, a fixed 22050 Hz sample-rate setting, fixed volume and fixed pitch. Client adjustment of those settings is unavailable. Actual output details for individual formats still require audio validation (§4).
3. Executable request example
Requires Bash, curl with --fail-with-body, and Python 3. Optionally install ffprobe for container inspection and ffmpeg for a full decode check.
Set export API_KEY='YOUR_SINOROUTER_API_KEY', save the full script below as tts.sh, then run bash tts.sh. The sample input remains in Chinese to preserve the original voice example; all script instructions and diagnostics are in English.
The script does not retry automatically. It preserves diagnostics on failure, prints text/JSON errors without dumping partial binary audio to the terminal, and checks the successful response's content type and body. To use Plus, change only model to qwen-audio-3.0-tts-plus.
#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${API_KEY:?Set the SinoRouter API_KEY environment variable first}"
BASE_URL="https://api.sinorouter.ai/v1"
OUTPUT_FILE="${OUTPUT_FILE:-speech.mp3}"
[[ ! -e "$OUTPUT_FILE" ]] || { printf 'Output exists; set OUTPUT_FILE to a new path.\n' >&2; exit 1; }
WORK_DIR=$(mktemp -d)
cleanup() {
code=$?
if [[ "$code" == 0 ]]; then
rm -rf "$WORK_DIR"
else
printf 'Diagnostics preserved in: %s (keep private)\n' "$WORK_DIR" >&2
fi
}
trap cleanup EXIT
cat > "$WORK_DIR/request.json" <<'JSON'
{
"model": "qwen-audio-3.0-tts-flash",
"input": "你好,欢迎使用 SinoRouter 语音合成。",
"voice": "longanhuan_v3.6",
"response_format": "mp3"
}
JSON
if ! curl --fail-with-body --silent --show-error \
--connect-timeout 15 --max-time 180 \
"$BASE_URL/audio/speech" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data-binary "@$WORK_DIR/request.json" \
--dump-header "$WORK_DIR/headers.txt" \
--output "$WORK_DIR/response.body"; then
python3 - "$WORK_DIR/headers.txt" "$WORK_DIR/response.body" <<'PY'
from pathlib import Path
import re, sys
headers = Path(sys.argv[1]).read_text(errors="replace") if Path(sys.argv[1]).exists() else ""
body = Path(sys.argv[2]).read_bytes() if Path(sys.argv[2]).exists() else b""
types = re.findall(r"(?im)^content-type:\s*([^\r\n;]+)", headers)
kind = types[-1].strip().lower() if types else ""
print("Request failed. Response Content-Type:", kind or "unknown", file=sys.stderr)
if kind.startswith("text/") or "json" in kind or body.lstrip().startswith((b"{", b"[", b"<")):
print(body[:2000].decode("utf-8", errors="replace"), file=sys.stderr)
else:
print("Binary/unknown response retained in the diagnostic directory.", file=sys.stderr)
PY
exit 1
fi
python3 - "$WORK_DIR/headers.txt" "$WORK_DIR/response.body" <<'PY'
from pathlib import Path
import re, sys
headers = Path(sys.argv[1]).read_text(errors="replace")
body = Path(sys.argv[2]).read_bytes()
types = re.findall(r"(?im)^content-type:\s*([^\r\n;]+)", headers)
kind = types[-1].strip().lower() if types else ""
if not body or kind != "audio/mpeg" or body.lstrip().startswith((b"{", b"[", b"<")):
print("Expected a non-empty MP3 response; received:", kind, file=sys.stderr)
if "json" in kind or kind.startswith("text/") or body.lstrip().startswith((b"{", b"[", b"<")):
print(body[:2000].decode("utf-8", errors="replace"), file=sys.stderr)
sys.exit(1)
PY
if command -v ffprobe >/dev/null 2>&1; then
ffprobe -v error "$WORK_DIR/response.body"
fi
if command -v ffmpeg >/dev/null 2>&1; then
ffmpeg -v error -xerror -i "$WORK_DIR/response.body" -f null -
else
printf 'Full decode not checked: install ffmpeg or verify playback manually.\n'
fi
mv "$WORK_DIR/response.body" "$OUTPUT_FILE"
printf 'Saved %s; play the audio to check completeness.\n' "$OUTPUT_FILE"4. Response and audio files
response_format | Current Content-Type mapping | Suggested file |
|---|---|---|
mp3 (default) | audio/mpeg | speech.mp3; recommended for first integration |
wav | audio/wav | speech.wav |
pcm | audio/pcm | speech.pcm; raw bytes are not a WAV file just because the extension changes |
opus | audio/ogg | speech.ogg; validate the actual container and player compatibility |
The success response is audio bytes, not JSON. It has no download URL, task ID or polling endpoint. HTTP may transfer binary audio in chunks; that is not an SSE text-event stream.
The script validates MP3 specifically. When changing format, update response_format, Content-Type validation and the output filename together. Renaming a file does not transcode its contents.
The format table reflects current code mappings, not individual live verification of every output format. Validate MP3 first. Confirm PCM bit depth and channel count, and the actual containers of other formats, with valid audio before integrating playback.
HTTP 200 or an
audio/*header alone does not prove the audio is complete. Interrupted transfer or a synthesis failure after headers are sent can leave incomplete data.--fail-with-bodydetects unsuccessful HTTP status codes; also inspect curl's exit status, the response body and real decode/playback results.ffprobeinspection alone is not a complete decode test.
5. Troubleshooting
| Symptom | Action |
|---|---|
| 401 / invalid token | Check Bearer authentication, environment variable, token status and owning site. Do not send your key to others |
No available channel | Check the Voice All in One token group, account permission and exact complete model ID. Contact support to check availability if it persists |
404 Invalid URL or HTML | Use https://api.sinorouter.ai/v1/audio/speech; verify method, path, /v1 and invisible copied characters. HTML is not audio |
model is required / input text is required | Validate JSON, presence of model, and a non-empty input that is not just whitespace |
Engine error [411] or unexpected voice | Start with longanhuan_v3.6; check spelling and model family. Non-_v3.6 names fall back; invalid names containing the suffix can still fail |
model_price_error | Server-side model configuration issue. Record the original error and contact support |
| Unplayable file / JSON inside audio file | Check actual bytes, Content-Type, HTTP status and curl exit code; validate decoding as described in §4 |
| Timeout / incomplete output | Shorten input, check network/proxy and preserve the error response and time. Inspect the previous outcome before a manual retry to avoid unnecessary duplicate requests |
5.1 Information to provide to support
- Site domain, request time and timezone,
model,voice,response_format, HTTP status, curl error and redacted original response. - Include a request ID if present in headers or errors. This endpoint produces no
task_id; do not use the image/video task workflow to look for one. - Remove
Authorizationand real API keys. Replace sensitive input with the shortest reproducible text. Do not debug audio binary as JSON, and do not share the diagnostic directory without redacting sensitive input and temporary access links.
Use current console notices for model or feature changes.