ورودی صوت (Audio Input)

فرستادن یک کلیپ صوتی همراه با پیام، تا مدل به آن گوش بدهد و پاسخ بگوید

مستندات

کدام مدل‌ها صدا می‌پذیرند

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

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

در حال بارگذاری فهرست مدل‌ها… فهرست به‌روز همیشه در لیست مدل‌ها با فیلتر «ورودی صوت» هست، جایی که قیمت‌ها هم کنارش است.

ساختار content

فقط Base64، نشانی https پذیرفته نمی‌شود. برخلاف ورودی تصویر و ورودی فایل که یک نشانی عمومی را هم می‌پذیرند و خودشان دانلودش می‌کنند، صوت فقط به شکل data URI یا رشتهٔ Base64 خام می‌آید. یک نشانی فرستادن با unsupported_attachment رد می‌شود.

مثل تصویر و فایل، content از یک رشتهٔ ساده به آرایه‌ای از «بخش»ها تبدیل می‌شود:

بخش‌های آرایهٔ content
نوع بخش	فیلد داده	توضیح
type: "text"	text	متن پیام کاربر، در همان بخش کنار صدا.
type: "input_audio"	input_audio.data	خود کلیپ صوتی: یک data URI با Base64، یا رشتهٔ Base64 به‌تنهایی. نشانی https پذیرفته نمی‌شود.
type: "input_audio"	input_audio.format	فرمت فایل، یکی از فرمت‌های جدول پایین (مثل wav یا mp3).

{  "type": "input_audio",  "input_audio": {    "data": "<Base64 کلیپ صوتی>",    "format": "wav"  }}

بقیهٔ درخواست تغییری نمی‌کند: همان model، همان messages، همان پارامترهای Chat Completions.

نمونه‌کد

فایل صوتی را بخوانید، Base64 کنید، و در یک بخش input_audio بگذارید. به‌جای مدل نمونه، هر مدلی از فهرست بالا را می‌توانید بگذارید.

# صوت باید Base64 باشد؛ نشانی https پذیرفته نمی‌شود.AUDIO=$(base64 -w0 audio.wav) curl https://api-ai.hibanacloud.ir/v1/chat/completions \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-flash",    "messages": [{      "role": "user",      "content": [        {"type": "text", "text": "این فایل صوتی دربارهٔ چیست؟ در یک جمله بگو."},        {          "type": "input_audio",          "input_audio": {"data": "'"$AUDIO"'", "format": "wav"}        }      ]    }],    "max_completion_tokens": 1000  }'

فرمت‌ها و محدودیت‌ها

فرمت‌های پذیرفته‌شده: wav mp3 aiff aac ogg flac m4a pcm16 pcm24

محدودیت‌های ورودی صوت
محدودیت	توضیح
حجم	۲۰ مگابایت برای هر کلیپ، پس از رمزگشایی از Base64 — نه حجم رشتهٔ Base64 خام.
فقط Base64	نشانی https پذیرفته نمی‌شود؛ فقط data URI یا رشتهٔ Base64 خام.
مدل	فقط مدل‌هایی با قابلیت «ورودی صوت» (فهرست بالا)؛ روی مدل دیگری خطای audio_input_not_supported برمی‌گردد.

روی endpoint دیگر

همین ساختار، بدون هیچ تغییری، روی /v1/responses هم کار می‌کند — همان نام بخش، همان فیلدها.

هزینه

صوت جدا از بقیهٔ متن قیمت‌گذاری می‌شود و معمولاً گران‌تر از ورودی متنی است. هر ثانیه صدا تقریباً ۳۲ توکن حساب می‌شود — یعنی حدود ۱٬۹۲۰ توکن به ازای هر دقیقه — و به نرخ ورودی صوت مدل حساب‌وکتاب می‌شود، نه نرخ ورودی متنی. بقیهٔ prompt (متن پیام) با همان نرخ معمول ورودی حساب می‌شود.

نرخ ورودی صوت هر مدل کنار قیمت متنی‌اش در لیست مدل‌ها و صفحهٔ هر مدل دیده می‌شود؛ توضیح کلی محاسبهٔ هزینه در قیمت‌گذاری.

خطاها و رفع اشکال

خطاهای مخصوص ورودی صوت
کد	معنی
audio_input_not_supported	مدل انتخاب‌شده صدا نمی‌پذیرد؛ از فهرست بالا یک مدل بردارید.
audio_too_large	کلیپ پس از رمزگشایی از ۲۰ مگابایت بزرگ‌تر است.
unsupported_audio_type	فرمت جزو فهرست فرمت‌های پذیرفته‌شده نیست.
invalid_audio	رمزگشایی Base64 شکست خورد یا داده خراب است.

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