مرجع API

تصویر

با مدلی که این قابلیت را دارد تصویر بسازید یا ویرایش کنید. بسته به نیاز، ساخت مستقیم یا ثبت در صف را انتخاب کنید.

روند کار

01ثبت ساخت تصویر در صف
02ویرایش یک یا چند تصویر
03ساخت تصویر

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

ثبت ساخت تصویر در صف

POST/api/v1/chat/images/generations

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

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

Responseresponse در قالب مخصوص مهوش

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`background`	Body	string	اختیاری	مشروط	یکی از `auto`، `transparent` یا `opaque`. حالت transparent به png یا webp نیاز دارد.
`chat_id`	Body	string	اختیاری	مخصوص مهوش	تصویر ساخته‌شده را به یکی از گفت‌وگوهای شما پیوست می‌کند.
`model`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل تصویر.
`moderation`	Body	string	اختیاری	مشروط	`auto` یا `low`.
`n`	Body	integer	اختیاری	مشروط	تعداد تصویرها، بین ۱ تا ۱۰؛ بیشتر از ۱ به پشتیبانی مسیر نیاز دارد.
`output_compression`	Body	integer	اختیاری	مشروط	سطح فشرده‌سازی از ۰ تا ۱۰۰، برای قالب‌هایی که با افت کیفیت فشرده می‌شوند.
`output_format`	Body	string	اختیاری	مشروط	یکی از `png`، `jpeg` یا `webp`.
`prompt`	Body	string	الزامی	پشتیبانی می‌شود	prompt توصیف تصویر، حداکثر ۳۲٬۰۰۰ نویسه.
`quality`	Body	string	اختیاری	مشروط	یکی از `auto`، `low`، `medium`، `high`، `standard` یا `hd`.
`response_format`	Body	string	اختیاری	مشروط	`b64_json` یا `url`. مهوش همیشه URL متعلق به خودش را برمی‌گرداند.
`size`	Body	string	اختیاری	مشروط	`auto` یا `WIDTHxHEIGHT` در محدودهٔ تنظیم‌شده.
`style`	Body	string	اختیاری	مشروط	`vivid` یا `natural`، در مسیرهایی که آن را می‌پذیرند.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

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

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/images/generations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "prompt": "a red bicycle"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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

ویرایش یک یا چند تصویر

POST/v1/images/edits

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

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

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

نوع محتواmultipart/form-data

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`background`	Form	string	اختیاری	مشروط	یکی از `auto`، `transparent` یا `opaque`. حالت transparent به png یا webp نیاز دارد.
`image`	Form	array<string> (binary)	الزامی	پشتیبانی می‌شود	بین ۱ تا ۱۶ تصویر ورودی.
`input_fidelity`	Form	string	اختیاری	مشروط	`low` یا `high`؛ برای مدل‌هایی که همیشه با `high` کار می‌کنند پذیرفته نمی‌شود.
`mask`	Form	string (binary)	اختیاری	پشتیبانی می‌شود	ماسک alpha با همان قالب و اندازهٔ تصویر اول.
`model`	Form	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل تصویر.
`moderation`	Form	string	اختیاری	مشروط	`auto` یا `low`.
`n`	Form	integer	اختیاری	مشروط	تعداد تصویرها، بین ۱ تا ۱۰؛ بیشتر از ۱ به پشتیبانی مسیر نیاز دارد.
`output_compression`	Form	integer	اختیاری	مشروط	سطح فشرده‌سازی از ۰ تا ۱۰۰، برای قالب‌هایی که با افت کیفیت فشرده می‌شوند.
`output_format`	Form	string	اختیاری	مشروط	یکی از `png`، `jpeg` یا `webp`.
`prompt`	Form	string	الزامی	پشتیبانی می‌شود	prompt توصیف تصویر، حداکثر ۳۲٬۰۰۰ نویسه.
`quality`	Form	string	اختیاری	مشروط	یکی از `auto`، `low`، `medium`، `high`، `standard` یا `hd`.
`response_format`	Form	string	اختیاری	مشروط	`b64_json` یا `url`. مهوش همیشه URL متعلق به خودش را برمی‌گرداند.
`size`	Form	string	اختیاری	مشروط	`auto` یا `WIDTHxHEIGHT` در محدودهٔ تنظیم‌شده.
`user`	Form	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/images/edits' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'image=@./your-file' \
  -F 'prompt=a red bicycle'

Response

{
  "data": [
    {
      "url": "https://example.com/resource"
    }
  ],
  "created": 1750000000
}

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

کدهای وضعیت

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

ساخت تصویر

POST/v1/images/generations

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

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

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

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`background`	Body	string	اختیاری	مشروط	یکی از `auto`، `transparent` یا `opaque`. حالت transparent به png یا webp نیاز دارد.
`model`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ عمومی مدل تصویر.
`moderation`	Body	string	اختیاری	مشروط	`auto` یا `low`.
`n`	Body	integer	اختیاری	مشروط	تعداد تصویرها، بین ۱ تا ۱۰؛ بیشتر از ۱ به پشتیبانی مسیر نیاز دارد.
`output_compression`	Body	integer	اختیاری	مشروط	سطح فشرده‌سازی از ۰ تا ۱۰۰، برای قالب‌هایی که با افت کیفیت فشرده می‌شوند.
`output_format`	Body	string	اختیاری	مشروط	یکی از `png`، `jpeg` یا `webp`.
`prompt`	Body	string	الزامی	پشتیبانی می‌شود	prompt توصیف تصویر، حداکثر ۳۲٬۰۰۰ نویسه.
`quality`	Body	string	اختیاری	مشروط	یکی از `auto`، `low`، `medium`، `high`، `standard` یا `hd`.
`response_format`	Body	string	اختیاری	مشروط	`b64_json` یا `url`. مهوش همیشه URL متعلق به خودش را برمی‌گرداند.
`size`	Body	string	اختیاری	مشروط	`auto` یا `WIDTHxHEIGHT` در محدودهٔ تنظیم‌شده.
`style`	Body	string	اختیاری	مشروط	`vivid` یا `natural`، در مسیرهایی که آن را می‌پذیرند.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/images/generations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "prompt": "a red bicycle"
}'

Response

{
  "data": [
    {
      "url": "https://example.com/resource"
    }
  ],
  "created": 1750000000
}

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

کدهای وضعیت

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