API نانو بنانا پرو در ایران: ساخت و ویرایش تصویر با Nano Banana Pro، 2 و 2.1

نانو بنانا اسمی است که Google روی مدل‌های تصویر خانوادهٔ Gemini گذاشته و Nano Banana Pro را پیشرفته‌ترینِ آن‌ها معرفی کرده است. اگر می‌خواهی API نانو بنانا پرو را از داخل کد خودت صدا بزنی، در یوتاپن با شناسهٔ google/gemini-3-pro-image در دسترس است: همان SDK رسمی OpenAI، فقط base_url عوض می‌شود، و هزینه از کیف پول تومانی کم می‌شود. کنار Pro، سه نسخهٔ Flash هم هست، یعنی Nano Banana 2، Nano Banana 2.1 و Nano Banana 2 Lite، که برای خیلی از کارها انتخاب منطقی‌تری‌اند.

اینجا فقط دربارهٔ همین خانواده حرف می‌زنیم: کدام نسخه برای چه کاری، ساخت و ویرایش با تصویر مرجع، نسبت ابعاد و رزولوشن، و اینکه هزینهٔ یک تصویر Gemini دقیقاً از چه اجزایی ساخته می‌شود. اگر دنبال مقایسهٔ همهٔ مدل‌های تصویر (FLUX، Seedream، GPT Image و بقیه) هستی، راهنمای کلی API ساخت عکس با هوش مصنوعی جای بهتری است.

خانوادهٔ نانو بنانا در API یوتاپن

چهار مدل این خانواده در کاتالوگ قابل استفاده‌اند. ستون «به گفتهٔ سازنده» از توضیحی آمده که Google منتشر کرده و در کاتالوگ ما هست. ما رتبه‌بندی کیفیت یا عدد بنچمارک نمی‌دهیم، چون کیفیت تصویر به موضوع و سبک کار تو بستگی دارد.

هر چهار مدل هم متن و هم تصویر ورودی می‌گیرند و در خروجی تصویر و متن می‌دهند. یعنی هم برای ساخت تصویر از صفر کار می‌کنند و هم برای ویرایش عکسی که خودت می‌فرستی. هیچ‌کدام رایگان نیست.

کدام نانو بنانا را انتخاب کنم

بر اساس توضیح سازنده و قیمت‌گذاری امروز کاتالوگ، این‌طور تصمیم بگیر:

• Nano Banana 2 نقطهٔ شروع خوبی است. سازنده آن را «کیفیت Pro با سرعت Flash» معرفی کرده و حالت خودکار یوتاپن (uttapen/auto-image) هم امروز برای ویرایش عکس و پوستر متن‌دار همین مدل را انتخاب می‌کند.
• Nano Banana 2.1 برای عکس محصول. سازنده صراحتاً گفته این نسخه در «product recontextualization» بهتر شده، یعنی گرفتن عکس یک محصول و نشاندنش در صحنه، نور یا پس‌زمینهٔ تازه. اگر فروشگاه اینترنتی داری، اول این را امتحان کن. در برآورد هر تصویرِ کاتالوگ هم امروز ارزان‌تر از Nano Banana 2 درمی‌آید، هرچند توکن متنی‌اش گران‌تر است.
• Nano Banana Pro وقتی درخواستت پیچیده است. صحنهٔ شلوغ با چند جزء، دستور چندمرحله‌ای، یا جایی که مدل باید چیزی را درست از دنیای واقعی بداند. Pro در صفحهٔ مدلش در دستهٔ قیمتی «گران» است و در برآورد هر تصویر، گران‌ترینِ این خانواده. پس اول همان پرامپت را روی نسخه‌های Flash بزن و اگر نتیجه راضی‌ات نکرد سراغ Pro برو.
• Nano Banana 2 Lite برای حجم بالا. پیش‌نویس، تست ایده، یا ساخت صدها تصویر که کیفیت نهایی‌شان حیاتی نیست.

یک تفاوت فنی هم هست: Pro و 2.1 در supported_parameters ابزار (tools) دارند و Nano Banana 2 ندارد. این فقط وقتی مهم است که مدل را از مسیر chat/completions و داخل یک ایجنت صدا بزنی.

ساخت تصویر با Nano Banana Pro در Python

مسیر POST /v1/images/generations همان شکل OpenAI را دارد، پس client.images.generate بدون تغییر کار می‌کند. پاسخ همگام (synchronous) است و درخواست تا ساخته شدن تصویر باز می‌ماند، معمولاً چند ثانیه تا یک دقیقه. فیلدهایی که SDK رسمی نمی‌شناسد، مثل aspect_ratio و resolution، داخل extra_body می‌روند:

import os
import urllib.request
from openai import OpenAI

client = OpenAI(base_url="https://api.uttapen.ir/v1", api_key=os.environ["UTTAPEN_API_KEY"])

raw = client.images.with_raw_response.generate(
    model="google/gemini-3-pro-image",
    prompt="نمای داخلی یک کتاب‌فروشی کوچک در تهران قدیم، قفسه‌های چوبی، نور عصر از پنجره",
    n=1,
    extra_body={"aspect_ratio": "16:9", "resolution": "2K", "output_format": "webp"},
)
img = raw.parse()

urllib.request.urlretrieve(img.data[0].url, "bookshop.webp")   # لینک امضاشده، ۲۴ ساعت معتبر
print("هزینه:", raw.headers.get("X-Uttapen-Cost-Toman"), "تومان")

برای عوض کردن مدل فقط رشتهٔ model را تغییر بده، مثلاً google/gemini-3.1-flash-image یا google/gemini-nano-banana-2.1. باقی کد همان است.

همین درخواست با curl:

curl https://api.uttapen.ir/v1/images/generations \
  -H "Authorization: Bearer $UTTAPEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-pro-image",
    "prompt": "a small old bookshop in Tehran, wooden shelves, warm afternoon light",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

پاسخ یک data[0].url دارد و یک بلوک uttapen که cost_toman (هزینهٔ نهایی همین ساخت) و hold_toman (مبلغی که پیش از ساخت رزرو شده بود) را نشان می‌دهد. اگر وسط کار اتصالت قطع شود، ساخت تمام می‌شود و نتیجه را با GET /v1/uttapen/media/{id} می‌گیری. شناسه در هدر X-Uttapen-Media-Id آمده. فایل‌ها ۳۰ روز روی سرور ما در ایران می‌مانند و بعد پاک می‌شوند.

نسبت ابعاد و رزولوشن

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

ویرایش عکس با تصویر مرجع

نانو بنانا فقط برای ساخت از صفر نیست و برای ویرایش هم ساخته شده: عکسی می‌فرستی و با یک جمله می‌گویی چه چیزی عوض شود. تصویر یا تصویرها در فیلد image یا images می‌روند. قواعدش:

• طبق مستندات، حداکثر ۴ تصویر مرجع در هر درخواست، هرکدام تا ۱۰ مگابایت. همهٔ مدل‌ها به یک اندازه تصویر مرجع نمی‌خوانند، پس برای اطمینان از همین سقف بیشتر نفرست.
• هر تصویر یک آدرس https است یا data:image/png|jpeg|webp;base64,....
• مدلی که ورودی تصویر نمی‌پذیرد خطای 400 با param: "images" می‌دهد. هر چهار مدل این خانواده ورودی تصویر دارند، پس با این‌ها چنین خطایی نمی‌بینی.

img = client.images.generate(
    model="google/gemini-nano-banana-2.1",
    prompt="این قوری را روی میز صبحانهٔ یک خانهٔ روستایی بگذار، نور صبح از سمت چپ، سایهٔ طبیعی",
    n=1,
    extra_body={
        "images": ["https://example.com/teapot.jpg"],
        "aspect_ratio": "1:1",
    },
)
print(img.data[0].url)

با چند تصویر مرجع می‌توانی اجزا را ترکیب کنی، مثلاً یک محصول و یک عکس از فضای مغازه، و در پرامپت بگویی هر کدام چه نقشی دارد. اگر فایل روی دیسک خودت است، آن را با base64 به شکل data:image/jpeg;base64,... بفرست.

اگر هدفت خواندن و تحلیل محتوای یک عکس است، نه ساختن تصویر تازه، این کار مدل vision است و از مسیر chat/completions انجام می‌شود.

هزینهٔ API نانو بنانا چطور حساب می‌شود

مدل‌های نانو بنانا برخلاف مدلی مثل Seedream قیمت ثابت برای هر تصویر ندارند. هزینه از سه جزء ساخته می‌شود و هر سه در فیلد pricing کاتالوگ (GET /v1/models) و در صفحهٔ خود مدل جدا آمده‌اند:

1. توکن ورودی: پرامپت تو و تصویرهای مرجع. برای Nano Banana Pro امروز ۶۹۲٬۴۳۹ تومان به‌ازای هر میلیون توکن است. Pro برای تصویر ورودی یک جزء جداگانهٔ کوچک هم دارد.
2. توکن خروجی متن: مدل کنار تصویر معمولاً چند جمله متن هم برمی‌گرداند. توکن‌های استدلال (reasoning) هم جزو همین‌اند. برای Pro امروز ۴٬۱۵۴٬۶۳۲ تومان به‌ازای هر میلیون توکن.
3. تصویر خروجی (image_output): خود تصویر به شکل توکن‌های خروجیِ تصویر شمرده می‌شود، با نرخی جدا و بسیار بالاتر از توکن خروجی متن. در کاتالوگ امروز، نرخ هر توکن تصویر برای Pro حدود ده برابر توکن خروجی متن همان مدل است و برای Nano Banana 2 حدود بیست برابر. یعنی سهم اصلی هزینه را همین جزء می‌سازد.

تعداد توکن‌های یک تصویر به رزولوشن بستگی دارد. تصویر 1K تقریباً هزار و چند صد توکن تصویر است و 4K بیشتر؛ برای Nano Banana 2، 2K هم از 1K بیشتر است. پس رزولوشن بالاتر معمولاً گران‌تر است و رزرو پیش از ساخت هم بزرگ‌تر می‌شود. برای مقایسه، Nano Banana 2 امروز ۱۷۳٬۱۱۰ تومان ورودی و ۱٬۰۳۸٬۶۵۸ تومان خروجی به‌ازای هر میلیون توکن می‌گیرد، به‌اضافهٔ نرخ تصویر خروجی خودش. قیمت روز 2.1 و Lite هم روی صفحهٔ همان مدل است.

برآورد تومانی «هر تصویر» برای یک ساخت معمولی در فهرست مدل‌های تصویر آمده. آن عدد تقریبی است، چون پرامپت بلندتر، تصویر مرجع بیشتر و رزولوشن بالاتر هزینه را بالا می‌برد.

رزرو، بعد هزینهٔ واقعی

روند پرداخت در یوتاپن برای هر ساخت این است:

1. پیش از ساخت، مبلغی از کیف پول رزرو می‌شود. این برآورد محتاطانه بر اساس قیمت مدل، طول پرامپت، تعداد تصویر مرجع و رزولوشنی که خواسته‌ای حساب می‌شود. اگر موجودی برای رزرو کافی نباشد، خطای 402 با کد insufficient_balance می‌گیری و ساختی شروع نمی‌شود.
2. بعد از ساخت، فقط هزینهٔ واقعی‌ای که سازندهٔ مدل برای همین تصویر گزارش می‌کند کم می‌شود و بقیهٔ رزرو بلافاصله برمی‌گردد. عدد نهایی در uttapen.cost_toman و هدر X-Uttapen-Cost-Toman می‌آید و موجودی تازه در X-Uttapen-Balance-Toman.
3. ساخت ناموفق رایگان است. خطا، رد شدن درخواست به‌خاطر قوانین محتوا یا نرسیدن فایل، کل رزرو را آزاد می‌کند.

پس hold_toman در پاسخ قیمت نیست؛ cost_toman قیمت است. جزئیات کامل پرداخت رسانه در مستندات رسانه آمده.

راه دوم: مسیر chat/completions

مدل‌های نانو بنانا را از مسیر chat/completions هم می‌شود صدا زد، با فیلد modalities: ["image", "text"]. در این حالت تصویر به شکل base64 داخل message.images برمی‌گردد و می‌توانی متن و تصویر را در یک گفتگوی چندمرحله‌ای کنار هم داشته باشی. نمونه‌کد کامل این روش روی صفحهٔ هر مدل هست و توضیحش در راهنمای API Gemini در ایران آمده. برای ساخت و ویرایش ساده، مسیر images/generations تمیزتر است، چون لینک فایل، cost_toman و نگهداری ۳۰ روزه را آماده می‌دهد.

مقایسهٔ نسخه‌ها پیش از نوشتن کد

اگر پیش از نوشتن کد می‌خواهی این نسخه‌ها را روی پرامپت خودت مقایسه کنی، استودیوی یوتاپن همین کار را در مرورگر می‌کند: مدل را انتخاب می‌کنی، پیش از ساخت برآورد تومانی را می‌بینی، و بعد از ساخت فقط هزینهٔ واقعی کم می‌شود. کیف پولش همان کیف پول API است. حساب نداری؟ حساب بساز و کلید API بگیر و یک پرامپت را اول با Nano Banana 2 و بعد با Pro بساز تا cost_toman و کیفیت دو خروجی را کنار هم ببینی.

سؤال‌های رایج

nano banana api را با Python چطور صدا بزنم؟

کتابخانهٔ openai را نصب کن، base_url را https://api.uttapen.ir/v1 بگذار و کلید sk-up- را از متغیر محیطی بخوان. بعد client.images.generate را با model="google/gemini-3.1-flash-image" (Nano Banana 2) یا google/gemini-3-pro-image (Pro) صدا بزن. فیلدهای aspect_ratio، resolution و images داخل extra_body می‌روند. کد کامل در بخش‌های بالاست.

قیمت nano banana pro api ثابت است؟

نه. قیمت تومانی با قیمت سازنده و نرخ ارز عوض می‌شود و هزینهٔ هر ساخت هم به طول پرامپت، تصویر مرجع و رزولوشن بستگی دارد. قیمت روز هر سه جزء روی صفحهٔ Nano Banana Pro است و هزینهٔ دقیق هر ساخت در cost_toman پاسخ همان درخواست.

چرا Nano Banana 2.1 با اینکه توکن متنی‌اش گران‌تر است، در برآورد هر تصویر ارزان‌تر درمی‌آید؟

چون سهم اصلی هزینه را توکن‌های تصویر خروجی می‌سازند، نه متن. در کاتالوگ امروز نرخ تصویر خروجی 2.1 پایین‌تر از Nano Banana 2 است، در حالی که نرخ توکن متنی‌اش بالاتر است. اگر پرامپتت کوتاه است و فقط تصویر می‌خواهی، همین نرخ تصویر تعیین‌کننده است.

می‌توانم در یک درخواست چند تصویر بسازم؟

بله، با n از ۱ تا ۴. بیش از ۳ ساخت هم‌زمان خطای 429 با کد too_many_active_jobs می‌دهد. برای حجم بالا درخواست‌ها را در صف بگذار و هدر Retry-After را رعایت کن.

هر عکسی را می‌شود با نانو بنانا ساخت یا ویرایش کرد؟

نه. تصویر شبیه افراد واقعی، محتوای جنسی و خشونت شدید ساخته نمی‌شود. چنین درخواستی پیش از هر هزینه‌ای با خطای content_policy_violation و پیام فارسی رد می‌شود. اگر خود سازندهٔ مدل درخواست را رد کند هم چیزی از کیف پول کم نمی‌شود.