تبدیل متن به گفتار
ساخت فایل صوتی از متن با API سازگار با OpenAI: یک درخواست، یک فایل mp3 یا wav
مستندات
یک درخواست، یک فایل
متن را به https://api-ai.hibanacloud.ir/v1/audio/speech میفرستید و فایل صوتی را در همان درخواست پس میگیرید. پاسخ JSON نیست؛ خود بایتهای صدا است (audio/mpeg، audio/wav یا pcm) و هزینه در هدرها میآید. API با OpenAI سازگار است، پس همان client.audio.speech.create رسمی OpenAI کار میکند و فقط نشانی پایه و کلید عوض میشود. کلید همان کلید API چت شماست.
ارائهدهنده صدا را کامل میسازد و بعد فایل را میفرستد، پس پاسخ تکهتکه (استریم) نیست و برای حدود ۱٬۲۵۰ کاراکتر ۱۵ تا ۲۰ ثانیه طول میکشد. تایماوت کلاینت را کوتاه نگذارید.
شروع سریع
نمونهٔ زیر یک جملهٔ فارسی را با صدای sarah میخواند و در speech.mp3 ذخیره میکند. نمونههای Python، Node.js، C# و Java با SDK رسمی OpenAI نوشته شدهاند. هر اجرا کمی هزینه دارد، پس قیمت مدل را در صفحهٔ آن ببینید.
curl https://api-ai.hibanacloud.ir/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "elevenlabs/eleven-v4-turbo", "voice": "sarah", "input": "سلام! به هیبانا خوش آمدید. این صدا با API تبدیل متن به گفتار ساخته شده است.", "response_format": "mp3" }' \ --output speech.mp3پارامترهای درخواست
| پارامتر | الزامی | نوع | توضیحات |
|---|---|---|---|
| model | بله | string | کد مدل صوتی، مثل elevenlabs/eleven-v4-turbo. نامهای OpenAI (tts-1، tts-1-hd، gpt-4o-mini-tts) هم پذیرفته میشوند. |
| input | بله | string / array | متنی که باید خوانده شود (حداکثر ۵۰۰۰ کاراکتر، در Gemini ۳۰۰۰). در مدلهای چندگوینده میتواند آرایهای از نوبتها به شکل {text, voice?, instructions?} باشد. |
| voice | خیر | string / {id} | نام صدا، مثل sarah، Kore یا English_CalmWoman، یا {"id": "..."}. خالی یعنی صدای پیشفرض مدل. نام صداهای OpenAI مثل alloy به صدای پیشفرض همان مدل تبدیل میشود. |
| instructions | خیر | string | لحن و سبک خواندن (مدلهای Gemini TTS). جزو کاراکترهای قابل پرداخت نیست. |
| response_format | خیر | string | یکی از mp3، wav یا pcm. پیشفرض و قالبهای مجاز به مدل بستگی دارد (بخش «صداها و قالبها»). |
| speed | خیر | number | سرعت خواندن در مدلهایی که پشتیبانی میکنند (Gemini TTS و MiniMax). در مدلهای دیگر نادیده گرفته میشود. |
| stream_format | خیر | string | فقط audio (کل فایل وقتی آماده شد فرستاده میشود). مقدار sse پذیرفته نمیشود. |
| user | خیر | string | نادیده گرفته میشود. |
فیلدی که در جدول نیست با unknown_parameter رد میشود. هدر اختیاری Idempotency-Key را برای جلوگیری از ساخت (و پرداخت) دوباره در تلاش مجدد بفرستید؛ توضیحش در بخش «هزینه» و در کلید یکتایی است.
پاسخ و هدرها
بدنهٔ پاسخ فایل صوتی است؛ آن را مستقیم در یک فایل ذخیره کنید یا به پخشکننده بدهید. اطلاعات هزینه در هدرها میآید:
| هدر | معنی |
|---|---|
| Content-Type | audio/mpeg برای mp3، audio/wav برای wav و audio/pcm;rate=24000;channels=1 برای pcm. |
| Content-Length | اندازهٔ فایل؛ کل صدا یکجا فرستاده میشود. |
| X-Hibana-Cost-Rial | مبلغی که برای این درخواست از کیف پول کم شد (ریال). |
| X-Hibana-Characters | تعداد کاراکترهای قابل پرداخت متن ورودی. |
| X-Request-Id | شناسهٔ درخواست؛ برای پیگیری با پشتیبانی نگه دارید. |
HTTP/1.1 200 OKContent-Type: audio/mpegContent-Length: 61440X-Hibana-Cost-Rial: 37500X-Hibana-Characters: 1250X-Request-Id: req_...اعداد بالا نمونهاند. فایل pcm سرایند ندارد (۲۴ کیلوهرتز، تککاناله، ۱۶ بیت)؛ اگر فایل قابل پخش میخواهید wav یا mp3 بخواهید، یا خودتان تبدیل کنید:
ffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wavصداها و قالبها
صداها و قالبهای خروجی به خانوادهٔ مدل بستگی دارد. فهرست کامل صداها (با نمونهٔ صدا برای گوش دادن) در صفحهٔ هر مدل است؛ خلاصه:
| مدلها | صداها | قالبها | ویژگیها |
|---|---|---|---|
| ElevenLabs (elevenlabs/eleven-v4 و eleven-v4-turbo) | ۲۱ صدا، مثل sarah، george و adam؛ شناسهٔ صداهای دیگر ElevenLabs هم پذیرفته میشود | mp3 (پیشفرض)، wav، pcm | speed ندارد؛ بیش از ۹۰ زبان از جمله فارسی؛ برچسبهای صوتی مثل [whispers] در متن |
| Gemini TTS (google/gemini-3.8-flash-tts و flash-lite-tts) | ۳۰ صدا، مثل Kore، Puck و Zephyr | wav (پیشفرض) و pcm؛ mp3 خطای 400 است | instructions برای لحن، speed، و چندگوینده با input آرایهای؛ حداکثر ۳۰۰۰ کاراکتر |
| MiniMax (minimax/speech-2.8-hd و speech-2.8-turbo) | ۴۵ صدا، مثل English_CalmWoman؛ شناسهٔ صداهای دیگر MiniMax هم پذیرفته میشود | فقط mp3 | speed دارد؛ بیش از ۴۰ زبان از جمله فارسی؛ هر نویسهٔ چینی، ژاپنی و کرهای دو کاراکتر حساب میشود |
قالبهای opus، aac و flac پشتیبانی نمیشوند چون تبدیل قالب نداریم و خطای 400 unsupported_response_format میگیرید. صدا را بهصورت رشته ("voice": "sarah") یا شیء ({"id": "sarah"}) بدهید.
لحن و چندگوینده
مدلهای Gemini TTS با instructions لحن و سبک را میگیرند (مثلاً «آرام و گرم») و با input آرایهای گفتگوی چندنفره میسازند؛ هر نوبت صدای خودش را دارد. خروجی این مدلها wav یا pcm است. نمونه:
# مدلهای Gemini TTS فقط wav و pcm میدهند؛ mp3 خطای 400 است.# instructions لحن و سبک را تعیین میکند و کاراکتر حساب نمیشود.# input آرایهای از نوبتهاست؛ هر نوبت صدای خودش را دارد (چندگوینده).curl https://api-ai.hibanacloud.ir/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-3.8-flash-tts", "instructions": "Warm, relaxed conversation between two friends.", "input": [ {"text": "سلام، حالت چطوره؟", "voice": "Kore"}, {"text": "سلام! خوبم، ممنون. تو چطوری؟", "voice": "Puck"} ], "response_format": "wav" }' \ --output speech.wavشکل کلی input آرایهای:
{ "model": "google/gemini-3.8-flash-tts", "input": [ { "text": "سلام، حالت چطوره؟", "voice": "Kore" }, { "text": "سلام! خوبم، ممنون.", "voice": "Puck", "instructions": "cheerful" } ], "response_format": "wav"}مدلها
مدلهای تبدیل متن به گفتار در فهرست مدلها با دستهٔ «صدا» هستند. صفحهٔ هر مدل قیمت، صداها (با نمونهٔ صدا)، قالبها، سقف طول متن و پشتیبانی از لحن و سرعت را نشان میدهد. همین اطلاعات را با کلید API هم میتوانید بخوانید:
GET https://api-ai.hibanacloud.ir/v1/audio/speech/modelsاین فهرست مدلهای صوتی را با صداها، قالبها، محدودیتها و قیمت ریالی برمیگرداند.
هزینه
- قیمت: بیشتر مدلها بر اساس تعداد کاراکتر متن ورودی قیمت دارند (هر ۱۰۰۰ کاراکتر). مدلهای Gemini TTS بر اساس توکن متن و توکن صدا حساب میشوند (هر ثانیه صدا ۲۵ توکن). قیمت هر مدل در صفحهٔ همان مدل است.
- یک بار، پس از آماده شدن صدا: مبلغ فقط بعد از ساخته شدن فایل کم میشود و در
X-Hibana-Cost-Rialمیآید. اگر ساخت صدا شکست بخورد، چیزی کم نمیشود. - موجودی: کیف پول باید پیش از درخواست قیمت را پوشش دهد، وگرنه 402
insufficient_fundsمیگیرید و پیام خطا قیمت دقیق را میگوید. - قطع اتصال: اگر کلاینت پس از ارسال درخواست قطع شود، ارائهدهنده صدا را میسازد و هزینهاش را از ما میگیرد؛ پس مبلغ همچنان کم میشود.
- تلاش مجدد بدون پرداخت دوباره: درخواست را با هدر
Idempotency-Keyبفرستید؛ تا ۵۰ دقیقه، تکرار همان درخواست همان صدا را بدون هزینهٔ دوم پس میدهد. - کاراکتر: هر نویسهٔ یونیکد یک کاراکتر است و instructions شمرده نمیشود. در MiniMax هر نویسهٔ چینی، ژاپنی و کرهای دو کاراکتر حساب میشود. تعداد در
X-Hibana-Charactersاست.
توضیح کلی در قیمتگذاری آمده است.
خطاها
| HTTP | کد | معنی |
|---|---|---|
| 402 | insufficient_funds | موجودی کیف پول برای قیمت این متن کافی نیست. پیام خطا قیمت دقیق را میگوید. |
| 400 | unknown_parameter | فیلدی فرستادهاید که API نمیشناسد. برخلاف چت، فیلد ناشناس نادیده گرفته نمیشود و رد میشود. |
| 400 | unsupported_parameter | provider، input_references (کلون صدا) و stream_format با مقدار sse پشتیبانی نمیشوند. |
| 400 | unsupported_response_format | قالب opus، aac یا flac خواستهاید. تبدیل قالب نداریم؛ mp3، wav یا pcm بخواهید. |
| 400 | speech_model_requires_speech_endpoint | مدل صوتی را به chat/completions یا responses فرستادهاید؛ از /v1/audio/speech استفاده کنید. |
| 400 | کدهای اعتبارسنجی | مقدار نامعتبر، مثل قالبی که مدل نمیدهد (mp3 در Gemini TTS)، صدای ناشناس یا متن بلندتر از سقف مدل. فیلد param مشخص میکند کدام فیلد. |
شکل کلی پاسخ خطا و سیاست تلاش مجدد در مدیریت خطاها آمده است.
محدودیتها
| مورد | محدودیت |
|---|---|
| طول متن | حداکثر ۵۰۰۰ کاراکتر در هر درخواست، در Gemini TTS حداکثر ۳۰۰۰. متن بلندتر را به چند درخواست تقسیم کنید. |
| کاراکتر | هر نویسهٔ یونیکد متن ورودی یک کاراکتر است. instructions شمرده نمیشود. |
| زمان ساخت | ارائهدهنده صدا را کامل میسازد و بعد فایل را میفرستد؛ برای حدود ۱٬۲۵۰ کاراکتر ۱۵ تا ۲۰ ثانیه. |
| قالب pcm | ۲۴ کیلوهرتز، تککاناله، عدد صحیح ۱۶ بیتی علامتدار به ترتیب little-endian، بدون سرایند فایل. |
| کلید | ساخت صدا با کلید و کیف پول عادی انجام میشود؛ ورودی کلون صدا (input_references) پذیرفته نمیشود. |
چرا نه Chat Completions
مدل صوتی را به chat/completions یا responses نفرستید. این مدلها متن تولید نمیکنند و درخواست چت به آنها با خطای 400 speech_model_requires_speech_endpoint رد میشود. همیشه از /v1/audio/speech استفاده کنید.
جهت مخالف، یعنی تبدیل فایل صوتی به متن، در تبدیل گفتار به متن است، و اگر میخواهید مدل چت به یک صدا گوش دهد و دربارهٔ آن پاسخ دهد، ورودی صوت را ببینید.
سازگاری با OpenAI
کد موجود شما که از client.audio.speech.create با مدلهای OpenAI استفاده میکند، بدون تغییر کار میکند؛ فقط نشانی پایه و کلید را عوض کنید:
- نامهای
tts-1،tts-1-hdوgpt-4o-mini-ttsنام مستعار یک مدل پیشفرضاند که مدیر هیبانا انتخاب میکند (امروزelevenlabs/eleven-v4-turbo). - نام صدای OpenAI مثل
alloyبه صدای پیشفرض همان مدل تبدیل میشود. speedدر مدلی که پشتیبانی نمیکند حذف میشود، نه خطا.- اما فیلدهایی که در OpenAI وجود ندارند یا ما نمیدهیم (مثل
provider) با خطای 400 رد میشوند.
پرسشهای متداول
فارسی را هم میخواند؟
بله. ElevenLabs (بیش از ۹۰ زبان) و MiniMax (بیش از ۴۰ زبان) فارسی را پشتیبانی میکنند. صدا را با یک جملهٔ کوتاه امتحان کنید و در صفحهٔ هر مدل نمونهٔ صداها را گوش دهید.
پاسخ چرا بلافاصله نمیآید؟
ارائهدهنده صدا را کامل میسازد و بعد فایل را میفرستد. برای حدود ۱٬۲۵۰ کاراکتر ۱۵ تا ۲۰ ثانیه صبر لازم است و استریم صدا نداریم.
اگر ساخت شکست بخورد پولم چه میشود؟
مبلغ فقط بعد از آماده شدن صدا کم میشود، پس برای درخواست ناموفق چیزی کم نمیشود.
اگر اتصال قطع شود و درخواست را دوباره بفرستم دو بار پول میدهم؟
اگر قطع پس از ارسال درخواست بوده، ساخت صدا انجام شده و هزینهاش کم میشود. برای تلاش مجدد بدون هزینهٔ دوم، هدر Idempotency-Key بفرستید؛ تا ۵۰ دقیقه همان صدا بازگردانده میشود.
میتوانم صدای خودم را کلون کنم؟
نه. input_references (کلون صدا) پشتیبانی نمیشود و 400 unsupported_parameter میگیرید.
با SDK رسمی OpenAI کار میکند؟
بله. client.audio.speech.create در Python و Node.js، AudioClient.GenerateSpeech در .NET و client.audio().speech().create در Java با همان کد (فقط نشانی پایه و کلید هیبانا) کار میکنند.
از بلاگ هیبانا
- تبدیل متن به گفتار فارسی با API؛ آزمایش شش مدل و نمونهکد پایتون
متن فارسی را با API هیبانا به فایل صوتی تبدیل کنید؛ آزمایش واقعی شش مدل ElevenLabs، Gemini و MiniMax با هزینه، سرعت و خواندن عدد و تاریخ، همراه نمونهکد پایتون.