تبدیل متن به گفتار (GET)
متن فارسی ← فایل صوتی ۸ کیلوهرتز برای IVR و VoIP؛ مناسب آدرس ttsUrl سانترال.
https://api.irnoti.com/v1/tts/sayمتن فارسی را به فایل صوتی تک‌کانالهٔ آمادهٔ سانترال تبدیل می‌کند و **خود فایل** را برمی‌گرداند (نه JSON). روی دامنهٔ اختصاصی همین سرویس، همین عملیات با مسیر کوتاه https://tts.irnoti.com/say?text=... هم در دسترس است.
**هزینه:** به‌ازای هر حرفِ جملهٔ تازه (با حداقل هر جمله). هر جملهٔ تکراری (همان متن، صدا و قالب) برای شما فقط یک‌بار حساب می‌شود، حتی اگر سانترال صدها بار آن را بگیرد. متن داخل [ ] و ( ) و علائم مارک‌داون خوانده و حساب نمی‌شود.
**بدون کلید:** درخواست بدون key آزمایش رایگان است (متن کوتاه، محدودیت نرخ و سقف روزانهٔ پلتفرم). **با کلید:** هزینه از کیف پول صاحب کلید کم می‌شود؛ کلید آزمایشی (Sandbox) صدای آزمایشی می‌دهد و هزینه‌ای ندارد.
**امنیت:** سانترال‌ها معمولاً فقط می‌توانند آدرس باز کنند، پس کلید را می‌توان در key= گذاشت؛ برای کلید حتماً فهرست IP مجاز تعریف کنید. در برنامه‌ها از هدر Authorization: Bearer استفاده کنید.
**هدرهای پاسخ:** X-TTS-Chars (حرف‌های خوانده‌شده)، X-TTS-Price (ریال؛ ۰ برای دریافت مجدد)، X-TTS-Duration-Ms. پاسخ برای یک روز قابل کش است.
پارامترها
| نام | محل | نوع | توضیح |
|---|---|---|---|
| text * | query | string | متن فارسی؛ حداکثر ۱۵۰۰ حرف (تنظیم سامانه؛ در آزمایش رایگان کوتاه‌تر). |
| voice | query | string | شناسهٔ صدا مثل char_teacher_lady؛ فهرست در GET /public/tts/info. پیش‌فرض: صدای پیش‌فرض سامانه. |
| format | query | string | wav8k (پیش‌فرض)، wav16k، sln، ulaw یا alaw. |
| key | query | string | کلید API با دامنهٔ tts.say (به‌جای هدر Authorization، برای سانترال‌ها). |
خطاهای خاص این endpoint
| 401 | unauthorized | کلید نامعتبر است، یا آزمایش رایگان بسته شده و کلیدی نفرستاده‌اید (key_required). |
| 402 | insufficient_balance | اعتبار برای این جمله کافی نیست؛ قبل از تولید صدا رد می‌شود و هزینه‌ای ندارد. |
| 403 | forbidden | کلید دامنهٔ tts.say ندارد یا ویژگی TTS برای حساب شما فعال نیست. |
| 409 | kyc_required | احراز هویت تأیید نشده است. |
| 422 | text_too_long | متن از سقف مجاز طولانی‌تر است (در آزمایش رایگان کوتاه‌تر). |
| 422 | empty_text | متن چیزی برای خواندن ندارد (مثلاً فقط توضیح داخل [ ] یا ( ) است). |
| 422 | unknown_voice | صدای خواسته‌شده در دسترس نیست؛ فهرست را از GET /public/tts/info بگیرید. |
| 422 | unknown_format | قالب خواسته‌شده در دسترس نیست. |
| 422 | daily_limit | سقف حرف روزانهٔ کلید پر شده است. |
| 429 | demo_limit | سقف روزانهٔ آزمایش رایگان پر شده است یا درخواست‌ها در دقیقه زیاد بوده؛ با کلید API ادامه دهید. |
| 502 | tts_failed | موتور صدا پاسخ نداد؛ هزینه‌ای کم نشده است، دوباره تلاش کنید. |
| 503 | tts_disabled | سرویس موقتاً غیرفعال است. |
اجرای زنده (محیط تست)
باز کردن در کنسول کامل ←با یک کلید آزمایشی (در پنل ← وب‌سرویس ← «کلید آزمایشی») این درخواست را همین‌جا اجرا کنید. پیام واقعی ارسال نمی‌شود و هزینه‌ای کسر نمی‌شود.