Wiozen Voice API
Use Wiozen Voice from your own code, from Claude Code or from Claude connectors. Keys, billing and limits live in the Wiozen API; the audio is made in Voice.
Authentication
Send Authorization: Bearer sk-gw-… with every request. Get a key in the Wiozen API panel; Voice never stores it.
Endpoints
POST /v1/voice/speech | Turns text into speech. Returns JSON: file URLs, duration, characters and, if asked, sentence timings. |
GET /v1/voice/jobs/:id | Status of a long job: queued, warming, running, done, failed. |
GET /v1/voice/voices | Voice list; filter with ?language=, ?gender=, ?tone=. Free. |
POST /v1/voice/estimate | Characters, estimated cost and time, and the text as it will be read. No audio, free. |
POST /v1/audio/speech | OpenAI compatible: model "wiozen-voice", returns audio bytes. speed must be 1. |
Request fields (/v1/voice/speech)
input | text; required |
voice | voice id (e.g. defne); required |
language | optional; detected from the text when omitted, 400 language_not_detected if that fails |
format | mp3 (default) or wav |
timings | none (default) or sentence |
settings | optional: exaggeration, pace, temperature, seed (the same seed gives a similar result, not always an identical one) |
async | true: long text runs as a job (202); poll /v1/voice/jobs/:id |
Example request
curl
curl https://api.wiozen.com/v1/voice/speech \
-H "Authorization: Bearer $WIOZEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sahne-1-v1" \
-d '{"input":"Merhaba, bu kısa bir denemedir.","voice":"defne","timings":"sentence"}'Node
const res = await fetch("https://api.wiozen.com/v1/voice/speech", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WIOZEN_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "sahne-1-v1",
},
body: JSON.stringify({ input: "Merhaba, bu kısa bir denemedir.", voice: "defne", timings: "sentence" }),
});
const speech = await res.json(); // speech.audio_url, speech.timings.captionsPython
import os, requests
res = requests.post(
"https://api.wiozen.com/v1/voice/speech",
headers={
"Authorization": f"Bearer {os.environ['WIOZEN_API_KEY']}",
"Idempotency-Key": "sahne-1-v1",
},
json={"input": "Merhaba, bu kısa bir denemedir.", "voice": "defne", "timings": "sentence"},
)
speech = res.json() # speech["audio_url"], speech["timings"]["captions"]
Never pay twice for the same request
Send an Idempotency-Key header (8–120 characters: letters, digits, :_-). The same key and body within 24 hours returns the first result without charging again; the same key with a different body gets 409 idempotency_conflict.
Response
{
"id": "j_r8fK2…",
"status": "done",
"chars": 52,
"language": "tr",
"language_source": "detected",
"language_detected": "tr",
"duration_ms": 3980,
"sample_rate": 24000,
"format": "mp3",
"audio_url": "https://voice.wiozen.com/dl/<token>.mp3",
"timings_url": "https://voice.wiozen.com/dl/<token>.json",
"srt_url": "https://voice.wiozen.com/dl/<token>.srt",
"expires_at": "2026-11-21T11:44:00Z",
"timings": { "version": 1, "durationMs": 3980, "sampleRate": 24000, "granularity": "sentence", "captions": [ … ], "parts": [ … ] }
}The response also has cost_usd (amount charged, USD). sample_rate is the engine's real output rate, not a constant. File URLs need no key and last 24 hours; files are kept 30 days.
Sentence timings
Returned with timings: "sentence". The captions array matches the Caption type from Remotion's @remotion/captions; pass it to your caption component or createTikTokStyleCaptions. text is what you wrote. Composition length: Math.ceil(durationMs / 1000 * fps) frames.
{
"version": 1,
"audio": "voice-r_8fK2.mp3",
"durationMs": 23140,
"sampleRate": 24000,
"granularity": "sentence",
"captions": [
{ "text": " Geçen ay kafemizin elektrik faturası 4.850 TL geldi.", "startMs": 0, "endMs": 3980, "timestampMs": 1990, "confidence": null, "pageBreakAfter": true },
{ "text": " Bu ay aynı tüketimle 5.320 TL ödedik; fark %9,7.", "startMs": 4200, "endMs": 7920, "timestampMs": 6060, "confidence": null, "pageBreakAfter": true }
],
"parts": [ { "index": 0, "startMs": 0, "endMs": 7920 } ]
}
Use with Claude (MCP)
Claude Code
claude mcp add --transport http wiozen-voice https://api.wiozen.com/mcp \
--header "Authorization: Bearer ${WIOZEN_API_KEY}"Claude desktop and claude.ai (custom connector)
URL: https://api.wiozen.com/mcp
Header: Authorization: Bearer <WIOZEN_API_KEY>Tools: list_voices, estimate, synthesize, get_job, get_balance. synthesize returns two file links and the timings; Claude Code downloads the files into your project.
Claude skill
Ready-made instructions that set up the voiceover, file locations and composition length in a Remotion project in one go. Save it as ~/.claude/skills/wiozen-voice/SKILL.md.
Limits
- Up to 4,096 characters per synchronous request; longer text up to 50,000 characters with async.
- 20 requests per minute and 2 jobs at a time per key.
- Default daily Voice cap per key is $5; change it in the Wiozen API panel.
- Failed generations are free.
Errors
OpenAI-style body: {"error":{"type","code","message"}}. Codes:
| 400 | missing_input |
| 400 | input_too_long |
| 400 | voice_not_found |
| 400 | language_not_supported |
| 400 | language_not_detected |
| 400 | unsupported_parameter |
| 400 | invalid_settings |
| 400 | content_blocked |
| 400 | invalid_idempotency_key |
| 400 | invalid_body |
| 404 | job_not_found |
| 409 | idempotency_conflict |
| 429 | insufficient_balance |
| 429 | key_spend_limit |
| 429 | key_daily_limit |
| 429 | rate_limited |
| 502 | render_failed |
| 503 | engine_unavailable |