رفتن به محتوا

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

ساخت فایل صوتی از متن با 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

پارامترهای درخواست

پارامترهای POST /v1/audio/speech
پارامترالزامینوعتوضیحات
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-Typeaudio/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، pcmspeed ندارد؛ بیش از ۹۰ زبان از جمله فارسی؛ برچسب‌های صوتی مثل [whispers] در متن
Gemini TTS (google/gemini-3.8-flash-tts و flash-lite-tts)۳۰ صدا، مثل Kore، Puck و Zephyrwav (پیش‌فرض) و pcm؛ mp3 خطای 400 استinstructions برای لحن، speed، و چندگوینده با input آرایه‌ای؛ حداکثر ۳۰۰۰ کاراکتر
MiniMax (minimax/speech-2.8-hd و speech-2.8-turbo)۴۵ صدا، مثل English_CalmWoman؛ شناسهٔ صداهای دیگر MiniMax هم پذیرفته می‌شودفقط mp3speed دارد؛ بیش از ۴۰ زبان از جمله فارسی؛ هر نویسهٔ چینی، ژاپنی و کره‌ای دو کاراکتر حساب می‌شود

قالب‌های 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 است.

توضیح کلی در قیمت‌گذاری آمده است.

خطاها

خطاهای API تبدیل متن به گفتار
HTTPکدمعنی
402insufficient_fundsموجودی کیف پول برای قیمت این متن کافی نیست. پیام خطا قیمت دقیق را می‌گوید.
400unknown_parameterفیلدی فرستاده‌اید که API نمی‌شناسد. برخلاف چت، فیلد ناشناس نادیده گرفته نمی‌شود و رد می‌شود.
400unsupported_parameterprovider، input_references (کلون صدا) و stream_format با مقدار sse پشتیبانی نمی‌شوند.
400unsupported_response_formatقالب opus، aac یا flac خواسته‌اید. تبدیل قالب نداریم؛ mp3، wav یا pcm بخواهید.
400speech_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 با همان کد (فقط نشانی پایه و کلید هیبانا) کار می‌کنند.

از بلاگ هیبانا