مرجع API
Realtime
پیش از اتصال کلاینت، credential کوتاهمدت یا تماس را روی سرور خودتان بسازید. API key پروژه را هرگز در کد مرورگر قرار ندهید.
روند کار
روی هر عملیات بزنید تا همهٔ ورودیها، request، response و کدهای وضعیت آن را ببینید.
برقراری تماس Realtime با WebRTC
/v1/realtime/callshttps://api.mahvashai.irapplication/jsonپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
client_secret | Body | string | الزامی | پشتیبانی میشود | secret کوتاهمدت برای کلاینت Realtime. |
sdp | Body | string | الزامی | پشتیبانی میشود | پیشنهاد SDP از طرف WebRTC. |
session_id | Body | string | الزامی | مخصوص مهوش | شناسهٔ جلسهٔ Realtime در مهوش. |
Request
curl -X POST 'https://api.mahvashai.ir/v1/realtime/calls' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_secret": "ek_...",
"sdp": "v=0\\r\\no=- 0 0 IN IP4 127.0.0.1\\r\\n...",
"session_id": "3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'Response
برای این endpoint نمونهٔ قابلاعتمادی از response در دست نیست. کد وضعیت HTTP را بررسی کنید و body برگشتی را متناسب با روند کار کلاینت خود بخوانید.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 201 | منبع ساخته شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 402 | موجودی برای پرداخت هزینه کافی نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
| 502 | سرویس ارائهدهنده با خطا مواجه شد. |
| 503 | یکی از سرویسهای موردنیاز موقتاً در دسترس نیست. |
ساخت secret کوتاهمدت برای Realtime
/v1/realtime/client_secretshttps://api.mahvashai.irapplication/jsonپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
expires_after | Body | object | اختیاری | مخصوص مهوش | مدت اعتبار credential کوتاهمدت. |
model | Body | string | اختیاری | مشروط | مدل منطقی Realtime. |
session | Body | object | اختیاری | مشروط | تنظیمات جلسهٔ Realtime با اندازهٔ محدود. |
فیلدهای مشروط فقط وقتی کار میکنند که مدل و مسیر ارائهدهنده از آنها پشتیبانی کنند.
Request
curl -X POST 'https://api.mahvashai.ir/v1/realtime/client_secrets' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expires_after": {
"anchor": "created_at",
"seconds": 60
}
}'Response
{
"id": "<id>",
"object": "realtime.session",
"model": "<model-id>",
"expires_at": 1750000000,
"client_secret": {
"value": "<value>",
"expires_at": 1750000000
},
"session_id": "<id>"
}این نمونه فقط ساختار response را نشان میدهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 402 | موجودی برای پرداخت هزینه کافی نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
| 502 | سرویس ارائهدهنده با خطا مواجه شد. |
| 503 | یکی از سرویسهای موردنیاز موقتاً در دسترس نیست. |