رفتن به محتوای اصلی
بنانا AI
مستندات APIمسیرهاText to Speech

متن به گفتار (Text to Speech)

متن فارسی یا انگلیسی را با گویندگان فارسی‌زبان به صدا تبدیل کنید؛ تک‌گوینده یا دیالوگ چندنفره با تگ‌های حسی. فایل صوتی همان لحظه برمی‌گردد.

مسیر درخواست

POSThttps://bananaai.ir/api/v1/audio/speech

برخلاف عکس و ویدیو، این مسیر همگام است: درخواست تا ساخته شدن صدا باز می‌ماند (معمولاً چند ثانیه) و پاسخ مستقیماً نشانی فایل MP3 را دارد. تسک ساخته‌شده هم با وضعیت completed در فهرست تسک‌ها ثبت می‌شود.

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

بدنهٔ درخواست باید JSON باشد. یکی از text (تک‌گوینده) یا turns (دیالوگ) را بفرستید.

textstringاختیاری
متنی که خوانده می‌شود؛ حداکثر ۲٬۵۰۰ کاراکتر. برای جهت‌دادن به لحن، تگ‌های صوتی انگلیسی داخل [ ] بگذارید؛ مثل [happily]، [whispers] یا [calmly].
مثال:[excitedly] سلام! به بنانا خوش آمدید.
voice_idstringاختیاری
شناسهٔ گوینده. فهرست کامل در گویندگان و در GET /api/v1/models?type=audio.
پیش‌فرض:rNb3hdSf0n4ROIbYC8Bl
turnsobject[]اختیاری
برای دیالوگ: آرایه‌ای از {text, voice_id}؛ ۲ تا ۲۰ نوبت، حداکثر ۱۰ گوینده و ۲٬۰۰۰ کاراکتر در مجموع. اگر turns بفرستید text و voice_id نادیده گرفته می‌شوند.
stabilitynumberاختیاری
۰ بیانگر (بیشترین حس)، ۰٫۵ طبیعی، ۱ ثابت و یکدست. اگر متن تگ صوتی داشته باشد خودکار ۰ می‌شود تا تگ‌ها اثر کنند.
پیش‌فرض:0.5مقادیر مجاز:00.51
metadataobjectاختیاری
جفت‌های کلید/مقدار دلخواه (تا ۱۶ کلید، مقدار حداکثر ۵۰۰ کاراکتر) مثل شناسهٔ سفارش شما. در پاسخ تسک و بدنهٔ وب‌هوک عیناً برمی‌گردد تا نتیجه را به رکورد خودتان وصل کنید.
مثال:{"order_id":"1042"}

هزینه

هر ۳۰ کاراکتر (رو به بالا) یک اعتبار؛ مثلاً متن ۵۶۰ کاراکتری ۱۹ اعتبار. جزئیات در اعتبار و هزینه.

گویندگان

همهٔ گویندگان لهجهٔ فارسی تهرانی دارند و برای متن فارسی بهترین نتیجه را می‌دهند.

voice_idنامجنسیتسبک
rNb3hdSf0n4ROIbYC8Blشهراممردمستند و روایی
NZiuR1C6kVMSWHG27sIMنوشینزنشوخ و لطیف
WwAjIyMBDBNl1dvId9Xeنازیزنقصه‌گو و گرم
PleK417YVMP2SUWm8Btbامیرمردآرام و صمیمی
0CM1acfSP05Da4eiVeZLمریمزنآموزشی و دقیق
3AA408tBxTzz5dPx3TsRایمانمردآرام و آموزشی
WXMb6G4d3xpdkOSusiLgهستیزنشاد و تبلیغاتی
vxpDwAUruwpDtekhzRHLبهراممردجاافتاده و پخته
SAC3BW43jtuoWxSVzyBhکیانمردگفتگوی روزمره
POwVdSos0GhCqrEpT9A1رامینمردگرم و تبلیغاتی
HMSLvUqJiRQD6keNv4Q9مینازنادبی و آرام
W7gM1dm8sqf5LMw4l3hHندازنتبلیغ روزمره
OJmdcNwQdLgLsbZyazAhسعیدمردگوینده اخبار
0GSMOiyPyqafPvCG94Auخسرومردراوی تاریخ
GkbmgDaR83yKKH5MmcM3مهینزنشب‌نشین مهربان
5WYc04e0KiiHeOTGOhHhسورناخنثیجنایی آرام

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

bash
curl -X POST "https://bananaai.ir/api/v1/audio/speech" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "[happily] سلام! به بنانا خوش آمدید. ایده‌تان را بنویسید، بقیه‌اش با ما.",
  "voice_id": "NZiuR1C6kVMSWHG27sIM"
}'

دیالوگ چندنفره

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

bash
curl -X POST "https://bananaai.ir/api/v1/audio/speech" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "turns": [
    {
      "voice_id": "NZiuR1C6kVMSWHG27sIM",
      "text": "[excitedly] باور نمی‌کنم اینقدر سریع آماده شد!"
    },
    {
      "voice_id": "PleK417YVMP2SUWm8Btb",
      "text": "[calmly] گفتم که می‌شه. فقط باید متن رو ساده نگه داریم."
    }
  ]
}'

پاسخ

JSON
1{
2  "id": "tts-3f0c9a52-8a3e-4d8e-9d4b-1a2f3e4d5c6b",
3  "status": "completed",
4  "type": "audio",
5  "model": "eleven_v4",
6  "prompt": "[happily] سلام! به بنانا خوش آمدید...",
7  "images": [],
8  "videos": [],
9  "audios": ["https://cdn.bananaai.ir/.../speech.mp3"],
10  "error": null,
11  "credits_reserved": 3,
12  "credits_deducted": true,
13  "metadata": {},
14  "created_at": "2026-09-29T12:00:00.000Z",
15  "completed_at": "2026-09-29T12:00:04.000Z",
16  "audio_url": "https://cdn.bananaai.ir/.../speech.mp3",
17  "voice_ids": ["NZiuR1C6kVMSWHG27sIM"],
18  "stability": 0,
19  "character_count": 72,
20  "credits_charged": 3
21}

نشانی فایل در audio_url (و همان مقدار در audios) است. اگر ساخت صدا ناموفق شود، 500 با کد generation_failed برمی‌گردد و اعتباری کسر نمی‌شود.