تصویرها
همه مدل‌های تصویر با یک ساختار درخواست یکسان. اعتبار هر مدل، محدودیت‌های
پرامپت، سقف تصویرهای ورودی و کیفیت‌ها در بخش «مدل‌های تصویر» در صفحه
معرفی آمده‌اند و نسبت‌های تصویر در GET /models/.
تولید تصویر
یک تسک تولید تصویر ارسال می‌شود و اعتبار آن کسر می‌شود. فرستادن مدیای ورودی، درخواست را به ویرایش تبدیل می‌کند؛ تعداد ورودی‌هایی که مدل‌ها می‌پذیرند متفاوت است (بخش «مدل‌های تصویر» در صفحه معرفی را ببینید).
آیدی‌های آپلود را در uploads بفرستید. در این اندپوینت، فیلد شماره‌دار
image1 فقط به‌صورت بخش فایل خوانده می‌شود؛ پس آیدی آپلودی که در آن
بفرستید نادیده گرفته می‌شود. برای پیوست مستقیم فایل‌ها با نام‌های
image1…imageN، به‌جای JSON از multipart/form-data استفاده کنید.
هدرها
Idempotency-Keyتلاش دوباره برای این ارسال را بی‌خطر می‌کند. تکرار درخواست ظرف 15 دقیقه،
body اصلی را با وضعیت 200 برمی‌گرداند و دوباره اعتباری کسر نمی‌شود؛ تکرار
در حالی که درخواست اول هنوز در حال پردازش است، 409 request_in_progress
برمی‌گرداند.
کلید همراه با پرامپت درخواست (در گفتار، دیالوگ آن) هویت درخواست را تعیین
می‌کند؛ پس استفاده دوباره از یک کلید با پرامپتی متفاوت، تولید جدیدی را
شروع می‌کند. فیلد client_request_id در body هم دقیقاً همین‌طور عمل
می‌کند.
تولید تصویر › body درخواست
modelبا نام mode هم پذیرفته می‌شود؛ اگر هر دو فرستاده شوند، mode
اولویت دارد. اگر تعداد تصویرهای ورودی از سقف مدل بیشتر باشد، با
خطای too_many_images رد می‌شود.
promptآنچه باید ساخته شود، یا اینکه ورودی‌ها چطور ویرایش شوند. اگر طول آن
از max_prompt_chars مدل بیشتر باشد، با خطای prompt_too_long رد
می‌شود.
image_urlsURLهای تصویر https:// که به‌صورت عمومی در دسترس باشند. لینک‌های مدیای هوشا با خطای invalid_image_url رد می‌شوند؛ آن فایل‌ها را از طریق uploads بفرستید. در multipart این فیلد را تکرار کنید.
uploadsآیدی‌های آپلود دریافتی از POST /uploads/. هر آیدی یک‌بارمصرف است و
حدود 20 دقیقه پس از آپلود منقضی می‌شود. /images/ آیدی‌های آپلود را
فقط از همین فیلد می‌خواند؛ آیدی‌ای که در image1 فرستاده شود نادیده
گرفته می‌شود.
aspect_ratioپیش‌فرض در chatgpt-image-2.0، مدل‌های chatgpt-image-2.5-* و
nano-banana-2-1 برابر auto و در chatgpt-image-1.5 و
grok-imagine-2 برابر 1:1 است. این مدل‌ها مقدار را بررسی
می‌کنند و نسبت پشتیبانی‌نشده در آن‌ها با خطای
invalid_aspect_ratio رد می‌شود. بقیه مدل‌ها نسبتی را که
نمی‌توانند بسازند، به‌جای رد کردن، جایگزین می‌کنند: hoosha-v1 با
auto می‌سازد، nano-banana-2-pro و seedream4 با 1:1 و
flux_kontext با 16:9، حتی برای پیش‌فرض 4:3. در محدوده
aspect_ratios هر مدل در GET /models/ بمانید.
qualityفقط برای مدل‌های دارای سطح‌بندی کیفیت (nano-banana-2-1،
nano-banana-2-pro، chatgpt-image-2.0 و مدل‌های
chatgpt-image-2.5-*)؛ سطح قیمت را تعیین می‌کند و پیش‌فرض آن در
nano-banana-2-1 برابر 1K است. بقیه مدل‌ها آن را نادیده
می‌گیرند. با نام resolution هم پذیرفته می‌شود؛ اگر هر دو فرستاده
شوند، quality اولویت دارد. هر مقدار دیگری با خطای
invalid_quality رد می‌شود.
levelفقط برای مدل‌های chatgpt-image-2.5-*؛ بقیه مدل‌ها آن را نادیده
می‌گیرند. low و medium با قیمت جدول محاسبه می‌شوند. high،
xhigh و max به یک aspect_ratio مشخص و کیفیت 2K یا 4K نیاز
دارند، اعتبار جدول سطح‌ها را رزرو می‌کنند و پس از تحویل تصویر با
هزینه واقعی تسویه می‌شوند. هر مقدار دیگری با خطای invalid_level
رد می‌شود.
backgroundفقط برای مدل‌های chatgpt-image-2.5-* و در همه سطح‌ها؛ بقیه مدل‌ها
آن را نادیده می‌گیرند. هر مقدار دیگری با خطای invalid_background
رد می‌شود.
output_formatفقط برای nano-banana-2-pro؛ بقیه مدل‌ها آن را نادیده می‌گیرند. هر
مقدار دیگری با خطای invalid_output_format رد می‌شود.
تولید تصویر › پاسخ‌ها
تکرار درخواست با همان Idempotency-Key ظرف 15 دقیقه. body پاسخ
بایت‌به‌بایت با پاسخ 202 اصلی یکسان است و دوباره اعتباری کسر نشده است.
idوضعیت را با GET /generations/{id}/ بررسی کنید.
typeنوع مدیای تسک.
modelمدل، همان‌طور که در درخواست فرستاده‌اید.
statusهمیشه processing؛ هنوز چیزی ساخته نشده است.
credits_chargedاز قبل کسر شده است. این قیمت نهایی است، به‌جز در تسک‌های edit/extend مدل seedance25 که این مبلغ رزرو اعتبار است و پس از تحویل، بخشی از آن بازگردانده می‌شود.
created_at