مرجع API
Batchها
مجموعهای از requestها را یکجا برای اجرا در پسزمینه بفرستید، پیشرفتشان را دنبال کنید و در صورت نیاز کارهای باقیمانده را لغو کنید.
روند کار
روی هر عملیات بزنید تا همهٔ ورودیها، request، response و کدهای وضعیت آن را ببینید.
ساخت batch از فایل JSONL
/v1/batcheshttps://api.mahvashai.irapplication/jsonپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
Idempotency-Key | Header | string | اختیاری | پشتیبانی میشود | کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمیگردد. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
completion_window | Body | string | اختیاری | مشروط | بازهٔ زمانی تکمیل؛ فعلاً فقط 24h پشتیبانی میشود. |
endpoint | Body | string | الزامی | پشتیبانی میشود | endpoint عمومیای که همهٔ خطهای JSONL به آن فرستاده میشوند. |
input_file_id | Body | string | الزامی | پشتیبانی میشود | یک فایل JSONL آماده که با purpose=batch آپلود شده است. |
metadata | Body | object | اختیاری | پشتیبانی میشود | metadata دلخواه شما که روی شیء batch ذخیره میشود. |
فیلدهای مشروط فقط وقتی کار میکنند که مدل و مسیر ارائهدهنده از آنها پشتیبانی کنند.
Request
curl -X POST 'https://api.mahvashai.ir/v1/batches' \
-H "Authorization: Bearer $MAHVASH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-request-id>" \
-d '{
"endpoint": "/v1/embeddings",
"input_file_id": "file-3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'Response
{
"id": "<id>",
"object": "batch",
"endpoint": "<value>",
"errors": null,
"input_file_id": "<id>",
"completion_window": "24h",
"status": "in_progress",
"output_file_id": null,
"error_file_id": null,
"created_at": 1750000000,
"in_progress_at": 0,
"expires_at": 1750000000,
"finalizing_at": null,
"completed_at": null,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"metadata": {
"test": "<value>"
}
}این نمونه فقط ساختار response را نشان میدهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
لغو کارهای در صف یک batch
/v1/batches/{batch_id}/cancelhttps://api.mahvashai.irپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
batch_id | مسیر (path) | string | الزامی | پشتیبانی میشود | شناسهٔ batch. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
Request
curl -X POST 'https://api.mahvashai.ir/v1/batches/<batch_id>/cancel' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
برای این endpoint نمونهٔ قابلاعتمادی از response در دست نیست. کد وضعیت HTTP را بررسی کنید و body برگشتی را متناسب با روند کار کلاینت خود بخوانید.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
دریافت وضعیت یک batch
/v1/batches/{batch_id}https://api.mahvashai.irپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
batch_id | مسیر (path) | string | الزامی | پشتیبانی میشود | شناسهٔ batch. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
Request
curl -X GET 'https://api.mahvashai.ir/v1/batches/<batch_id>' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
{
"id": "<id>",
"object": "batch",
"endpoint": "<value>",
"errors": null,
"input_file_id": "<id>",
"completion_window": "24h",
"status": "completed",
"output_file_id": "<id>",
"error_file_id": null,
"created_at": 1750000000,
"in_progress_at": 0,
"expires_at": 1750000000,
"finalizing_at": 0,
"completed_at": 0,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"metadata": {
"test": "<value>"
}
}این نمونه فقط ساختار response را نشان میدهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
فهرست batchهای پروژه
/v1/batcheshttps://api.mahvashai.irپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
after | Query | string | اختیاری | پشتیبانی میشود | batchهای بعد از این شناسه را برمیگرداند. |
limit | Query | integer | اختیاری | پشتیبانی میشود | تعداد batchها، حداکثر ۱۰۰. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
Request
curl -X GET 'https://api.mahvashai.ir/v1/batches' \
-H "Authorization: Bearer $MAHVASH_API_KEY"Response
{
"object": "list",
"data": [
{
"id": "<id>",
"object": "batch",
"endpoint": "<value>",
"errors": null,
"input_file_id": "<id>",
"completion_window": "24h",
"status": "completed",
"output_file_id": "<id>",
"error_file_id": null,
"created_at": 1750000000,
"in_progress_at": 0,
"expires_at": 1750000000,
"finalizing_at": 0,
"completed_at": 0,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"metadata": {
"test": "<value>"
}
}
],
"first_id": "<id>",
"last_id": "<id>",
"has_more": false
}این نمونه فقط ساختار response را نشان میدهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.
کدهای وضعیت
| HTTP | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |