Wiozen Voice API
Wiozen Voice seslerini kendi kodundan, Claude Code'dan ya da Claude'un bağlayıcılarından kullan. Anahtar ve sınırlar Wiozen API'de; ses Voice'ta üretilir. Paketin varsa API ve MCP ile üretimde de önce paketin harcanır, kalanı bakiyenden düşer.
Kimlik
Her istekte Authorization: Bearer sk-gw-…. Anahtarı Wiozen API panelinden alırsın; Voice anahtarı saklamaz.
Uçlar
POST /v1/voice/speech | Metni seslendirir. JSON döner: dosya adresleri, süre, karakter, istenirse cümle zamanları. |
GET /v1/voice/jobs/:id | Uzun işin durumu: queued, warming, running, done, failed. |
GET /v1/voice/voices | Ses listesi; ?language=, ?gender=, ?tone= ile süzülür. Ücretsiz. |
POST /v1/voice/estimate | Karakter, tahmini ücret ve süre, okunuşa çevrilmiş metin. Ses üretmez, ücretsiz. |
POST /v1/audio/speech | OpenAI uyumlu: model "wiozen-voice", ses baytlarını döndürür. speed yalnız 1. |
İstek alanları (/v1/voice/speech)
input | metin; zorunlu |
voice | ses kimliği (ör. defne); zorunlu |
language | isteğe bağlı; verilmezse metinden algılanır, algılanamazsa 400 language_not_detected |
format | mp3 (varsayılan) ya da wav |
timings | none (varsayılan) ya da sentence |
settings | isteğe bağlı: exaggeration, pace, temperature, seed (aynı tohum benzer sonuç verir, birebir aynı olmayabilir) |
async | true: uzun metin iş olarak döner (202), /v1/voice/jobs/:id ile beklenir |
Örnek istek
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"]
Aynı isteği iki kez ödememek için
Idempotency-Key başlığı (8–120 karakter, harf, rakam, :_-). Aynı anahtar ve aynı gövde 24 saat içinde ilk sonucu döndürür, yeniden ücret kesmez; aynı anahtar farklı gövdeyle gelirse 409 idempotency_conflict.
Yanıt
{
"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": [ … ] }
}Yanıtta ayrıca cost_usd (kesilen tutar, dolar) var. sample_rate motorun gerçek çıkış hızıdır, sabit değildir. Dosya adresleri anahtar istemez, 24 saat geçerli; dosyalar 30 gün saklanır.
Cümle zamanları
timings: "sentence" ile gelir. captions dizisi Remotion'ın @remotion/captions paketindeki Caption tipiyle aynı; altyazı bileşenine ya da createTikTokStyleCaptions işlevine doğrudan verilir. text senin yazdığın metindir. Kompozisyon süresi: Math.ceil(durationMs / 1000 * fps) kare.
{
"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 } ]
}
Claude ile kullan (MCP)
Claude Code
claude mcp add --transport http wiozen-voice https://api.wiozen.com/mcp \
--header "Authorization: Bearer ${WIOZEN_API_KEY}"Claude masaüstü ve claude.ai (özel bağlayıcı)
URL: https://api.wiozen.com/mcp
Header: Authorization: Bearer <WIOZEN_API_KEY>Araçlar: list_voices, estimate, synthesize, get_job, get_balance. synthesize iki dosya bağlantısı ve zamanlamayı döndürür; Claude Code dosyaları projeye kendisi indirir.
Claude skill'i
Remotion projesinde seslendirmeyi, dosyaların yerini ve kompozisyon süresini tek akışta kuran hazır talimat. ~/.claude/skills/wiozen-voice/SKILL.md olarak kaydet.
Sınırlar
- Eşzamanlı istekte en çok 4.096 karakter; daha uzun metin async ile en çok 50.000 karakter.
- Anahtar başına dakikada 20 istek, aynı anda 2 iş.
- Anahtar başına günlük Voice tavanı varsayılan $5; Wiozen API panelinden değişir.
- Başarısız üretim ücretsizdir.
Hatalar
Gövde OpenAI biçiminde: {"error":{"type","code","message"}}. Kodlar:
| 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 |