تبدیل گفتار فارسی به متن با API؛ از پیام صوتی تا متن قابل جست‌وجو

هیبانا دو مسیر جدا برای صدا دارد و بهتر است از اول بدانید کدام را لازم دارید:

• تبدیل گفتار به متن با POST /v1/audio/transcriptions: یک فایل صوتی می‌فرستید و فقط متن آن را می‌گیرید. این endpoint با Whisper در OpenAI سازگار است؛ یعنی همان client.audio.transcriptions.create در SDK رسمی کار می‌کند.
• ورودی صوت در Chat Completions: صدا را کنار یک پیام متنی می‌فرستید و مدل دربارهٔ آن پاسخ می‌دهد؛ مثلاً خلاصه‌اش می‌کند یا به سؤالی دربارهٔ آن جواب می‌دهد.

اگر «فقط متن» می‌خواهید، مسیر اول ساده‌تر است. موضوع اصلی این مطلب همین مسیر است و در بخش آخر سراغ مسیر دوم هم می‌رویم.

در هر دو مسیر باید مدلی را انتخاب کنید که در کاتالوگ قابلیت «ورودی صوت» دارد. چند نمونه از لیست مدل‌ها با فیلتر ورودی صوت، با قیمت‌ها به تومان و به‌ازای هر یک میلیون توکن، در زمان نگارش این مطلب:

ما همهٔ نمونه‌های این مطلب را با Gemini 3.7 Flash اجرا کرده‌ایم و دربارهٔ کیفیت فارسی بقیهٔ مدل‌ها ادعایی نداریم. قیمت‌ها تغییر می‌کنند؛ قیمت به‌روز را در صفحهٔ هر مدل ببینید.

برای آزمایش، یک کلیپ ۹ ثانیه‌ای فارسی را خودمان با موتور متن‌باز تبدیل متن به گفتار Piper و صدای فارسی fa_IR-amir ساختیم؛ متن آن یک پیام پشتیبانی ساده بود. صدای مصنوعی تمیزتر از ضبط واقعی است، پس نتیجهٔ شما با نویز، لهجه یا چند گوینده ممکن است متفاوت باشد.

اول pip install openai را اجرا کنید. بعد:

from openai import OpenAI client = OpenAI(    base_url="https://api-ai.hibanacloud.ir/v1",    api_key="YOUR_API_KEY",) with open("voice.mp3", "rb") as audio:    result = client.audio.transcriptions.create(        model="google/gemini-3.7-flash",        file=audio,        language="fa",    ) print(result.text)print(result.usage)

خروجی در اجرای ما:

سلام وقت بخیر سفارش شماره ۴۸۲۱ من هنوز نرسیده لطفاً تا فردا ساعت ۱۰ صبح با من تماس بگیریدUsageTokens(input_tokens=316, output_tokens=155, total_tokens=471, type='tokens', input_token_details=UsageTokensInputTokenDetails(audio_tokens=232, text_tokens=84), cost_rial=3115)

مدل عددی را که در صدا با حروف گفته شده بود («چهار هزار و هشتصد و بیست و یک») به رقم نوشت. در این اجرا علامت‌گذاری نداشت و «نرسیده است» را «نرسیده» نوشت؛ یعنی خروجی نزدیک به گفتار است، نه کلمه‌به‌کلمه. هزینهٔ این درخواست ۳٬۱۱۵ ریال بود.

اگر می‌خواهید پاسخ فقط یک رشته باشد، response_format="text" بدهید. فرمت‌های زمان‌دار یعنی srt، vtt و verbose_json پشتیبانی نمی‌شوند؛ درخواست ما با srt این خطا را برگرداند:

400 response_format 'srt' is not supported. Use 'json' or 'text' (timestamps — srt, vtt, verbose_json — are not available).

پس برای ساختن زیرنویس زمان‌دار، این endpoint به‌تنهایی کافی نیست.

درخواست از نوع multipart/form-data است، نه JSON. با curl:

curl https://api-ai.hibanacloud.ir/v1/audio/transcriptions \  -H "Authorization: Bearer YOUR_API_KEY" \  -F model=google/gemini-3.7-flash \  -F language=fa \  -F response_format=text \  -F file=@voice.mp3

خروجی همان متن بود، این بار با نقطه:

سلام وقت بخیر. سفارش شماره ۴۸۲۱ من هنوز نرسیده. لطفاً تا فردا ساعت ۱۰ صبح با من تماس بگیرید.

مدل اسم‌هایی را که نمی‌شناسد حدس می‌زند. کلیپ دوم ما این جمله بود: «برای اتصال به هیبانا، کلید ای پی آی را در متغیر محیطی بگذارید و مدل جمنای تری پوینت سون فلش را انتخاب کنید.» بدون prompt، دو اجرای جداگانه این‌ها را برگرداند:

برای اتصال به گیواها، کلید ای‌پی‌آی رو در متغیر محیطی بگذارید و مدل جنای تری پوینت سون فلش رو انتخاب کنید.برای اتصال به هیوانا کلید ای‌پی‌آی رو در متغیر محیطی بگذارید و مدل جن‌آی تری‌پوینت‌سون فلش رو انتخاب کنید.

حالا همان فایل با فهرست کوتاهی از واژه‌های درست در prompt:

with open("tech.wav", "rb") as audio:    result = client.audio.transcriptions.create(        model="google/gemini-3.7-flash",        file=audio,        language="fa",        prompt="هیبانا، API، Gemini 3.7 Flash",    )print(result.text)

برای اتصال به هیبانا کلید API رو در متغیر محیطی بذارید و مدل Gemini 3.7 Flash رو انتخاب کنین

اسم‌ها درست شدند. اما به «رو»، «بذارید» و «کنین» دقت کنید: این شکل‌های محاوره‌ای در متنی که ما به موتور تبدیل متن به گفتار داده بودیم نبود. اگر متن رسمی لازم دارید، یک مرحلهٔ ویرایش با یک مدل چت بعد از تبدیل اضافه کنید.

طبق مستندات تبدیل گفتار به متن، حجم هر فایل حداکثر ۲۵ مگابایت هنگام آپلود و ۲۰ مگابایت پس از رمزگشایی است. گوگل در مستندات صوت Gemini می‌نویسد صدا پیش از پردازش به ۱۶ کیلوبیت‌برثانیه کاهش می‌یابد و چند کانال به یک کانال ادغام می‌شود؛ پس بیت‌ریت بالا مزیتی ندارد و وضوح خود ضبط، یعنی نویز کم و صدای روشن، مهم‌تر است. فایل را تک‌کاناله و کم‌حجم کنید و اگر طولانی است، با ffmpeg تکه‌تکه کنید:

import glob, os, subprocessfrom openai import OpenAI client = OpenAI(base_url="https://api-ai.hibanacloud.ir/v1", api_key="YOUR_API_KEY") SOURCE = "long.wav"SEGMENT_SECONDS = 600  # ده دقیقه os.makedirs("chunks", exist_ok=True)subprocess.run([    "ffmpeg", "-y", "-loglevel", "error", "-i", SOURCE,    "-ac", "1", "-ar", "16000", "-b:a", "48k",    "-f", "segment", "-segment_time", str(SEGMENT_SECONDS),    "chunks/part_%03d.mp3",], check=True) parts, total_cost = [], 0for path in sorted(glob.glob("chunks/part_*.mp3")):    with open(path, "rb") as audio:        r = client.audio.transcriptions.create(            model="google/gemini-3.7-flash", file=audio, language="fa",            prompt="هیبانا، API، Gemini 3.7 Flash",        )    if not r.text.strip():        print("هشدار: متن خالی برای", path)    parts.append(r.text.strip())    total_cost += r.usage.cost_rial print("\n".join(parts))print("cost_rial:", total_cost)

ما این کد را روی یک فایل ۱۸ ثانیه‌ای، با SEGMENT_SECONDS = 10 اجرا کردیم تا دو تکه بسازد:

سلام وقت بخیر سفارش شماره ۴۸۲۱ من هنوز نرسیده. لطفاً تا فردا ساعت ۱۰ صبح با من تماس بگیرید.برای اتصال به هیبانا، کلید API رو در متغیر محیطی بذارید و مدل Gemini 3.7 Flash رو انتخاب کنید.cost_rial: 16651

محل برش در این آزمایش اتفاقاً بین دو جمله افتاد. در فایل واقعی ممکن است برش وسط یک کلمه بیفتد و آن کلمه خراب شود. اگر این مهم است، فایل را در سکوت‌ها ببرید. پیش از فرستادن دسته‌ای فایل، محدودیت نرخ درخواست را هم بخوانید.

گوگل در همان مستندات هر ثانیه صدا را ۳۲ توکن حساب می‌کند، یعنی ۱٬۹۲۰ توکن برای هر دقیقه. با قیمت ورودی صوت Gemini 3.7 Flash در زمان نگارش، یک دقیقه صدا حدود ۵۴۷ تومان هزینهٔ ورودی دارد. در اجراهای ما عدد واقعی کمتر بود: ۲۳۲ توکن صوتی برای کلیپ ۹ ثانیه‌ای.

بخش بزرگ‌تر هزینه اما توکن خروجی است. هزینهٔ کلیپ‌های ۸ تا ۹ ثانیه‌ای ما بین ۳٬۱۱۵ و ۱۲٬۶۰۹ ریال بود، چون تعداد توکن خروجی از ۱۵۵ تا ۸۲۶ تغییر می‌کرد. توکن خروجی در مدل‌های جمینای توکن‌های «فکر کردن» را هم شامل می‌شود (مستندات thinking گوگل). پس برآورد را بر پایهٔ cost_rial چند فایل واقعی خودتان بگذارید، نه فقط طول صدا. منطق کلی را در توکن چیست و هزینهٔ API چطور حساب می‌شود توضیح داده‌ایم.

متن پیاده‌شده معمولاً قدم اول است. در این نمونه پیام صوتی مشتری را به متن تبدیل می‌کنیم و بعد با مدل ارزان gpt-5-nano سه فیلد را به‌صورت JSON بیرون می‌کشیم:

import jsonfrom openai import OpenAI client = OpenAI(base_url="https://api-ai.hibanacloud.ir/v1", api_key="YOUR_API_KEY") # مرحلهٔ ۱: صدا به متنwith open("voice.mp3", "rb") as audio:    transcript = client.audio.transcriptions.create(        model="google/gemini-3.7-flash", file=audio, language="fa",    ) # مرحلهٔ ۲: استخراج فیلدها از متنresponse = client.chat.completions.create(    model="gpt-5-nano",    messages=[        {"role": "system", "content": "از پیام مشتری فقط JSON با کلیدهای order_number (عدد)، request و callback_time برگردان."},        {"role": "user", "content": transcript.text},    ],    response_format={"type": "json_object"},) print(json.dumps(json.loads(response.choices[0].message.content), ensure_ascii=False, indent=2))print("cost_rial:", transcript.usage.cost_rial + response.usage.cost_rial)

{  "order_number": 4821,  "request": "پیگیری وضعیت سفارش 4821 و تماس با مشتری تا فردا ساعت ۱۰:۰۰ صبح",  "callback_time": "فردا ۱۰:۰۰ صبح"}cost_rial: 5986

همین کار را می‌شود در یک قدم هم انجام داد: صدا را به‌صورت input_audio در یک پیام چت بفرستید (ورودی صوت) و مستقیم JSON بخواهید. ما این را هم با Gemini 3.7 Flash آزمودیم؛ یک بار order_number را درست ۴۸۲۱ و یک بار اشتباه ۴۸۲۰ برگرداند. چه یک‌قدمی کار کنید چه دوقدمی، عددها و تاریخ‌ها را پیش از استفاده اعتبارسنجی کنید و متن پیاده‌شده را کنار نتیجه نگه دارید تا بتوانید آن را بازبینی کنید.

• زیرنویس زمان‌دار نه: فقط json و text پشتیبانی می‌شوند.
• قطعی اینترنت بین‌الملل: مدل‌های این مطلب روی سرورهای خارج از ایران اجرا می‌شوند. برای آن روزها استفاده از API هوش مصنوعی بدون VPN را بخوانید.
• کیفیت به صدا بستگی دارد: ما با صدای مصنوعی و تمیز آزمودیم. ضبط واقعی را پیش از تکیه بر نتیجه، روی نمونه‌های خودتان امتحان کنید.
• حریم خصوصی: صدای مشتری یا جلسه داده‌ای حساس است. پیش از فرستادن، رضایت گوینده و قوانین مربوط را در نظر بگیرید.

برای تبدیل گفتار فارسی به متن کافی است همان کد Whisper را با base_url هیبانا و یک مدل با ورودی صوت اجرا کنید. با prompt اسم‌ها را درست کنید، فایل‌های طولانی را تکه‌تکه بفرستید، خالی بودن متن را چک کنید و هزینه را از cost_rial واقعی برآورد کنید. برای شروع، کلید API بگیرید، جزئیات پارامترها را در مستندات تبدیل گفتار به متن ببینید و اگر می‌خواهید متن پیاده‌شده را به یک ربات یا سایت وصل کنید، ساخت چت‌بات سایت و ربات بله را بخوانید.