مرجع API

Responses

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

روند کار

01ساخت response
02دریافت response
03فهرست ورودی‌های یک response

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

ساخت response

POST/v1/responses

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

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

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

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`asset_ids`	Body	array<value>	اختیاری	مخصوص مهوش	فایل‌های قابل استفادهٔ مجدد شما که به آخرین پیام کاربر پیوست می‌شوند.
`background`	Body	boolean	اختیاری	پشتیبانی می‌شود	request را ثبت می‌کند و بلافاصله پاسخ می‌دهد؛ پیش از آنکه کار ارائه‌دهنده تمام شود.
`chat_id`	Body	string	اختیاری	مخصوص مهوش	ادامهٔ یک گفت‌وگوی ذخیره‌شده که به شما تعلق دارد.
`container`	Body	string \| object	اختیاری	مشروط	تنظیمات container نزد ارائه‌دهنده؛ مسیر باید صریحاً از آن پشتیبانی کند.
`id_chat`	Body	string	اختیاری	منسوخ	نام قدیمی `chat_id`. در کلاینت‌های تازه از `chat_id` استفاده کنید.
`include`	Body	array<value>	اختیاری	مشروط	داده‌های اضافه‌ای که از مسیر سازگار در response می‌خواهید: منابع و نتایج جست‌وجوی وب، نتایج file search یا logprobs متن خروجی.
`input`	Body	string \| array<value>	الزامی	پشتیبانی می‌شود	متن، یا فهرستی از آیتم‌های ورودی.
`instructions`	Body	string	اختیاری	پشتیبانی می‌شود	متن دستورالعمل system یا developer.
`managed_tools`	Body	object	اختیاری	مخصوص مهوش	ابزارهایی که خود مهوش اجرا می‌کند. اگر این فیلد را نفرستید، ابزارهای فعال پروژه خودکار در اختیار مدل قرار می‌گیرند؛ `enabled=false` همه را خاموش می‌کند، `tools` فهرست را محدود می‌کند و `max_rounds` سقف تعداد نوبت‌های استفاده از ابزار است.
`max_output_tokens`	Body	integer	اختیاری	پشتیبانی می‌شود	سقف token خروجی.
`max_tool_calls`	Body	integer	اختیاری	مشروط	سقف آن را تنظیمات سرویس برای فراخوانی ابزارهای ارائه‌دهنده تعیین می‌کند.
`metadata`	Body	object	اختیاری	پشتیبانی می‌شود	شیء metadata با اندازهٔ محدود که عیناً در response برمی‌گردد.
`mode`	Body	string	اختیاری	مخصوص مهوش	حالت انتخاب خودکار مدل، وقتی مدل مشخصی نفرستاده‌اید.
`model`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل. اگر نفرستید، مدل خودکار انتخاب می‌شود.
`parallel_tool_calls`	Body	boolean	اختیاری	مشروط	اجازهٔ فراخوانی همزمان چند ابزار، در مسیرهایی که از آن پشتیبانی می‌کنند.
`previous_response_id`	Body	string	اختیاری	پشتیبانی می‌شود	ادامهٔ یک response کامل‌شده، روی همان مسیری که قبلاً اجرا شده است.
`project`	Body	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه برای این request؛ مقدار متناقض رد می‌شود.
`prompt`	Body	object \| string	اختیاری	مشروط	ارجاع به قالب prompt نزد ارائه‌دهنده.
`prompt_cache_key`	Body	string	اختیاری	مشروط	نام بخشی از prompt cache؛ پیش از رسیدن به ارائه‌دهنده به سازمان شما محدود می‌شود. مسیر باید از آن پشتیبانی کند.
`prompt_cache_retention`	Body	string	اختیاری	مشروط	مدت نگهداری ترجیحی prompt cache؛ مسیر باید از آن پشتیبانی کند.
`prompt_id`	Body	string	اختیاری	مخصوص مهوش	promptی از پروژه که به دستورالعمل‌های این اجرا اضافه می‌شود.
`reasoning`	Body	object	اختیاری	مشروط	تنظیمات استدلال؛ مسیر انتخاب‌شده باید از آن پشتیبانی کند.
`safety_identifier`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ ثابت ایمنی نزد ارائه‌دهنده.
`service_tier`	Body	string	اختیاری	مشروط	سطح سرویس ارائه‌دهنده؛ مسیر باید از آن پشتیبانی کند.
`store`	Body	boolean	اختیاری	مشروط	ترجیح ذخیره‌سازی نزد ارائه‌دهنده.
`stream`	Body	boolean	اختیاری	پشتیبانی می‌شود	رویدادها را با نوع مشخص و به‌صورت Server-Sent Events برمی‌گرداند.
`temperature`	Body	number	اختیاری	پشتیبانی می‌شود	دمای نمونه‌گیری (temperature)، بین ۰ تا ۲.
`text`	Body	object	اختیاری	مشروط	تنظیمات متن و خروجی ساختاریافته. قالب `json_schema` پیش از تماس با ارائه‌دهنده بررسی می‌شود و خروجی مدل هم با آن تطبیق داده می‌شود.
`text_format`	Body	object	اختیاری	مخصوص مهوش	نام جایگزین صریح برای تعیین قالب خروجی ساختاریافته.
`tool_choice`	Body	string \| object	اختیاری	پشتیبانی می‌شود	روش انتخاب ابزار که به مسیر سازگار فرستاده می‌شود.
`tools`	Body	array<value>	اختیاری	مشروط	ابزارهای function و ابزارهای ثبت‌شدهٔ ارائه‌دهنده.
`top_p`	Body	number	اختیاری	پشتیبانی می‌شود	پارامتر nucleus sampling، بین ۰ تا ۱.
`truncation`	Body	string	اختیاری	مشروط	حالت کوتاه کردن ورودی نزد ارائه‌دهنده.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/responses' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "auto",
  "input": "Summarize the value of a small, reliable API in one sentence."
}'

Response

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1750000000,
  "status": "completed",
  "model": "<model-id>",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 11,
    "output_tokens": 4,
    "total_tokens": 15
  }
}

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

کدهای وضعیت

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

دریافت response

GET/v1/responses/{pk}

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

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

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

پارامترها

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

Request

curl -X GET 'https://api.mahvashai.ir/v1/responses/<pk>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "<value>",
  "created_at": 0,
  "status": "queued",
  "background": false,
  "error": "<value>",
  "incomplete_details": "<value>",
  "instructions": "<value>",
  "max_output_tokens": "<value>",
  "model": "<value>",
  "output": [
    {
      "type": "<value>"
    }
  ],
  "parallel_tool_calls": false,
  "previous_response_id": "<id>",
  "reasoning": "<value>"
}

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

کدهای وضعیت

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

فهرست ورودی‌های یک response

GET/v1/responses/{pk}/input_items

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`pk`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ response که با `resp_` شروع می‌شود.
`limit`	Query	integer	اختیاری	پشتیبانی می‌شود	اندازهٔ صفحه از ۱ تا ۱۰۰؛ پیش‌فرض ۲۰.
`order`	Query	string	اختیاری	پشتیبانی می‌شود	مرتب‌سازی آیتم‌ها با `asc` (پیش‌فرض) یا `desc`.
`after`	Query	string	اختیاری	پشتیبانی می‌شود	آیتم‌های بعد از این شناسه را برمی‌گرداند.
`before`	Query	string	اختیاری	پشتیبانی می‌شود	آیتم‌های پیش از این شناسه را برمی‌گرداند.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/v1/responses/<pk>/input_items' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "<value>",
  "data": [
    {
      "id": "<id>",
      "type": "<value>"
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false
}

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

کدهای وضعیت

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

لغو response

POST/v1/responses/{pk}/cancel

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

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

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

پارامترها

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

Request

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

Response

برای این endpoint نمونهٔ قابل‌اعتمادی از response در دست نیست. کد وضعیت HTTP را بررسی کنید و body برگشتی را متناسب با روند کار کلاینت خود بخوانید.

کدهای وضعیت

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

حذف response

DELETE/v1/responses/{pk}

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

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

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

پارامترها

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

Request

curl -X DELETE 'https://api.mahvashai.ir/v1/responses/<pk>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

کدهای وضعیت

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