مرجع API

گفت‌وگوها و Chat Completions

اگر کلاینت شما با قالب Chat Completions کار می‌کند، از همین بخش استفاده کنید. با عملیات گفت‌وگو هم می‌توانید پیام‌ها و اجراهای ذخیره‌شده را ببینید.

روند کار

01ساخت Chat Completion
02فهرست گفت‌وگوها
03دریافت اطلاعات گفت‌وگو

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

ساخت Chat Completion

POST/v1/chat/completions

آدرس پایهٔ 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>	اختیاری	مخصوص مهوش	فایل‌های قابل استفادهٔ مجدد شما که به آخرین پیام کاربر پیوست می‌شوند.
`audio`	Body	object	اختیاری	مشروط	تنظیمات خروجی صوتی؛ به مسیری نیاز دارد که خروجی صوتی را پشتیبانی کند.
`chat_id`	Body	string	اختیاری	مخصوص مهوش	ادامهٔ یک گفت‌وگوی ذخیره‌شده که به شما تعلق دارد.
`frequency_penalty`	Body	number	اختیاری	پشتیبانی می‌شود	جریمهٔ تکرار واژه‌ها، بین ۲- تا ۲.
`function_call`	Body	string \| object	اختیاری	منسوخ	روش قدیمی انتخاب function. `tool_choice` را ترجیح دهید.
`functions`	Body	array<value>	اختیاری	منسوخ	تعریف قدیمی functionها. `tools` را ترجیح دهید.
`id_chat`	Body	string	اختیاری	منسوخ	نام قدیمی `chat_id`. در کلاینت‌های تازه از `chat_id` استفاده کنید.
`logit_bias`	Body	object	اختیاری	مشروط	حداکثر ۳۰۰ مقدار bias برای شناسهٔ tokenها، هر کدام بین ۱۰۰- تا ۱۰۰.
`logprobs`	Body	boolean	اختیاری	مشروط	احتمال tokenها را درخواست می‌کند؛ مسیر باید از آن پشتیبانی کند. نتیجه در `choices[].logprobs` و هنگام stream در هر chunk می‌آید.
`managed_tools`	Body	object	اختیاری	مخصوص مهوش	ابزارهایی که خود مهوش اجرا می‌کند. اگر این فیلد را نفرستید، ابزارهای فعال پروژه خودکار در اختیار مدل قرار می‌گیرند؛ `enabled=false` همه را خاموش می‌کند، `tools` فهرست را محدود می‌کند و `max_rounds` سقف تعداد نوبت‌های استفاده از ابزار است.
`max_completion_tokens`	Body	integer	اختیاری	پشتیبانی می‌شود	سقف tokenهای خروجی، از ۱ تا ۱٬۰۰۰٬۰۰۰.
`max_output_tokens`	Body	integer	اختیاری	مخصوص مهوش	نام جایگزین پذیرفته‌شده برای `max_completion_tokens`.
`max_tokens`	Body	integer	اختیاری	منسوخ	سقف قدیمی token خروجی. `max_completion_tokens` را ترجیح دهید.
`messages`	Body	array<value>	الزامی	پشتیبانی می‌شود	پیام‌های گفت‌وگو؛ بین ۱ تا ۱٬۰۰۰ مورد.
`metadata`	Body	object	اختیاری	پشتیبانی می‌شود	شیء metadata با اندازهٔ محدود برای ارائه‌دهنده یا اپلیکیشن شما.
`modalities`	Body	array<value>	اختیاری	مشروط	نوع‌های خروجی درخواستی (modality)؛ هر کدام به قابلیت خروجی مربوط به خودش نیاز دارد.
`mode`	Body	string	اختیاری	مخصوص مهوش	حالت انتخاب خودکار مدل، وقتی مدل مشخصی نفرستاده‌اید.
`model`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل. اگر نفرستید، مدل خودکار انتخاب می‌شود.
`n`	Body	integer	اختیاری	مشروط	تعداد پاسخ‌های جایگزین. مقدار بیشتر از ۱ به پشتیبانی صریح مسیر نیاز دارد.
`parallel_tool_calls`	Body	boolean	اختیاری	مشروط	اجازهٔ فراخوانی همزمان چند ابزار، در مسیرهایی که از آن پشتیبانی می‌کنند.
`prediction`	Body	object	اختیاری	مشروط	تنظیمات predicted output که به مسیرهای سازگار فرستاده می‌شود.
`presence_penalty`	Body	number	اختیاری	پشتیبانی می‌شود	جریمهٔ حضور واژه، بین ۲- تا ۲.
`project`	Body	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه برای این request؛ مقدار متناقض رد می‌شود.
`prompt_cache_key`	Body	string	اختیاری	مشروط	نام بخشی از prompt cache؛ پیش از رسیدن به ارائه‌دهنده به سازمان شما محدود می‌شود. مسیر باید از آن پشتیبانی کند.
`prompt_cache_retention`	Body	string	اختیاری	مشروط	مدت نگهداری ترجیحی prompt cache؛ مسیر باید از آن پشتیبانی کند.
`prompt_id`	Body	string	اختیاری	مخصوص مهوش	promptی از پروژه که به دستورالعمل‌های این اجرا اضافه می‌شود.
`reasoning_effort`	Body	string	اختیاری	مشروط	هم مدل منطقی و هم مسیر ارائه‌دهنده باید از آن پشتیبانی کنند.
`response_format`	Body	object	اختیاری	مشروط	`json_object` یا `json_schema`؛ مسیر باید قابلیت آن را اعلام کرده باشد. تعریف `json_schema` محدود می‌شود، در حالت strict پیش از تماس با ارائه‌دهنده بررسی می‌شود و خروجی نیز با schema تطبیق داده می‌شود.
`safety_identifier`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ ثابت ایمنی که به مسیر سازگار فرستاده می‌شود.
`seed`	Body	integer	اختیاری	مشروط	راهنمایی برای تکرارپذیری خروجی نزد ارائه‌دهنده؛ مسیر باید از آن پشتیبانی کند.
`service_tier`	Body	string	اختیاری	مشروط	سطح سرویس درخواستی از ارائه‌دهنده؛ مسیر باید از آن پشتیبانی کند.
`stop`	Body	string \| array<value>	اختیاری	پشتیبانی می‌شود	حداکثر ۴ رشتهٔ توقف (stop sequence) که هر کدام حداکثر ۱٬۰۲۴ نویسه دارد.
`stream`	Body	boolean	اختیاری	پشتیبانی می‌شود	به‌جای یک شیء JSON، رویدادها را به‌صورت Server-Sent Events برمی‌گرداند.
`stream_options`	Body	object	اختیاری	مشروط	فقط `include_usage` پذیرفته می‌شود.
`temperature`	Body	number	اختیاری	پشتیبانی می‌شود	دمای نمونه‌گیری (temperature)، بین ۰ تا ۲.
`thinking`	Body	object	اختیاری	مخصوص مهوش	تنظیمات استدلال برای مسیرهایی که از آن پشتیبانی می‌کنند.
`tool_choice`	Body	string \| object	اختیاری	پشتیبانی می‌شود	یکی از `auto`، `none`، `required` یا شیئی سازگار با ارائه‌دهنده.
`tools`	Body	array<value>	اختیاری	مشروط	فقط ابزارهای function؛ ابزارهای ارائه‌دهنده فقط در Responses پشتیبانی می‌شوند.
`top_logprobs`	Body	integer	اختیاری	مشروط	تعداد محتمل‌ترین tokenها در هر جایگاه، بین ۰ تا ۲۰؛ مسیر باید از آن پشتیبانی کند.
`top_p`	Body	number	اختیاری	پشتیبانی می‌شود	پارامتر nucleus sampling، بین ۰ تا ۱.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.
`verbosity`	Body	string	اختیاری	مشروط	میزان تفصیل پاسخ نزد ارائه‌دهنده.
`web_search_options`	Body	object	اختیاری	مشروط	به مسیری نیاز دارد که جست‌وجوی وب و همین پارامتر را پشتیبانی کند.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/chat/completions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "Say hello in one sentence."
    }
  ]
}'

Response

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Hello!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 4,
    "total_tokens": 15
  }
}

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

کدهای وضعیت

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

فهرست گفت‌وگوها

GET/v1/chat/completions

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`search`	Query	string	اختیاری	مخصوص مهوش	جست‌وجوی گفت‌وگو بر اساس عنوان یا محتوای پیام.
`status`	Query	string	اختیاری	مخصوص مهوش	فیلتر بر اساس وضعیت گفت‌وگو.
`mode`	Query	string	اختیاری	مخصوص مهوش	فیلتر بر اساس حالت گفت‌وگو.
`is_pinned`	Query	boolean	اختیاری	مخصوص مهوش	فقط گفت‌وگوهای سنجاق‌شده را نشان می‌دهد.
`ordering`	Query	string	اختیاری	مخصوص مهوش	`updated_at` یا `title`، با prefix اختیاری `-`.
`cursor`	Query	string	اختیاری	مخصوص مهوش	cursorی که از صفحهٔ قبل گرفته‌اید؛ محتوای آن را تغییر ندهید.
`limit`	Query	integer	اختیاری	مخصوص مهوش	اندازهٔ صفحهٔ درخواستی که سرور برایش سقف تعیین می‌کند.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/v1/chat/completions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "chat.completion",
      "created": 1750000000,
      "model": null,
      "metadata": {
        "chat_id": "<id>",
        "title": "<value>",
        "is_pinned": false,
        "status": "ACTIVE",
        "mode": "<value>"
      }
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false,
  "next": null,
  "previous": null
}

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

کدهای وضعیت

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

دریافت اطلاعات گفت‌وگو

GET/v1/chat/completions/{pk}

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

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

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

پارامترها

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

Request

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

Response

{
  "id": "<id>",
  "object": "chat.completion",
  "created": 1750000000,
  "model": null,
  "metadata": {
    "chat_id": "<id>",
    "title": "<value>",
    "is_pinned": false,
    "status": "ACTIVE",
    "mode": "<value>"
  }
}

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

کدهای وضعیت

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

فهرست پیام‌ها و فایل‌های یک گفت‌وگو

GET/v1/chat/completions/{pk}/messages

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

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

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

پارامترها

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

Request

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "chat.completion.message",
      "role": "user",
      "content": "<value>",
      "content_parts": [],
      "tool_calls": [],
      "attachments": [],
      "created": 1750000000,
      "metadata": {
        "status": "COMPLETED"
      }
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false,
  "next": null,
  "previous": null
}

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

کدهای وضعیت

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

لغو اجرای در حال انجام گفت‌وگو

POST/v1/chat/completions/cancel

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

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

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

نوع محتواapplication/json

پارامترها

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/chat/completions/cancel' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_id": "3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'

Response

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

کدهای وضعیت

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

حذف گفت‌وگو و پاک کردن محتوای آن

DELETE/v1/chat/completions/{pk}

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

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

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

پارامترها

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

Request

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

Response

{
  "message": "<value>"
}

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

کدهای وضعیت

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