مرجع API

صوت

تبدیل متن به گفتار، تبدیل گفتار به متن و ترجمهٔ صوت عملیات جداگانه‌ای هستند. نوع ورودی و قالب خروجی را با قابلیت‌های مدل انتخابی هماهنگ کنید.

روند کار

01تبدیل متن به گفتار
02تبدیل فایل صوتی به متن
03ترجمهٔ فایل صوتی به متن انگلیسی

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

تبدیل متن به گفتار

POST/v1/audio/speech

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`input`	Body	string	الزامی	پشتیبانی می‌شود	متنی که به گفتار تبدیل می‌شود؛ طول آن با تنظیمات سرویس محدود است.
`instructions`	Body	string	اختیاری	مشروط	دستورهای تحویل، حداکثر ۴٬۰۹۶ نویسه.
`model`	Body	string	الزامی	پشتیبانی می‌شود	شناسهٔ عمومی مدل گفتار.
`response_format`	Body	string	اختیاری	پشتیبانی می‌شود	یکی از `mp3`، `opus`، `aac`، `flac`، `wav` یا `pcm`.
`speed`	Body	number	اختیاری	مشروط	سرعت پخش، بین ۰٫۲۵ تا ۴٫۰.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.
`voice`	Body	string	الزامی	پشتیبانی می‌شود	شناسهٔ صدا نزد ارائه‌دهنده.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/speech' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "input": "probe",
  "model": "tts-1",
  "voice": "alloy"
}'

Response

این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402	موجودی برای پرداخت هزینه کافی نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409	تداخل در وضعیت یا idempotency.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.
502	سرویس ارائه‌دهنده با خطا مواجه شد.
503	یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.

تبدیل فایل صوتی به متن

POST/v1/audio/transcriptions

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواmultipart/form-data

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`file`	Form	string (binary)	الزامی	پشتیبانی می‌شود	فایل صوتی که باید پردازش شود.
`language`	Form	string	اختیاری	پشتیبانی می‌شود	زبان صوت با کد ISO، حداکثر ۱۶ نویسه.
`model`	Form	string	الزامی	پشتیبانی می‌شود	شناسهٔ عمومی مدل صوتی.
`prompt`	Form	string	اختیاری	مشروط	راهنمایی برای تبدیل گفتار به متن (مثلاً واژه‌های تخصصی)، حداکثر ۴٬۰۹۶ نویسه.
`response_format`	Form	string	اختیاری	پشتیبانی می‌شود	یکی از `json`، `text`، `srt`، `verbose_json` یا `vtt`.
`temperature`	Form	number	اختیاری	پشتیبانی می‌شود	دمای نمونه‌گیری (temperature)، بین ۰ تا ۱.
`timestamp_granularities`	Form	array<value>	اختیاری	مشروط	`word` یا `segment` یا هر دو؛ به `response_format=verbose_json` نیاز دارد.
`user`	Form	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/transcriptions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'file=@./your-file' \
  -F 'model=whisper-1'

Response

{
  "text": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402	موجودی برای پرداخت هزینه کافی نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409	تداخل در وضعیت یا idempotency.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.
502	سرویس ارائه‌دهنده با خطا مواجه شد.
503	یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.

ترجمهٔ فایل صوتی به متن انگلیسی

POST/v1/audio/translations

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواmultipart/form-data

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`file`	Form	string (binary)	الزامی	پشتیبانی می‌شود	فایل صوتی که باید پردازش شود.
`model`	Form	string	الزامی	پشتیبانی می‌شود	شناسهٔ عمومی مدل صوتی.
`prompt`	Form	string	اختیاری	مشروط	راهنمایی برای تبدیل گفتار به متن (مثلاً واژه‌های تخصصی)، حداکثر ۴٬۰۹۶ نویسه.
`response_format`	Form	string	اختیاری	پشتیبانی می‌شود	یکی از `json`، `text`، `srt`، `verbose_json` یا `vtt`.
`temperature`	Form	number	اختیاری	پشتیبانی می‌شود	دمای نمونه‌گیری (temperature)، بین ۰ تا ۱.
`user`	Form	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/audio/translations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'file=@./your-file' \
  -F 'model=whisper-1'

Response

برای این endpoint نمونهٔ قابل‌اعتمادی از response در دست نیست. کد وضعیت HTTP را بررسی کنید و body برگشتی را متناسب با روند کار کلاینت خود بخوانید.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402	موجودی برای پرداخت هزینه کافی نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409	تداخل در وضعیت یا idempotency.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.
502	سرویس ارائه‌دهنده با خطا مواجه شد.
503	یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.