پرش به محتوا

API ساخت تصویر

API ساخت تصویر با نانو بنانا (Nano Banana) و GPT Image از یک نشانی: ساخت از متن، ویرایش با عکس مرجع، اندازه و کیفیت، پس‌زمینهٔ شفاف و هزینهٔ هر تصویر.

بازبینی: ۲۰ مهر ۱۴۰۵ ۸ دقیقه مطالعه

با POST /images/generations از روی توصیف متنی تصویر می‌سازید: تصویر شاخص مقاله، بنر، طرح محصول، آیکون. API ساخت تصویر گیسو مدل‌های چند سازنده را از همین یک مسیر جواب می‌دهد: GPT Image از OpenAI، نانو بنانا (Nano Banana) از Google و مدل‌هایی مثل FLUX، Recraft، Seedream و Qwen Image. فهرست کامل با GET /models?type=image می‌آید. نمونه‌کدهای ابتدای صفحه مدل gpt-image-1-mini را صدا می‌زنند و بخش نانو بنانا فرق‌های مدل‌های Google را می‌گوید.

POSThttps://gisoo.pro/api/v1/images/generations

نمونه

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/images/generations \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1-mini",
    "prompt": "Flat illustration of a Persian tea glass on a wooden table, warm morning light, no text",
    "size": "1024x1024",
    "quality": "medium"
  }' | jq -r '.data[0].b64_json' | base64 --decode > tea.png

خروجی همیشه به شکل base64 در data[].b64_json می‌آید و نشانی اینترنتی (URL) برنمی‌گردد؛ فایل را همان لحظه ذخیره کنید. گیسو تصویرهای ساخته‌شده با API را نگه نمی‌دارد.

پارامترها

model string الزامی
مدل تصویر؛ مثل gpt-image-1-mini.
prompt string الزامی
توصیف تصویر. انگلیسی معمولاً دقیق‌تر دنبال می‌شود؛ متنی که باید داخل تصویر نوشته شود را داخل گیومه بیاورید.
size string
اندازه؛ مقدارهای مجاز هر مدل در capabilities.sizes آن آمده است. رایج: 1024x1024، 1024x1536 (عمودی)، 1536x1024 (افقی).
quality string
low، medium یا high؛ مدل‌های تازه‌تر سطح‌های بالاتر هم دارند (capabilities.quality). کیفیت بالاتر توکن خروجی بیشتری می‌برد.
n integer
تعداد تصویر در یک درخواست؛ ۱ تا ۱۰. هزینه به همان نسبت بالا می‌رود.
background string
transparent برای پس‌زمینهٔ شفاف (با خروجی png یا webp).
output_format string
png، jpeg یا webp.

پس‌زمینهٔ شفاف

Python background: transparent
result = client.images.generate(
    model="gpt-image-1-mini",
    prompt="A minimal gold coffee-cup icon, centered",
    size="1024x1024",
    quality="high",
    background="transparent",   # PNG with alpha — for logos and stickers
    output_format="png",
)

API نانو بنانا (Nano Banana)

مدل‌های تصویر Gemini هم از همین مسیر جواب می‌دهند و کلید جدا نمی‌خواهند: gemini-3.1-flash-image (نانو بنانا ۲)، gemini-3-pro-image (نانو بنانا پرو) و gemini-3.1-flash-lite-image (نانو بنانا ۲ لایت). سه فرق با GPT Image دارند:

  • کیفیت یعنی وضوح: quality برای این مدل‌ها 1K، 2K یا 4K است (لایت فقط 1K). size فقط قاب را تعیین می‌کند؛ 1536x1024 یعنی قاب افقی با همان وضوح 1K، مگر quality بیشتری بخواهید.
  • عکس مرجع: یک تا چهار عکس را در فیلد image (base64 یا data URL) کنار توصیف بفرستید تا مدل همان عکس را تغییر دهد یا از چند عکس یک تصویر تازه بسازد؛ مثلاً عکس موبایلی یک محصول را روی زمینهٔ سفید فروشگاهی بنشاند.
  • بدون پس‌زمینهٔ شفاف: background: "transparent" در این مدل‌ها نیست؛ برای لوگو و استیکر با پس‌زمینهٔ شفاف، GPT Image 1.5 یا GPT Image 1 mini را بردارید.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

import base64
from openai import OpenAI

client = OpenAI(base_url="https://gisoo.pro/api/v1", api_key="sk-gisoo-v1-...")

# 1) From text: a 16:9 frame at 2K
banner = client.images.generate(
    model="gemini-3.1-flash-image",
    prompt="Product banner: a ceramic tea set on a walnut table, soft window light, empty space on the left, no text",
    size="1792x1024",
    quality="2K",          # 1K / 2K / 4K for Nano Banana
)
open("banner.png", "wb").write(base64.b64decode(banner.data[0].b64_json))

# 2) From your own photo: up to four reference images in "image"
photo = base64.b64encode(open("phone-shot.jpg", "rb").read()).decode()
clean = client.images.generate(
    model="gemini-3.1-flash-image",
    prompt="Place this exact product on a pure white studio background with a soft shadow; keep the label unchanged",
    extra_body={"image": ["data:image/jpeg;base64," + photo]},
)
open("product-white.png", "wb").write(base64.b64decode(clean.data[0].b64_json))

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

هزینه

مدل‌های GPT Image توکنی قیمت دارند: توکن‌های متن توصیف (ورودی) و توکن‌های خود تصویر (خروجی). اندازه و کیفیت بزرگ‌تر یعنی توکن خروجی بیشتر. تعداد دقیق در usage پاسخ می‌آید و هزینه از همان حساب می‌شود. پیش از درخواست، برای هر تصویر مبلغی به‌اندازهٔ یک تصویر کیفیت بالا کنار گذاشته می‌شود و بعد از پاسخ، فقط هزینهٔ واقعی کم می‌شود.

اول ارزان، بعد نهایی

ایده‌ها را با quality: "low" امتحان کنید و فقط برای نسخهٔ نهایی کیفیت را بالا ببرید. تصویر پیش‌نویس کسری از هزینهٔ تصویر نهایی را دارد.

نوشتن توصیف خوب

  • موضوع، سبک، نور، قاب: «a flat illustration»، «soft studio light»، «top-down view».
  • چیزی که نمی‌خواهید را بگویید: «no text»، «no watermark».
  • متن فارسی داخل تصویر هنوز برای مدل‌ها سخت است و ممکن است حروف به‌هم‌ریخته شوند. متن را بعداً با ابزار طراحی روی تصویر بگذارید.
  • برای تصویری که باید در چند اندازه تکرار شود، همان توصیف را نگه دارید و فقط size را عوض کنید.
سیاست محتوایی

سازندهٔ مدل درخواست‌هایی را که با سیاست محتوایی‌اش جور نیست رد می‌کند (خطای 400 upstream_rejected). درخواست ردشده هزینه‌ای ندارد.

پرسش‌های پرتکرار

API نانو بنانا (Nano Banana) را از گیسو می‌شود صدا زد؟

بله، از همان POST /images/generations و با همان کلید: gemini-3.1-flash-image (نانو بنانا ۲)، gemini-3-pro-image (نانو بنانا پرو) و gemini-3.1-flash-lite-image (نانو بنانا ۲ لایت). نسخه‌ها و هزینهٔ تقریبی هر تصویر را در صفحهٔ خانوادهٔ نانو بنانا کنار هم می‌بینید.

با API می‌شود عکس موجود را ویرایش کرد؟

با مدل‌های Nano Banana بله: یک تا چهار عکس مرجع را در فیلد image (base64 یا data URL) کنار توصیف بفرستید تا تصویر ویرایش یا ترکیب شود. مسیر جدای /images/edits شرکت OpenAI روی گیسو نیست.

پس‌زمینهٔ شفاف را کدام مدل می‌سازد؟

GPT Image 1.5 و GPT Image 1 mini با background: "transparent" و خروجی png یا webp. GPT Image 2 و مدل‌های Nano Banana پس‌زمینهٔ شفاف نمی‌سازند.

نوشتهٔ فارسی داخل تصویر درست درمی‌آید؟

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

خروجی API لینک می‌دهد یا فایل؟

فایل، به شکل base64 در data[].b64_json؛ لینکی برنمی‌گردد و گیسو تصویر را نگه نمی‌دارد. همان لحظه آن را در فضای خودتان ذخیره کنید.

قدم بعدی

پاسخ پرسشتان را پیدا نکردید؟

شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

تیکت پشتیبانی