دسترسی به API جمینای (Gemini) در ایران؛ مدل‌ها، قیمت و نمونه‌کد

گوگل در فهرست کشورهای پشتیبانی‌شدهٔ Gemini API نام کشورهایی را آورده که API و Google AI Studio در آن‌ها در دسترس است و ایران در این فهرست نیست. یعنی حتی با ساختن کلید، درخواست‌های ایران پذیرفته نمی‌شود و پرداخت هم به کارت بین‌المللی نیاز دارد.

هیبانا یک درگاه سازگار با OpenAI است: برنامهٔ شما به آدرس داخلی https://api-ai.hibanacloud.ir/v1 درخواست می‌فرستد و هزینه از کیف پول ریالی کم می‌شود. برای جمینای به کتابخانهٔ جداگانه‌ای نیاز ندارید؛ همان کتابخانهٔ openai کافی است و فقط نام مدل را عوض می‌کنید. اگر تازه شروع کرده‌اید، اول راهنمای API هوش مصنوعی و دریافت کلید API را ببینید.

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

ویژگی‌های مشترک این هفت مدل متنی طبق کاتالوگ:

• پنجرهٔ متن ۱٬۰۴۸٬۵۷۶ توکنی (حدود یک میلیون توکن)؛
• ورودی متن، تصویر، صوت و ویدیو، و خروجی متن؛
• پشتیبانی از فراخوانی ابزار (Function Calling)، حالت JSON و استریم؛
• سقف خروجی ۶۵٬۵۳۶ توکن برای مدل‌های Flash و Flash-Lite.

کنار این‌ها سه مدل تصویری جمینای هم هست که گوگل آن‌ها را با نام Nano Banana می‌شناساند: Nano Banana 2 Lite (gemini-3.1-flash-lite-image)، Nano Banana 2 (gemini-3.1-flash-image) و Nano Banana Pro (nano-banana-pro). یک مدل امبدینگ هم با نام Gemini Embedding 2 (gemini-embedding-2) در دسترس است.

گوگل در صفحهٔ مدل‌های Gemini API مدل‌های Flash-Lite را سریع‌ترین و کم‌هزینه‌ترین گزینه برای حجم بالای درخواست معرفی می‌کند و مدل‌های Flash را برای کارهای چندمرحله‌ای، کدنویسی و ایجنت‌ها. Pro رده‌ای است که قیمت بالاتری دارد. یک قاعدهٔ سرانگشتی برای شروع:

• دسته‌بندی، استخراج داده و خلاصه‌سازی پرتعداد: یکی از مدل‌های Flash-Lite. تفاوت قیمت در حجم بالا محسوس است.
• چت‌بات، کدنویسی و کارهای چندمرحله‌ای: Gemini 3.7 Flash یا 3.8 Flash. قیمت این دو در زمان نگارش یکی است.
• مسئله‌های سخت که کیفیت از هزینه مهم‌تر است: Gemini 3.1 Pro.

بهترین راه انتخاب، آزمایش روی داده‌های خودتان است: یک نمونهٔ واقعی را به دو مدل بدهید و کیفیت و هزینه را کنار هم بگذارید. برای مقایسهٔ مشخصات هم مقایسهٔ Flash و Pro را ببینید.

کتابخانه را با pip install openai نصب کنید. کد همان کد همیشگی OpenAI است و فقط base_url، کلید و نام مدل فرق می‌کند:

from openai import OpenAI client = OpenAI(    base_url="https://api-ai.hibanacloud.ir/v1",    api_key="YOUR_API_KEY",) response = client.chat.completions.create(    model="google/gemini-3.7-flash",    messages=[        {"role": "system", "content": "کوتاه و به فارسی پاسخ بده."},        {"role": "user", "content": "در دو جمله توضیح بده پنجرهٔ متن (context window) یک مدل زبانی چیست."},    ],) print(response.choices[0].message.content)print(response.usage)

خروجی در اجرای ما:

**پنجرهٔ متن** حداکثر میزان متنی (تعداد توکن‌هایی) است که یک مدل زبانی می‌تواند در یک زمان پردازش کند و به خاطر بسپارد. این ظرفیت مشخص می‌کند که مدل تا چه اندازه می‌تواند پیام‌های قبلی مکالمه یا بخش‌های یک متن طولانی را برای پاسخ‌دهی در حافظه نگه دارد.CompletionUsage(completion_tokens=602, prompt_tokens=29, total_tokens=631, completion_tokens_details=None, prompt_tokens_details=None, cost_rial=8619)

فیلد cost_rial هزینهٔ واقعی همین درخواست است: ۸٬۶۱۹ ریال، یعنی حدود ۸۶۲ تومان. حساب آن با جدول بالا جور است: ۲۹ توکن ورودی و ۶۰۲ توکن خروجی با قیمت Gemini 3.7 Flash. برای جزئیات این محاسبه توکن چیست و هزینهٔ API چطور حساب می‌شود را بخوانید.

همهٔ مدل‌های متنی جمینای در هیبانا تصویر هم می‌پذیرند. در این نمونه تصویر یک فاکتور ساده را به‌صورت Base64 می‌فرستیم و از مدل می‌خواهیم سه فیلد را به‌صورت JSON برگرداند:

import base64from openai import OpenAI client = OpenAI(base_url="https://api-ai.hibanacloud.ir/v1", api_key="YOUR_API_KEY") with open("invoice.png", "rb") as f:    image_b64 = base64.b64encode(f.read()).decode() response = client.chat.completions.create(    model="google/gemini-3.7-flash",    messages=[{        "role": "user",        "content": [            {"type": "text", "text": "شماره، تاریخ و مبلغ کل این فاکتور را فقط به‌صورت JSON با کلیدهای number، date و total برگردان."},            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_b64}"}},        ],    }],    response_format={"type": "json_object"},) print(response.choices[0].message.content)print("cost_rial:", response.usage.cost_rial)

تصویر آزمایشی ما یک فاکتور انگلیسی با شمارهٔ 1047 بود و خروجی این شد:

{  "number": "1047",  "date": "2026-10-05",  "total": "4,800,000 IRR"}cost_rial: 7910

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

مدل‌های تصویری جمینای از همان endpoint ساخت تصویر سازگار با OpenAI استفاده می‌کنند. در هیبانا پارامتر size نسبت ابعاد است، مثل 16:9، نه اندازه به پیکسل. نشانی تصویر خروجی هم موقت است، پس باید همان لحظه آن را ذخیره کنید:

import urllib.requestfrom openai import OpenAI client = OpenAI(base_url="https://api-ai.hibanacloud.ir/v1", api_key="YOUR_API_KEY") result = client.images.generate(    model="google/gemini-3.1-flash-lite-image",    prompt="A ceramic teapot and two small glass cups of tea on a wooden table, soft morning light, photo",    size="16:9",  # در هیبانا size نسبت ابعاد است، نه پیکسل) url = result.data[0].urlurllib.request.urlretrieve(url, "tea.jpg")  # لینک موقت است؛ همان لحظه ذخیره کنیدprint("saved tea.jpg")

در اجرای ما فایل خروجی یک JPEG با ابعاد ۱۳۷۶ در ۷۶۸ پیکسل بود:

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

برای جست‌وجوی معنایی و RAG به امبدینگ نیاز دارید. گوگل Gemini Embedding 2 را نخستین مدل امبدینگ چندوجهی خود معرفی می‌کند. در هیبانا این مدل از endpoint /v1/embeddings در دسترس است و طبق مستندات Embeddings علاوه بر متن، تصویر را هم می‌پذیرد؛ می‌توانید متن و تصویر را در یک آیتم بفرستید و یک بردار بگیرید. پنجرهٔ ورودی این مدل در کاتالوگ ۸٬۱۹۲ توکن است و قیمت ورودی متنی آن در زمان نگارش، ۷۶٬۰۰۰ تومان برای هر یک میلیون توکن.

اگر فقط متن فارسی دارید، مدل داخلی bge-m3 هم گزینهٔ خوبی است و چون روی سرورهای خود هیبانا اجرا می‌شود، در قطعی اینترنت بین‌الملل هم کار می‌کند. نمونهٔ کامل آن را در آموزش RAG فارسی با bge-m3 ببینید.

• قطعی اینترنت بین‌الملل: جمینای روی سرورهای گوگل اجرا می‌شود و وقتی ارتباط بین‌الملل قطع است، از هیچ مسیری در دسترس نیست. برای این روزها یک مدل داخلی جایگزین در نظر بگیرید؛ روش کار را در استفاده از API هوش مصنوعی بدون VPN نوشته‌ایم.
• ویژگی‌های اختصاصی گوگل: در هیبانا با رابط سازگار با OpenAI کار می‌کنید. پارامترهایی که فقط در SDK و API اختصاصی گوگل تعریف شده‌اند، لزوماً در این رابط وجود ندارند؛ پیش از تکیه بر یک ویژگی خاص، آن را در مستندات هیبانا بررسی و آزمایش کنید.
• قیمت‌ها ثابت نیستند: اعداد این مطلب مربوط به زمان نگارش‌اند و ممکن است تغییر کنند. همیشه صفحهٔ هر مدل در لیست مدل‌ها را ملاک بگذارید.

برای استفاده از Gemini در ایران به VPN یا کارت خارجی نیاز ندارید: با یک کلید هیبانا و کتابخانهٔ openai، مدل‌های متنی جمینای را برای چت و خواندن تصویر، Nano Banana را برای ساخت تصویر و Gemini Embedding 2 را برای امبدینگ صدا می‌زنید و هزینه را به ریال می‌پردازید. برای شروع، کلید API بگیرید، اولین درخواست را با Gemini 3.7 Flash بفرستید و اگر می‌خواهید جمینای را در ابزار کدنویسی‌تان به کار بگیرید، راهنمای اتصال ایجنت‌های کدنویسی را ببینید.