مرجع API
assetهای قابل استفادهٔ مجدد
assetهای مهوش فایل‌هایی متعلق به یک پروژه‌اند. فایل را یک بار آپلود کنید و UUID آن را در asset_ids درخواست‌های پشتیبانی‌شده بفرستید. این فایل‌ها عمومی نیستند و بین پروژه‌ها مشترک نمی‌شوند.
ورودی فایل و بازیابی اطلاعات ↗ · ساخت پرسش‌وپاسخ اسناد ↗
روند کار
- 01آپلود یک فایل قابل استفادهٔ مجدد (asset)
- 02فهرست assetهای پروژه
- 03دانلود محتوای asset با لینک امضاشده
روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.
آپلود یک فایل قابل استفادهٔ مجدد (asset)
/api/v1/chat/assets/uploadhttps://api.mahvashai.irmultipart/form-dataپارامترها
این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد. |
file | Form | string (binary) | الزامی | مخصوص مهوش | محتوای فایل. |
Request
curl -X POST 'https://api.mahvashai.ir/api/v1/chat/assets/upload' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-F 'file=@./your-file'Response
{
"status": 0,
"data": "<value>"
}این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 201 | منبع ساخته شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 429 | از سقف مجاز عبور کرده‌اید. |
| 500 | خطای داخلی سرور. |
| 503 | یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست. |
فهرست assetهای پروژه
/api/v1/chat/assetshttps://api.mahvashai.irپارامترها
این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
type | Query | string | اختیاری | مخصوص مهوش | فیلتر بر اساس نوع asset. |
source | Query | string | اختیاری | مخصوص مهوش | فیلتر بر اساس منشأ UPLOAD، REMOTE یا GENERATED. |
ordering | Query | string | اختیاری | مخصوص مهوش | created_at یا -created_at. |
page | Query | integer | اختیاری | مخصوص مهوش | شمارهٔ صفحهٔ نتایج (از ۱). |
search | Query | string | اختیاری | مخصوص مهوش | بخشی از نام فایل، بدون حساسیت به حروف بزرگ و کوچک. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد. |
Request
curl -X GET 'https://api.mahvashai.ir/api/v1/chat/assets' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
{
"status": 0,
"data": "<value>"
}این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 429 | از سقف مجاز عبور کرده‌اید. |
| 500 | خطای داخلی سرور. |
دانلود محتوای asset با لینک امضاشده
/api/v1/chat/assets/{asset_id}/contenthttps://api.mahvashai.irپارامترها
این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
asset_id | مسیر (path) | string | الزامی | مخصوص مهوش | UUID مربوط به asset. |
token | Query | string | الزامی | مخصوص مهوش | مجوز امضاشده و زمان‌دار برای دانلود. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد. |
Request
curl -X GET 'https://api.mahvashai.ir/api/v1/chat/assets/<asset_id>/content?token=<token>' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 429 | از سقف مجاز عبور کرده‌اید. |
| 500 | خطای داخلی سرور. |
| 503 | یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست. |
حذف asset
/api/v1/chat/assets/{asset_id}https://api.mahvashai.irپارامترها
این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
asset_id | مسیر (path) | string | الزامی | مخصوص مهوش | UUID مربوط به asset. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد. |
Request
curl -X DELETE 'https://api.mahvashai.ir/api/v1/chat/assets/<asset_id>' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 204 | response محتوایی ندارد. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کرده‌اید. |
| 500 | خطای داخلی سرور. |