رفتن به محتوا

مرجع API

Realtime

پیش از اتصال کلاینت، credential کوتاه‌مدت یا تماس را روی سرور خودتان بسازید. API key پروژه را هرگز در کد مرورگر قرار ندهید.

روند کار

  1. 01برقراری تماس Realtime با WebRTC
  2. 02ساخت secret کوتاه‌مدت برای Realtime

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

برقراری تماس Realtime با WebRTC

POST/v1/realtime/calls
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI
نوع محتواapplication/json

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوشslug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
client_secretBodystringالزامیپشتیبانی می‌شودsecret کوتاه‌مدت برای کلاینت Realtime.
sdpBodystringالزامیپشتیبانی می‌شودپیشنهاد SDP از طرف WebRTC.
session_idBodystringالزامیمخصوص مهوششناسهٔ جلسهٔ 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منبع ساخته شد.
400request نامعتبر است.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402موجودی برای پرداخت هزینه کافی نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409تداخل در وضعیت یا idempotency.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.
502سرویس ارائه‌دهنده با خطا مواجه شد.
503یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.

ساخت secret کوتاه‌مدت برای Realtime

POST/v1/realtime/client_secrets
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI
نوع محتواapplication/json

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوشslug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
expires_afterBodyobjectاختیاریمخصوص مهوشمدت اعتبار credential کوتاه‌مدت.
modelBodystringاختیاریمشروطمدل منطقی Realtime.
sessionBodyobjectاختیاریمشروطتنظیمات جلسهٔ 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توضیحات
200request با موفقیت انجام شد.
400request نامعتبر است.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402موجودی برای پرداخت هزینه کافی نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409تداخل در وضعیت یا idempotency.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.
502سرویس ارائه‌دهنده با خطا مواجه شد.
503یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.