رفتن به محتوا

مرجع API

Batchها

مجموعه‌ای از requestها را یکجا برای اجرا در پس‌زمینه بفرستید، پیشرفتشان را دنبال کنید و در صورت نیاز کارهای باقی‌مانده را لغو کنید.

روند کار

  1. 01ساخت batch از فایل JSONL
  2. 02لغو کارهای در صف یک batch
  3. 03دریافت وضعیت یک batch

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

ساخت batch از فایل JSONL

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

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
Idempotency-KeyHeaderstringاختیاریپشتیبانی می‌شودکلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوشslug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
completion_windowBodystringاختیاریمشروطبازهٔ زمانی تکمیل؛ فعلاً فقط 24h پشتیبانی می‌شود.
endpointBodystringالزامیپشتیبانی می‌شودendpoint عمومی‌ای که همهٔ خط‌های JSONL به آن فرستاده می‌شوند.
input_file_idBodystringالزامیپشتیبانی می‌شودیک فایل JSONL آماده که با purpose=batch آپلود شده است.
metadataBodyobjectاختیاریپشتیبانی می‌شود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توضیحات
200request با موفقیت انجام شد.
400request نامعتبر است.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409تداخل در وضعیت یا idempotency.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.

لغو کارهای در صف یک batch

POST/v1/batches/{batch_id}/cancel
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
batch_idمسیر (path)stringالزامیپشتیبانی می‌شودشناسهٔ batch.
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوش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توضیحات
200request با موفقیت انجام شد.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409تداخل در وضعیت یا idempotency.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.

دریافت وضعیت یک batch

GET/v1/batches/{batch_id}
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
batch_idمسیر (path)stringالزامیپشتیبانی می‌شودشناسهٔ batch.
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوش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توضیحات
200request با موفقیت انجام شد.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.

فهرست batchهای پروژه

GET/v1/batches
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI

پارامترها

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

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
afterQuerystringاختیاریپشتیبانی می‌شودbatchهای بعد از این شناسه را برمی‌گرداند.
limitQueryintegerاختیاریپشتیبانی می‌شودتعداد batchها، حداکثر ۱۰۰.
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوش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توضیحات
200request با موفقیت انجام شد.
400request نامعتبر است.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.