API تبدیل متن به صدا فارسی (TTS): انتخاب مدل، کد Python و هزینهٔ تومانی

اگر می‌خواهی اپ، سایت یا رباتت متن فارسی را با صدای طبیعی بخواند، به یک API تبدیل متن به صدا (TTS) نیاز داری: متن را می‌فرستی و یک فایل صوتی تحویل می‌گیری. در یوتاپن این کار با یک مسیر انجام می‌شود، POST /v1/audio/speech، که هم‌شکل API رسمی OpenAI است. یعنی با SDK رسمی OpenAI و فقط با عوض کردن base_url به حدود ۳۰ مدل گفتار از سازنده‌های مختلف می‌رسی و هزینه را از کیف پول تومانی می‌پردازی.

این راهنما برای برنامه‌نویس است. اول یک فایل صوتی واقعی می‌سازیم، بعد سراغ انتخاب مدل و صدا، روش محاسبهٔ هزینه و نکته‌هایی می‌رویم که خروجی فارسی را تمیزتر می‌کنند.

چرا خرید مستقیم API تبدیل متن به صدا از ایران سخت است

سازنده‌های اصلی مدل‌های گفتار اعتبار API را به دلار و با کارت بانکی بین‌المللی می‌فروشند. کارت ایرانی آنجا کار نمی‌کند و برای هر سازنده هم باید حساب و صورت‌حساب جدا داشته باشی. اگر بخواهی دو یا سه مدل را روی متن خودت مقایسه کنی، باید چند بار همین مسیر را بروی. کارت مجازی و حساب دوستِ خارج از کشور هم کارمزد تبدیل ارز دارند و هر لحظه ممکن است مسدود شوند. ریسک این راه‌ها را در راهنمای دسترسی به API مدل‌ها از ایران جدا بررسی کرده‌ایم.

در یوتاپن با شمارهٔ موبایل ایرانی ثبت‌نام می‌کنی، کیف پول را با درگاه زیبال به تومان شارژ می‌کنی و یک کلید sk-up- می‌سازی. همین کلید برای مدل‌های متنی، تصویر، ویدیو و گفتار کار می‌کند. آدرس api.uttapen.ir داخل ایران است و VPN لازم ندارد. مسیر بین‌المللی درخواست را زیرساخت ما در خارج از ایران مدیریت می‌کند، و فایل‌های صوتی ساخته‌شده روی سرور خودمان در ایران نگه داشته می‌شوند.

اولین فایل صوتی با Python

اگر کتابخانهٔ openai را نصب داری، این کد کافی است:

from openai import OpenAI

client = OpenAI(base_url="https://api.uttapen.ir/v1", api_key="sk-up-...")

audio = client.audio.speech.create(
    model="uttapen/auto-speech",      # برای متن فارسی، مدلی انتخاب می‌شود که فارسی را درست می‌خواند
    voice="",                         # خالی: صدای پیش‌فرض مدلی که انتخاب می‌شود
    input="سلام! به یوتاپن خوش آمدید.",
)
audio.write_to_file("hello.wav")  # متن فارسی به مدل Gemini می‌رسد که خروجی WAV می‌دهد

شناسهٔ uttapen/auto-speech یعنی انتخاب خودکار: اگر حدود یک‌سوم نویسه‌های متن یا بیشتر فارسی باشد، مدلی برداشته می‌شود که فارسی را درست می‌خواند. در جدول فعلی انتخاب خودکار، این مدل google/gemini-3.8-flash-tts است. وقتی انتخاب خودکار را به کار می‌بری، voice را خالی بگذار، چون از قبل نمی‌دانی کدام مدل انتخاب می‌شود و صدای هر مدل فقط روی خود همان مدل معتبر است. هزینهٔ تشخیص خودکار هم جدا حساب می‌شود، که معمولاً کمتر از یک تومان است.

همان درخواست با curl

با curl می‌توانی هدرهای پاسخ را هم ببینی. هزینهٔ درخواست و موجودی کیف پول در همین هدرها می‌آید:

curl https://api.uttapen.ir/v1/audio/speech \
  -H "Authorization: Bearer sk-up-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "google/gemini-3.8-flash-tts", "voice": "", "input": "سلام! به یوتاپن خوش آمدید.", "response_format": "wav"}' \
  -D headers.txt -o hello.wav

بعد از اجرا، headers.txt را باز کن. این چهار هدر را آنجا می‌بینی:

اگر ساخت فایل از چند دقیقه بیشتر طول بکشد، به‌جای فایل صوتی پاسخ 202 با یک شیء کار برمی‌گردد. نتیجه را بعداً با همان شناسه بگیر. نمونهٔ Node و جزئیات کامل‌تر در مستند تبدیل متن به گفتار آمده است.

فیلدها و قالب فایل خروجی

درخواست پنج فیلد دارد:

• model: شناسهٔ مدل، مثل google/gemini-3.8-flash-tts، یا uttapen/auto-speech.
• input: متنی که خوانده می‌شود، حداکثر ۵٬۰۰۰ نویسه در هر درخواست.
• voice: یکی از صداهای همان مدل. فهرست صداها در صفحهٔ هر مدل آمده است. اگر خالی بماند، صدای پیش‌فرض مدل استفاده می‌شود. اگر صدای نامعتبر بفرستی، خطای 400 با param: "voice" و چند نمونهٔ مجاز برمی‌گردد.
• response_format: mp3 (پیش‌فرض)، wav، opus، aac، flac یا pcm.
• speed: سرعت خواندن، از ۰٫۲۵ تا ۴.

یک نکتهٔ عملی: بعضی مدل‌ها خروجی را فقط به شکل صدای خام تولید می‌کنند. خانوادهٔ Gemini TTS در حال حاضر این‌طور است و برای آن‌ها فایل WAV برمی‌گردد، حتی اگر mp3 خواسته باشی. اگر pcm بخواهی، همان نمونه‌های خام می‌آیند. پس قبل از ذخیره، هدر Content-Type پاسخ را نگاه کن و پسوند فایل را بر اساس آن بگذار. اگر حجم برایت مهم است، فایل WAV را بعداً با ابزاری مثل ffmpeg به mp3 یا opus تبدیل کن.

لینک داخل X-Uttapen-Media-Url تا ۲۴ ساعت بدون کلید باز می‌شود و خود فایل ۳۰ روز روی سرور می‌ماند. فایلی را که بیش از این لازم داری دانلود کن و در فضای ذخیره‌سازی خودت نگه دار. متن درخواست‌هایی که از API می‌فرستی ذخیره نمی‌شود. توضیح کامل نگهداری فایل‌ها و محدودیت‌ها در مرور API رسانه آمده است.

کدام مدل TTS فارسی و کدام صدا را انتخاب کنم

همهٔ مدل‌های گفتار، با قیمت لحظه‌ای هر کدام، در صفحهٔ مدل‌های تبدیل متن به گفتار فهرست شده‌اند. قبل از نگاه به جدول، یک نکته را در نظر داشته باش: اینکه سازنده بگوید مدلش «چندزبانه» است، به این معنی نیست که فارسی را خوب می‌خواند. بعضی مدل‌ها طبق توضیح خود سازنده فقط انگلیسی می‌خوانند. Kokoro 82M هم هشت زبان را پشتیبانی می‌کند و فارسی جزو آن‌ها نیست. ما برای کیفیت خواندن فارسی رتبه‌بندی‌ای منتشر نکرده‌ایم. تنها ادعای ما این است که انتخاب خودکار برای متن فارسی مدلی را برمی‌دارد که فارسی را درست می‌خواند.

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

هزینهٔ API تبدیل متن به صدا چطور حساب می‌شود

قیمت مدل‌های متنی به‌ازای توکن است، ولی گفتار به‌ازای هر ۱٬۰۰۰ نویسهٔ متن ورودی قیمت‌گذاری می‌شود. دلیلش این است که سازنده‌های مدل‌های گفتار هزینهٔ هر درخواست را گزارش نمی‌کنند. برای همین، هزینه از این فرمول به دست می‌آید: قیمت منتشرشدهٔ مدل × تعداد نویسه‌ها. بعضی مدل‌ها، مثل خانوادهٔ Gemini TTS، خروجی صوتی را بر حسب توکن قیمت می‌دهند. برای آن‌ها یک تخمین ثابت از تعداد توکن صوتی به‌ازای هر نویسه به کار می‌رود، و به همین دلیل کنار قیمتشان در کاتالوگ کلمهٔ «حدود» آمده است.

چند قاعده که باید بدانی:

• پیش از اجرا، مبلغ برآوردشده از کیف پول رزرو می‌شود. اگر موجودی کافی نباشد، خطای 402 برمی‌گردد.
• درخواست ناموفق رایگان است. خطا، رد شدن به‌خاطر قوانین محتوا یا نرسیدن فایل، رزرو را کامل آزاد می‌کند.
• قیمت‌ها تومانی‌اند و با نرخ ارز و قیمت سازنده تغییر می‌کنند. به همین دلیل در این مقاله عدد ننوشته‌ایم. قیمت روز هر مدل را در صفحهٔ همان مدل یا در صفحهٔ قیمت‌ها ببین.

برای برآورد بودجه، تعداد نویسه‌های متنت را بشمار، بر هزار تقسیم کن و در قیمت هر ۱٬۰۰۰ نویسهٔ مدل ضرب کن. اگر با منطق قیمت‌گذاری توکنی مدل‌های متنی آشنا نیستی، مقالهٔ قیمت API مدل‌ها به تومان تفاوت این دو را روشن می‌کند.

نکته‌های متن فارسی برای خروجی بهتر

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

اعداد. معلوم نیست مدل «۱۴۰۵/۰۷/۱۶» را تاریخ بخواند یا کسر. شمارهٔ تلفن را هم ممکن است یک‌جا بخواند، نه رقم‌به‌رقم. هر جا نحوهٔ خواندن مهم است، عدد را خودت با حروف بنویس، مثلاً «شانزدهم مهر هزار و چهارصد و پنج». مبلغ، درصد و ساعت هم همین‌طورند. یادت باشد این کار تعداد نویسه‌ها را کمی بیشتر می‌کند و هزینه بر اساس همین نویسه‌ها حساب می‌شود.

مخفف‌ها و کلمه‌های لاتین. مخفف‌هایی مثل «ق.ظ» یا «ج.ا.ا» را باز کن. کلمهٔ انگلیسی وسط جملهٔ فارسی را یک بار به خط لاتین و یک بار به شکل فارسی‌نوشته امتحان کن و ببین کدام طبیعی‌تر خوانده می‌شود.

نقطه‌گذاری. ویرگول و نقطه جای مکث را به مدل نشان می‌دهند. جملهٔ خیلی بلند بدون نشانه معمولاً یکنواخت و نفس‌بُر خوانده می‌شود. اگر جمله را بشکنی، خواندنش طبیعی‌تر می‌شود.

کسرهٔ اضافه و اعراب. در خط فارسی کسرهٔ اضافه نوشته نمی‌شود و مدل باید آن را حدس بزند. کلمه‌هایی مثل «کرد» یا «مهر» هم چند خوانش دارند. اگر جایی خوانش اشتباه شنیدی، گذاشتن اعراب روی همان کلمه یا بازنویسی جمله را امتحان کن.

نیم‌فاصله و حروف عربی. «می‌شود» را با نیم‌فاصله بنویس، نه «میشود» یا «می شود». «ي» و «ك» عربی را که اغلب همراه متن کپی‌شده وارد می‌شوند به «ی» و «ک» فارسی تبدیل کن. این کار به‌خصوص برای متن‌هایی که از PDF یا سایت‌های قدیمی می‌آیند لازم است.

متن بلند. سقف هر درخواست ۵٬۰۰۰ نویسه است. متن بلند را در مرز جمله یا پاراگراف بشکن، نه وسط جمله. هر تکه را با همان مدل و صدا و speed بساز و فایل‌ها را پشت هم بچسبان. هم‌زمان حداکثر ۳ ساخت فعال مجاز است. پس برای کتاب صوتی یک صف ساده با سه کارگر بساز و Retry-After را در پاسخ‌های 429 و 503 رعایت کن.

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

سیستم تلفنی و IVR. پیام‌های منوی تلفنی مثل «برای پیگیری سفارش عدد یک را بزنید» را یک بار بساز و فایلش را ذخیره کن. برای پیام‌های ثابت، تولید دوباره در هر تماس فقط هزینهٔ اضافه است. سیستم‌های تلفنی معمولاً قالب و نرخ نمونه‌برداری مشخصی می‌خواهند، پس خروجی wav یا pcm را بگیر و با ffmpeg به قالب موردنیاز سیستم خودت تبدیل کن.

کتاب صوتی و پادکست. برای این کاربرد مدل و صدا را ثابت نگه دار، متن را با نکته‌های بخش قبل تمیز کن و آن را تکه‌تکه بساز. قبل از اینکه کل کتاب را بسازی، یک فصل را کامل گوش کن تا خطاهای تکراری خوانش را پیدا کنی و در متن اصلاح کنی. برای موسیقی آغاز و پایان پادکست هم API ساخت موسیقی را ببین.

دسترس‌پذیری. دکمهٔ «گوش کن» زیر مقاله‌های سایت به کاربر کم‌بینا و هر کسی که در راه است کمک می‌کند. فایل هر مقاله را یک بار بساز و روی سرور خودت نگه دار. لینک امضاشدهٔ ما ۲۴ ساعت اعتبار دارد و برای گذاشتن مستقیم در صفحه مناسب نیست.

پاسخ صوتی در ربات تلگرام. رباتی که جواب را به‌جای متن به شکل پیام صوتی بفرستد، برای خیلی از کاربرها راحت‌تر است. پاسخ مدل زبانی را به audio/speech بده و فایل را با sendVoice بفرست. تلگرام برای پیام صوتی قالب‌های مشخصی می‌پذیرد که ogg با کدک opus یکی از آن‌هاست، پس اگر مدلت WAV برگرداند، اول تبدیلش کن. برای ساخت خود ربات، راهنمای ربات تلگرام فارسی در ۳۰ دقیقه را ببین. اگر برای تولید متن پاسخ هم از مدل‌های گوگل استفاده می‌کنی، راهنمای API Gemini در ایران به کارت می‌آید.

پرسش‌های پرتکرار

آیا API تبدیل متن به صدای فارسی رایگان است؟

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

کدام مدل فارسی را بهتر می‌خواند؟

ما رتبه‌بندی کیفیت منتشر نکرده‌ایم. انتخاب خودکار (uttapen/auto-speech) برای متن فارسی مدلی را برمی‌دارد که فارسی را درست می‌خواند. اگر سلیقهٔ صدا برایت مهم است، دو یا سه مدل را با یک پاراگراف از متن خودت امتحان کن.

چرا فایلی که خواسته بودم mp3 باشد، WAV است؟

بعضی مدل‌ها، از جمله خانوادهٔ Gemini TTS، فقط صدای خام تولید می‌کنند و خروجی‌شان به شکل WAV برمی‌گردد. هدر Content-Type پاسخ را بخوان و پسوند فایل را بر اساس آن بگذار.

محدودیت طول متن چقدر است؟

هر درخواست حداکثر ۵٬۰۰۰ نویسه می‌گیرد، حتی اگر سقف خود مدل بالاتر باشد. متن بلندتر را در مرز جمله بشکن و تکه‌ها را جداگانه بساز.

آیا با همین API می‌شود صدا را به متن تبدیل کرد؟

نه. مسیر audio/speech فقط متن را به صدا تبدیل می‌کند، و در مستندات رسانهٔ فعلی مسیر جداگانه‌ای برای تبدیل گفتار به متن نیامده است.

فایل‌های صوتی کجا نگه داشته می‌شوند؟

روی سرور ما در ایران، به مدت ۳۰ روز. لینک هر فایل ۲۴ ساعت معتبر است و با GET /v1/uttapen/media/{id} می‌توانی لینک تازه بگیری.

از کجا شروع کنم

اگر اول می‌خواهی صدای مدل‌ها را بشنوی، یک متن فارسی را در استودیو بساز. اگر آماده‌ای کد بنویسی، وارد حساب شو، کیف پول را شارژ کن، یک کلید sk-up- بساز و نمونهٔ Python بالا را اجرا کن. اولین فایل صوتی‌ات چند ثانیه بعد آماده است.