تبدیل متن به گفتار

با endpoint تبدیل متن به گفتار (TTS) می‌توانید متن را به فایل صوتی تبدیل کنید. هوشوانا هم مدل‌های صوتی OpenAI و هم صداهای ElevenLabs را از طریق یک API سازگار با OpenAI در اختیارتان می‌گذارد.

POST https://hooshvana.ir/api/v1/audio/speech

پارامترها

صداها

نام صداها

نام‌های استاندارد alloy، echo، fable، onyx، nova و shimmer پشتیبانی می‌شوند تا کدهای سازگار با OpenAI بدون تغییر کار کنند. بهترین راه انتخاب، شنیدن چند نمونه با متن واقعی خودتان است.

صداهای ElevenLabs

وقتی مدل ElevenLabs (مثل elevenlabs/eleven_multilingual_v2) را انتخاب می‌کنید، در voice می‌توانید نام یا شناسه‌ی (voice_id) یکی از صداهای ElevenLabs را بفرستید. اگر یکی از نام‌های صدای OpenAI (مثل nova) را بفرستید، هوشوانا آن را به یک صدای مشابه ElevenLabs نگاشت می‌کند تا کد موجودتان بدون تغییر کار کند.

پشتیبانی از زبان فارسی

• elevenlabs/eleven_multilingual_v2 یک مدل چندزبانه است که فارسی را هم پشتیبانی می‌کند و معمولاً طبیعی‌ترین تلفظ فارسی را دارد.
• elevenlabs/eleven_v3 جدیدترین مدل است و بهترین کیفیت فارسی را دارد.

چون کیفیت خواندن فارسی به متن، صدا و حتی علائم نگارشی بستگی دارد، پیشنهاد می‌کنیم قبل از استفاده در تولید، چند جمله‌ی نمونه از محتوای واقعی خودتان را با چند مدل و صدا امتحان کنید. چند نکته برای نتیجه‌ی بهتر:

• اعداد را با حروف بنویسید یا مطمئن شوید شکل خوانده‌شده‌شان درست است («۱۴۰۳» ممکن است رقم‌به‌رقم خوانده شود).
• کلمات مبهم را با اعراب یا املای واضح‌تر بنویسید.
• از نقطه و ویرگول برای مکث طبیعی استفاده کنید.
• نیم‌فاصله‌ها را درست بگذارید تا کلمات مرکب درست خوانده شوند.

درخواست با cURL

curl https://hooshvana.ir/api/v1/audio/speech \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/eleven_multilingual_v2",
    "input": "سلام! به هوشوانا خوش آمدید. امیدواریم تجربه‌ی خوبی داشته باشید.",
    "voice": "nova",
    "response_format": "mp3"
  }' \
  --output welcome.mp3

پاسخ این endpoint خود فایل صوتی (داده‌ی باینری) است، نه JSON. در صورت خطا، پاسخ JSON با قالب استاندارد خطاها برمی‌گردد.

Python: استریم مستقیم در فایل

برای متن‌های طولانی بهتر است صدا را به صورت استریم بگیرید و مستقیم در فایل بنویسید تا کل فایل در حافظه نماند:

import os
from openai import OpenAI

client = OpenAI(base_url="https://hooshvana.ir/api/v1", api_key=os.environ["HOOSHVANA_API_KEY"])

text = "این یک نمونه‌ی آزمایشی برای تبدیل متن فارسی به گفتار است."

with client.audio.speech.with_streaming_response.create(
    model="elevenlabs/eleven_v3",
    voice="alloy",
    input=text,
    response_format="mp3",
) as response:
    response.stream_to_file("sample.mp3")

print("saved sample.mp3")

Node.js

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hooshvana.ir/api/v1",
  apiKey: process.env.HOOSHVANA_API_KEY,
});

const response = await client.audio.speech.create({
  model: "elevenlabs/eleven_multilingual_v2",
  voice: "shimmer",
  input: "سفارش شما ثبت شد و تا دو روز کاری ارسال می‌شود.",
  response_format: "mp3",
});

await fs.writeFile("order.mp3", Buffer.from(await response.arrayBuffer()));

قالب‌های خروجی

متن‌های طولانی

هر درخواست محدودیت طول ورودی دارد (بسته به مدل، چند هزار نویسه). برای کتاب صوتی یا مقاله‌های طولانی، متن را در مرز جمله‌ها یا پاراگراف‌ها تقسیم کنید، هر بخش را جداگانه بسازید و فایل‌ها را به هم بچسبانید. برای یکدست ماندن صدا، در همه‌ی بخش‌ها از یک مدل و یک صدا استفاده کنید.

هزینه

هزینه‌ی تبدیل متن به گفتار به ازای تعداد نویسه‌های ورودی محاسبه می‌شود (قیمت‌ها برای هر یک میلیون نویسه اعلام می‌شوند). فاصله‌ها و علائم نگارشی هم نویسه حساب می‌شوند. مثلاً متنی ۱۰۰۰ نویسه‌ای، یک‌هزارم قیمت اعلام‌شده برای یک میلیون نویسه هزینه دارد. صداهای ElevenLabs و مدل‌های OpenAI قیمت متفاوتی دارند. قیمت هر مدل را در صفحه‌ی قیمت‌ها ببینید.

برای کاهش هزینه، صداهای پرتکرار (مثل پیام‌های ثابت سیستم تلفنی یا اعلان‌ها) را یک بار بسازید و فایل را ذخیره کنید، نه این‌که هر بار دوباره تولید شوند.

گام بعدی

برای مسیر برعکس، یعنی تبدیل صدا به متن، تبدیل گفتار به متن را ببینید.