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

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

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

مسیر درخواست

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

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

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

بدنهٔ درخواست باید JSON باشد (Content-Type: application/json).

audio_urlstringالزامی
نشانی عمومی https فایل. MP3، WAV، AAC، M4A، OGG، WEBM یا MP4؛ حداکثر ۵ دقیقه و ۱۰۰ مگابایت.
مثال:https://example.com/interview.mp3
languagestringاختیاری
زبان گفتار (ISO-639-1). اگر مطمئن نیستید auto بگذارید تا خودکار تشخیص داده شود.
پیش‌فرض:autoمقادیر مجاز:autofaenartrdefresitptrujakozhhinlplsviduk
diarizebooleanاختیاری
تفکیک گوینده‌ها. اگر true باشد هر خط متن با شناسهٔ گوینده شروع می‌شود (speaker_0: …) و هر کلمه speaker_id دارد.
پیش‌فرض:false
tag_audio_eventsbooleanاختیاری
رویدادهای غیرگفتاری مثل (خنده) یا (تشویق) را هم در متن علامت بزند.
پیش‌فرض:true
metadataobjectاختیاری
جفت‌های کلید/مقدار دلخواه (تا ۱۶ کلید، مقدار حداکثر ۵۰۰ کاراکتر) مثل شناسهٔ سفارش شما. در پاسخ تسک و بدنهٔ وب‌هوک عیناً برمی‌گردد تا نتیجه را به رکورد خودتان وصل کنید.
مثال:{"order_id":"1042"}

هزینه

به ازای هر دقیقهٔ فایل (رو به بالا، حداقل ۱ دقیقه). مدت فایل را خودمان پس از دانلود اندازه می‌گیریم؛ جزئیات در اعتبار و هزینه.

دسترسی به فایل

فایل باید بدون ورود و مستقیماً قابل دانلود باشد. اگر دانلود نشود یا صدایی نداشته باشد، 400 با کد invalid_source برمی‌گردد و اعتباری کسر نمی‌شود.

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

bash
curl -X POST "https://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
1{
2  "id": "stt-7b1d2c3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
3  "status": "completed",
4  "type": "audio",
5  "model": "scribe_v2",
6  "prompt": "speaker_0: سلام، خوش آمدید...",
7  "images": [],
8  "videos": [],
9  "audios": ["https://cdn.bananaai.ir/.../interview.mp3"],
10  "error": null,
11  "credits_reserved": 2,
12  "credits_deducted": true,
13  "metadata": {},
14  "created_at": "2026-09-29T12:00:00.000Z",
15  "completed_at": "2026-09-29T12:00:09.000Z",
16  "text": "speaker_0: سلام، خوش آمدید...",
17  "transcript_url": "https://cdn.bananaai.ir/.../transcript.txt",
18  "language": "fa",
19  "language_probability": 0.98,
20  "duration_seconds": 84.2,
21  "words": [
22    { "text": "سلام،", "start": 0.12, "end": 0.58, "type": "word", "speaker_id": "speaker_0" },
23    { "text": " ", "start": 0.58, "end": 0.62, "type": "spacing", "speaker_id": "speaker_0" }
24  ],
25  "credits_charged": 2
26}
textstring
متن کامل.
transcript_urlstring
همان متن به‌صورت فایل txt برای دانلود.
languagestring
زبان تشخیص‌داده‌شده یا ارسالی.
wordsobject[]
کلمه‌ها با زمان شروع و پایان (ثانیه) برای ساخت زیرنویس؛ type یکی از word، spacing یا audio_event است.
audiosstring[]
نسخهٔ ذخیره‌شدهٔ فایل ورودی شما.