تولید عکس

با ارسال یک پرامپت متنی، یک یا چند عکس جدید بسازید. مدل، نسبت تصویر و کیفیت خروجی را در بدنهٔ درخواست تعیین کنید.

نسخهٔ API: v1

مسیر درخواست

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

یک تسک تولید عکس می‌سازد و بلافاصله شناسهٔ آن را برمی‌گرداند. هزینه در لحظهٔ ثبت رزرو و پس از تولید موفق کسر می‌شود. از هدر اختیاری Idempotency-Key پشتیبانی می‌کند.

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

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

promptstringالزامی: توضیح متنی عکس موردنظر. فارسی و انگلیسی هر دو پشتیبانی می‌شوند؛ توضیح دقیق‌تر، نتیجهٔ نزدیک‌تر.; مثال:شهری آینده‌نگر در غروب
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اختیاری: کیفیت خروجی برای مدل‌هایی که چند کیفیت دارند (GPT Image، Seedream). در بقیهٔ مدل‌ها نادیده گرفته می‌شود.; مثال:1K2K4K
num_imagesintegerاختیاری: تعداد عکس خروجی (۱ تا ۴). فقط برای مدل‌هایی که چند خروجی را پشتیبانی می‌کنند؛ هزینه به ازای هر عکس محاسبه می‌شود.; پیش‌فرض:1مثال:124
metadataobjectاختیاری: جفت‌های کلید/مقدار دلخواه (تا ۱۶ کلید، مقدار حداکثر ۵۰۰ کاراکتر) مثل شناسهٔ سفارش شما. در پاسخ تسک و بدنهٔ وب‌هوک عیناً برمی‌گردد تا نتیجه را به رکورد خودتان وصل کنید.; مثال:{"order_id":"1042"}

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

bash

curl -X POST "https://bananaai.ir/api/v1/images/generations" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana-2",
  "prompt": "شهری آینده‌نگر در غروب",
  "image_size": "9:16",
  "resolution": "2K"
}'

پاسخ

پاسخ 200 یعنی تسک ثبت شده است، نه اینکه عکس آماده است. فیلد id را نگه دارید.

JSON

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

idstring: شناسهٔ تسک برای پیگیری. نام فیلد taskId یا task_id نیست.
statusstring: وضعیت اولیهٔ تسک؛ همیشه pending است.
credits_reservedinteger: اعتباری که برای این تسک رزرو شده و پس از موفقیت کسر می‌شود.

دریافت نتیجه

هر ۳ تا ۵ ثانیه GET /api/v1/tasks/:id را بخوانید. وقتی status به completed رسید، نشانی عکس‌ها در آرایهٔ images قرار دارد:

JSON

1{
2  "id": "task_abc123",
3  "status": "completed",
4  "type": "image",
5  "model": "nano-banana-2",
6  "prompt": "شهری آینده‌نگر در غروب",
7  "images": ["https://cdn.bananaai.ir/.../output.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:19.000Z"
14}

نکته

نشانی خروجی‌ها را در فضای ذخیره‌سازی خودتان کپی کنید؛ برای ساختار کامل تسک و الگوی پیگیری، صفحهٔ پیگیری وضعیت تسک را ببینید.