تبدیل گفتار به متن (Transcriptions)
POST /v1/audio/transcriptions
مستندات
معرفی
این endpoint یک فایل صوتی میگیرد و متن پیادهشده از روی آن را برمیگرداند. هیچ messagesای در کار نیست و مدل چیزی «تولید» نمیکند؛ فقط میشنود و مینویسد. اگر میخواهید مدل دربارهٔ محتوای صدا صحبت کند یا در یک گفتگو به آن پاسخ بدهد، این صفحه جای درستی نیست؛ ورودی صوت برای همان است.
سازگار با OpenAI SDK، بدون تغییر. همان فراخوانی که برای Whisper مینویسید همینجا هم کار میکند: client.audio.transcriptions.create(model="whisper-1", file=open("a.mp3","rb")). فقط base_url و کلید را عوض کنید. اینجا whisper-1 فقط یک نام سازگاری است: خود Whisper اجرا نمیشود و فایل به مدل پیشفرض تبدیل گفتار به متن هیبانا میرود.
نمونهها
curl https://api-ai.hibanacloud.ir/v1/audio/transcriptions \ -H "Authorization: Bearer YOUR_API_KEY" \ -F file=@audio.wav \ -F model=gemini-2.5-flash-liteپارامترهای درخواست
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| file | file | بله | فایل صوتی، حداکثر ۲۵ مگابایت آپلود و ۲۰ مگابایت پس از رمزگشایی. |
| model | string | خیر | کد یک مدل صوتی، مثل gemini-2.5-flash-lite (پیشفرض) یا gemini-2.5-flash. خالی یعنی مدل پیشفرض. نامهای OpenAI مثل whisper-1 هم پذیرفته میشوند و به همان مدل پیشفرض میروند. |
| language | string | خیر | کد زبان به شکل ISO-639-1، مثل fa؛ فقط یک راهنماست. |
| prompt | string | خیر | متن راهنما برای املا و واژگان خاص (اسمها، اصطلاحات فنی). |
| response_format | string | خیر | json (پیشفرض) یا text. srt، vtt و verbose_json پشتیبانی نمیشوند و با unsupported_response_format رد میشوند. |
| temperature | number | خیر | عددی بین ۰ و ۱. |
درخواست multipart/form-data است، نه JSON؛ همان چیزی که SDK رسمی هر زبان خودش میسازد.
فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| text | string | متن پیادهشده. در response_format=text کل پاسخ همین رشته است، بدون پوششی دور آن. |
| usage.input_tokens | integer | مجموع توکن ورودی (صوت + راهنما/prompt). |
| usage.input_token_details.audio_tokens | integer | سهم صوت از توکن ورودی. |
| usage.input_token_details.text_tokens | integer | سهم متن (prompt) از توکن ورودی. |
| usage.output_tokens | integer | توکنهای متن خروجی. |
| usage.total_tokens | integer | مجموع ورودی و خروجی. |
| usage.cost_rial | integer | هزینهٔ این درخواست به تومان. |
انتخاب مدل
مدل پیشفرض تبدیل گفتار به متن gemini-2.5-flash-lite است؛ اگر model را خالی بگذارید همین استفاده میشود. کد هر مدلی که در لیست مدلها با فیلتر «ورودی صوت» ورودی صوت دارد هم همینجا کار میکند؛ مثلاً gemini-2.5-flash برای دقت بیشتر.
نامهای مدل OpenAI، یعنی whisper-1، gpt-4o-transcribe و gpt-4o-mini-transcribe، فقط برای اینکه کد فعلی شما بدون تغییر کار کند پذیرفته میشوند و همه به مدل پیشفرض میروند. هزینه هم با نرخ صوتی همان مدل حساب میشود.
گام بعدی
هزینهٔ این endpoint هم بر پایهٔ توکن است، با همان نرخ ورودی صوتی که ورودی صوت توضیح داده: تقریباً ۳۲ توکن به ازای هر ثانیه، بهعلاوهٔ توکنهای خروجی متن.
- ورودی صوت، وقتی میخواهید مدل دربارهٔ صدا گفتگو کند، نه فقط آن را پیاده کند.
- مدیریت خطاها، برای معنی کدهایی مثل
audio_too_largeوunsupported_audio_type. - محدودیت نرخ درخواست، قبل از فرستادن دستهای فایل صوتی این را بخوانید.