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

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


> همگام است: متن در همان پاسخ برمی‌گردد. بسته به طول فایل تا حدود یک دقیقه طول می‌کشد؛ timeout کلاینت را دست‌کم ۱۲۰ ثانیه بگذارید.

## درخواست

- `audio_url` (required, string): نشانی عمومی https فایل صوتی یا ویدیویی؛ حداکثر 5 دقیقه و 100 مگابایت.
- `language` (optional, string): کد ISO-639-1 یا auto (پیش‌فرض).
  - examples: `auto`, `fa`, `en`, `ar`, `tr`, `de`, `fr`, `es`, `it`, `pt`, `ru`, `ja`, `ko`, `zh`, `hi`, `nl`, `pl`, `sv`, `id`, `uk`
- `diarize` (optional, boolean): تفکیک گوینده (پیش‌فرض false)؛ هر خط با شناسهٔ گوینده شروع می‌شود (speaker_0: …).
- `tag_audio_events` (optional, boolean): علامت‌گذاری رویدادهای غیرگفتاری مثل خنده (پیش‌فرض true).
- `metadata` (optional, object): جفت‌های کلید/مقدار دلخواه که در تسک و وب‌هوک برمی‌گردد.

هزینه: به ازای هر دقیقهٔ فایل (رو به بالا، حداقل ۱ دقیقه). مدت فایل روی سرور اندازه‌گیری می‌شود.

### نمونه curl

```bash
curl -X POST "https://api.bananaai.ir/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/interview.mp3","language":"fa","diarize":true}'
```

## پاسخ

```json
{
  "id": "stt-7b1d2c3e-...",
  "status": "completed",
  "type": "audio",
  "model": "scribe_v2",
  "text": "speaker_0: سلام، خوش آمدید...",
  "transcript_url": "https://cdn.bananaai.ir/.../transcript.txt",
  "language": "fa",
  "language_probability": 0.98,
  "duration_seconds": 84.2,
  "words": [
    { "text": "سلام،", "start": 0.12, "end": 0.58, "type": "word", "speaker_id": "speaker_0" }
  ],
  "credits_charged": 2
}
```