Wiozen Voice

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.

Get a key

Endpoints

POST /v1/voice/speechTurns text into speech. Returns JSON: file URLs, duration, characters and, if asked, sentence timings.
GET /v1/voice/jobs/:idStatus of a long job: queued, warming, running, done, failed.
GET /v1/voice/voicesVoice list; filter with ?language=, ?gender=, ?tone=. Free.
POST /v1/voice/estimateCharacters, estimated cost and time, and the text as it will be read. No audio, free.
POST /v1/audio/speechOpenAI compatible: model "wiozen-voice", returns audio bytes. speed must be 1.

Request fields (/v1/voice/speech)

inputtext; required
voicevoice id (e.g. defne); required
languageoptional; detected from the text when omitted, 400 language_not_detected if that fails
formatmp3 (default) or wav
timingsnone (default) or sentence
settingsoptional: exaggeration, pace, temperature, seed (the same seed gives a similar result, not always an identical one)
asynctrue: 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.captions

Python

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.

Download 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:

400missing_input
400input_too_long
400voice_not_found
400language_not_supported
400language_not_detected
400unsupported_parameter
400invalid_settings
400content_blocked
400invalid_idempotency_key
400invalid_body
404job_not_found
409idempotency_conflict
429insufficient_balance
429key_spend_limit
429key_daily_limit
429rate_limited
502render_failed
503engine_unavailable