مستندات APIمسیرهاImage to Image

ویرایش عکس

یک یا چند عکس مرجع را همراه با پرامپت بفرستید و نسخه‌ای تازه از آن‌ها بسازید؛ تغییر سبک، حذف یا افزودن عناصر و ترکیب چند عکس.

نسخهٔ API: v1

مسیر درخواست

POSThttps://bananaai.ir/api/v1/images/edits

مثل تولید عکس یک تسک ناهمگام می‌سازد، با این تفاوت که یک یا چند عکس مرجع هم می‌گیرد. برای تغییر سبک، جایگزینی پس‌زمینه، افزودن یا حذف عناصر و ترکیب چند عکس مناسب است.

پارامترهای درخواست

بدنهٔ درخواست باید JSON باشد (Content-Type: application/json).

promptstringالزامی: توضیح تغییری که می‌خواهید روی عکس اعمال شود. بگویید چه چیزی ثابت بماند و چه چیزی عوض شود.; مثال:این عکس را به سبک آبرنگ تبدیل کن
image_urlsstring[]الزامی: آرایه‌ای از نشانی عکس‌های مرجع (حداکثر 3 عکس). نشانی‌ها باید عمومی و بدون نیاز به ورود باشند.; مثال:["https://example.com/source.jpg"]
modelstringاختیاری: شناسهٔ مدل. همهٔ مدل‌های عکس از ویرایش پشتیبانی می‌کنند؛ فهرست و هزینه در اعتبار و هزینه.; پیش‌فرض:nano-banana-2مثال:nano-banana-2nano-banana-2-1nano-litenano-progrok-speedgrok-qualitygpt-image-2-5-flaregpt-image-2-5-sunburstseedream-5-proflux-3-image
image_sizestringاختیاری: نسبت عکس خروجی. برای حفظ ابعاد عکس مرجع همان نسبت را بفرستید.; پیش‌فرض:9:16مثال:16:91:19:16
resolutionstringاختیاری: کیفیت خروجی برای مدل‌هایی که چند کیفیت دارند. در بقیهٔ مدل‌ها نادیده گرفته می‌شود.; مثال:1K2K4K
num_imagesintegerاختیاری: تعداد نسخهٔ خروجی (۱ تا ۴) در مدل‌هایی که چند خروجی را پشتیبانی می‌کنند.; پیش‌فرض:1مثال:124
metadataobjectاختیاری: جفت‌های کلید/مقدار دلخواه (تا ۱۶ کلید، مقدار حداکثر ۵۰۰ کاراکتر) مثل شناسهٔ سفارش شما. در پاسخ تسک و بدنهٔ وب‌هوک عیناً برمی‌گردد تا نتیجه را به رکورد خودتان وصل کنید.; مثال:{"order_id":"1042"}

دسترسی به عکس‌های مرجع

سرویس باید بتواند همهٔ نشانی‌ها را مستقیماً دانلود کند. عکس‌های پشت صفحهٔ ورود، پشت فایروال یا با لینک موقت منقضی‌شده باعث ناموفق شدن تسک می‌شوند (بدون کسر اعتبار). اگر فایل‌ها خصوصی‌اند، یک لینک امضاشده با مهلت کافی بسازید.

نمونه درخواست

bash

curl -X POST "https://bananaai.ir/api/v1/images/edits" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "prompt": "این عکس را به سبک آبرنگ تبدیل کن",
  "image_urls": [
    "https://example.com/source.jpg"
  ],
  "image_size": "1:1",
  "resolution": "2K"
}'

پاسخ

JSON

1{
2  "id": "task_xyz789",
3  "status": "pending",
4  "model": "nano-banana-2",
5  "credits_reserved": 8,
6  "created_at": "2026-07-04T12:00:00.000Z"
7}

شناسهٔ تسک در فیلد id است. پاسخ فقط تأیید ثبت درخواست است و خروجی هنوز آماده نیست.

دریافت نتیجه

وضعیت را از GET /api/v1/tasks/:id پیگیری کنید. پس از completed، نشانی نسخه‌های ویرایش‌شده در آرایهٔ images قرار دارد:

JSON

1{
2  "id": "task_xyz789",
3  "status": "completed",
4  "type": "image",
5  "model": "nano-banana-2",
6  "prompt": "این عکس را به سبک آبرنگ تبدیل کن",
7  "images": ["https://cdn.bananaai.ir/.../edited.png"],
8  "videos": [],
9  "error": null,
10  "credits_reserved": 8,
11  "credits_deducted": true,
12  "created_at": "2026-07-04T12:00:00.000Z",
13  "completed_at": "2026-07-04T12:00:22.000Z"
14}

نکته

الگوی کامل پیگیری با نمونه‌کد در الگوی پیگیری آمده است.