مرجع API

آپلود چندبخشی

برای فایل‌های بزرگ یا اتصال‌های ناپایدار از آپلود چندبخشی استفاده کنید: جلسهٔ آپلود را بسازید، بخش‌های شماره‌دار را بفرستید و پیش از استفاده از فایل، آپلود را تکمیل کنید.

ورودی فایل و بازیابی اطلاعات ↗ · ساخت پرسش‌وپاسخ اسناد ↗

روند کار

01شروع آپلود چندبخشی
02آپلود یک بخش از فایل
03تکمیل آپلود چندبخشی

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

شروع آپلود چندبخشی

POST/api/v1/chat/uploads

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

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

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

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`bytes`	Body	integer	الزامی	پشتیبانی می‌شود	حجم کل فایل بر حسب بایت.
`filename`	Body	string	الزامی	پشتیبانی می‌شود	نام فایل (بدون مسیر پوشه)، حداکثر ۲۵۵ نویسه.
`mime_type`	Body	string	اختیاری	پشتیبانی می‌شود	نوع فایل (MIME) نهایی، پس از کنار هم گذاشتن بخش‌ها.
`part_count`	Body	integer	اختیاری	مخصوص مهوش	تعداد بخش‌های موردانتظار که هنگام تکمیل آپلود بررسی می‌شود.
`purpose`	Body	string	اختیاری	مشروط	گزینه‌های رسمی `assistants`، `batch`، `fine-tune`، `vision` و `evals`؛ یا افزونه‌های مهوش `user_data` و `responses`.

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

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/uploads' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bytes": 1024,
  "filename": "report.pdf"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

HTTP	توضیحات
201	منبع ساخته شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

آپلود یک بخش از فایل

PUT/api/v1/chat/uploads/{upload_id}/parts/{part_number}

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

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`upload_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ جلسهٔ آپلود.
`part_number`	مسیر (path)	integer	الزامی	پشتیبانی می‌شود	شمارهٔ بخش، با شروع از ۱.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`file`	Form	string (binary)	الزامی	پشتیبانی می‌شود	محتوای این بخش از فایل.

Request

curl -X PUT 'https://api.mahvashai.ir/api/v1/chat/uploads/<upload_id>/parts/<part_number>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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

تکمیل آپلود چندبخشی

POST/api/v1/chat/uploads/{upload_id}/complete

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

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

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

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`upload_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ جلسهٔ آپلود.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`sha256`	Body	string	اختیاری	پشتیبانی می‌شود	checksum موردانتظار برای فایل نهایی.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/uploads/<upload_id>/complete' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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

لغو آپلود چندبخشی

POST/api/v1/chat/uploads/{upload_id}/cancel

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`upload_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ جلسهٔ آپلود.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/uploads/<upload_id>/cancel' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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