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

`POST https://api.bananaai.ir/api/v1/audio/speech`


> همگام است: پاسخ مستقیماً نشانی فایل MP3 را در `audio_url` (و در `audios`) دارد. نیازی به polling نیست.

## درخواست

- `text` (optional, string): متن (حداکثر 2500 کاراکتر). تگ‌های صوتی انگلیسی داخل [ ] لحن را تغییر می‌دهند، مثل [happily] یا [whispers]. یکی از text یا turns الزامی است.
- `voice_id` (optional, string): شناسهٔ گوینده؛ پیش‌فرض `rNb3hdSf0n4ROIbYC8Bl`.
- `turns` (optional, object[]): دیالوگ: آرایهٔ {text, voice_id}؛ 2 تا 20 نوبت، حداکثر 10 گوینده و 2000 کاراکتر در مجموع.
- `stability` (optional, number): ۰ بیانگر، ۰٫۵ طبیعی (پیش‌فرض)، ۱ ثابت. اگر متن تگ صوتی داشته باشد خودکار ۰ می‌شود.
  - examples: `0`, `0.5`, `1`
- `metadata` (optional, object): جفت‌های کلید/مقدار دلخواه که در تسک و وب‌هوک برمی‌گردد.

هزینه: هر 30 کاراکتر (رو به بالا) یک اعتبار.

### نمونه curl

```bash
curl -X POST "https://api.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"}'
```

## گویندگان

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

## پاسخ

```json
{
  "id": "tts-3f0c9a52-...",
  "status": "completed",
  "type": "audio",
  "model": "eleven_v4",
  "audios": ["https://cdn.bananaai.ir/.../speech.mp3"],
  "audio_url": "https://cdn.bananaai.ir/.../speech.mp3",
  "voice_ids": ["NZiuR1C6kVMSWHG27sIM"],
  "stability": 0,
  "character_count": 36,
  "credits_charged": 2
}
```