API Gemini (جمینای) در ایران: خرید، قیمت تومانی و راهنمای اتصال

Gemini (که خیلی‌ها «جمینای» یا «جمنای» می‌نویسند) خانوادهٔ مدل‌های زبانی Google است و برای برنامه‌نویس چند ویژگی جذاب دارد: context یک‌میلیون‌توکنی در همهٔ نسخه‌های اصلی، ورودی تصویر و PDF و صوت و ویدیو در همان درخواست، و نسخه‌های Flash Lite که برای کار پرحجم کم‌هزینه‌اند. ولی خانواده بزرگ است و اسم نسخه‌ها گیج‌کننده: Flash Lite، Flash، Pro، Preview، و چند نسل که هم‌زمان در کاتالوگ‌اند. این مقاله جواب سه سؤال است: از ایران چطور API Gemini بخری و کلید API جمینای را با پرداخت تومانی بگیری؛ هر نسخه دقیقاً چقدر خرج دارد؛ و برای کار تو کدام منطقی‌تر است. کد آمادهٔ Python، Node.js و curl هم داری.

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

چرا خرید مستقیم API Gemini از ایران سخت است

برای کار با API رسمی Gemini باید حساب Google Cloud یا AI Studio داشته باشی و صورت‌حساب را به ارز خارجی، با کارت بانکی بین‌المللی، پرداخت کنی. کارت ایرانی آنجا کار نمی‌کند و ایران هم جزو منطقه‌هایی که Google این API را در آن‌ها عرضه می‌کند نیست. پس یا باید به حساب و کارت کسی خارج از کشور تکیه کنی، یا به سرویس‌های کارت مجازی که کارمزد تبدیل ارز دارند و هر بار شارژ یک هماهنگی تازه می‌خواهد. اگر حسابی که پروژه‌ات به آن وابسته است یک روز بسته شود، محصولت هم همان روز از کار می‌افتد. جزئیات این مسیرها و ریسک هر کدام را در راهنمای دسترسی به API مدل‌ها از ایران نوشته‌ایم.

راه کوتاه‌تر: با موبایل ایرانی ثبت‌نام می‌کنی، کیف پول را از درگاه زیبال به تومان شارژ می‌کنی، یک کلید sk-up- می‌سازی و با SDK رسمی OpenAI به همهٔ مدل‌های Gemini وصل می‌شوی. آدرس api.uttapen.ir داخل ایران است و VPN لازم نیست؛ مسیر بین‌المللی درخواست را زیرساخت ما در خارج از ایران مدیریت می‌کند. یک کلید هم کافی است: همان کلید برای Claude، GPT، DeepSeek و بقیهٔ کاتالوگ هم کار می‌کند.

قیمت API Gemini (جمینای) به تومان

ستون آخر هزینهٔ یک درخواست معمولی فارسی است: حدود ۱٬۰۰۰ کلمه ورودی (تقریباً ۱٬۷۸۰ توکن) و ۵۰۰ کلمه پاسخ (حدود ۸۹۰ توکن). همین مبنا را در مقالهٔ قیمت API مدل‌ها به تومان، راهنمای API کلاد و راهنمای API دیپ سیک هم به کار برده‌ایم، پس اعداد قابل مقایسه‌اند. قیمت‌ها به‌ازای هر یک میلیون توکن و به تومان است. context همهٔ مدل‌های این جدول ۱٬۰۴۸٬۵۷۶ توکن است.

فهرست کامل همهٔ مدل‌های Google، از جمله نسخه‌های preview، نسخه‌های :batch، مدل‌های تصویر و صوت و خانوادهٔ متن‌باز Gemma، با قیمت زنده در صفحهٔ مدل‌های Google است. چند نکته از همین جدول:

• شمارهٔ نسخه قیمت را تعیین نمی‌کند. در این خانواده نسخهٔ جدیدتر لزوماً گران‌تر نیست و لزوماً ارزان‌تر هم نیست. مثلاً امروز یک درخواست هزارکلمه‌ای با gemini-3.5-flash حدود ۳٬۷۰۰ تومان است و با gemini-3.8-flash حدود ۱٬۶۰۰ تومان. پیش از انتخاب، هزینهٔ هر درخواست را نگاه کن، نه عدد نسخه را.
• فاصلهٔ Flash Lite و Pro زیاد است. context همه یکسان است، ولی هزینهٔ یک درخواست بین ارزان‌ترین Flash Lite و Pro چندین برابر فرق می‌کند (ستون آخر را ببین). برای کاری که Flash Lite از پسش برمی‌آید، Pro فقط صورت‌حساب را بالا می‌برد.
• با کمترین شارژ کیف پول (مبلغش در صفحهٔ قیمت‌ها آمده) امروز حدود ۵۴۰ درخواست هزارکلمه‌ای با gemini-2.5-flash-lite، حدود ۱۰۴ درخواست با gemini-2.5-flash و حدود ۲۰ درخواست با gemini-3.1-pro-preview می‌زنی.
• نسخه‌های :batch ارزان‌ترند. همهٔ مدل‌های متنی این جدول یک نسخه با پسوند :batch دارند که ارزان‌تر ولی کندتر است؛ مثلاً امروز همان درخواست با google/gemini-2.5-flash:batch حدود — تومان در برابر ۹۶۰ تومان نسخهٔ عادی تمام می‌شود. برای کار پس‌زمینه که منتظر جواب فوری نیستی، ارزش امتحان دارد.

همهٔ مدل‌های این جدول استدلال (reasoning)، tool calling و خروجی JSON ساخت‌یافته را پشتیبانی می‌کنند، و علاوه بر متن، تصویر، فایل PDF، صوت و ویدیو را هم به‌عنوان ورودی می‌گیرند. سقف پاسخ در هر فراخوانی حدود ۶۵ هزار توکن است.

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

عدد بنچمارک نمی‌آوریم؛ کیفیت را روی دادهٔ خودت بسنج. ولی بر اساس قیمت و جایگاه هر نسخه در خانواده، این نقطهٔ شروع منطقی است:

Flash Lite برای کار پرحجم و تکراری. دسته‌بندی تیکت و نظر مشتری، استخراج فیلد از متن، خلاصهٔ کوتاه، ترجمهٔ ساده، مسیریابی درخواست‌ها بین مدل‌ها. gemini-2.5-flash-lite و gemini-3.1-flash-lite (نسل تازه‌تر) هر دو در این رده‌اند؛ اینکه امروز کدام ارزان‌تر است را ستون آخر جدول می‌گوید. اگر حجم کارت بالاست، مقالهٔ مدل‌های ارزان برای پروژه‌های پرحجم کد batch با کنترل هزینه دارد و Flash را کنار DeepSeek و Qwen گذاشته.

Flash برای کار روزمره. پاسخ به کاربر، تولید و ویرایش متن فارسی، خواندن فاکتور و اسکرین‌شات، tool calling در یک ربات پشتیبانی. gemini-2.5-flash پیش‌فرض خیلی از پروژه‌ها بوده و هنوز گزینهٔ ارزان و قابل‌اتکایی است؛ نسل‌های 3.x Flash را کنارش روی نمونهٔ واقعی خودت امتحان کن و بین آن‌ها با هزینهٔ هر درخواست تصمیم بگیر. مقایسهٔ مستقیم یک Flash تازه با DeepSeek در صفحهٔ مقایسهٔ Gemini 3.8 Flash و DeepSeek V4 Flash هست.

Pro برای سخت‌ترین کارها. تحلیل سند بلند و چندمرحله‌ای، کدنویسی جدی، استدلال روی دادهٔ پیچیده. gemini-3.1-pro-preview تازه‌ترین Pro کاتالوگ است و gemini-2.5-pro نسخهٔ پایدار نسل قبل. منطقی است فقط درخواست‌هایی را به Pro بفرستی که Flash از پسشان برنیامده. اگر بین Gemini Pro و Claude مردد هستی، مقایسهٔ Gemini 3.1 Pro و Claude Sonnet 5.5 و مقالهٔ بهترین مدل برای کدنویسی را ببین.

نسخه‌های preview را آگاهانه انتخاب کن. مدل‌هایی که -preview در نامشان دارند ممکن است زودتر از نسخه‌های پایدار عوض یا جایگزین شوند. برای محصول تولیدی، نام مدل را در تنظیمات نگه دار، نه داخل کد، تا عوض کردنش یک تغییر مقدار باشد.

گرفتن کلید API جمینای در یوتاپن

کل مسیر چند دقیقه طول می‌کشد و هیچ‌جایش کارت خارجی یا VPN نمی‌خواهد:

1. ثبت‌نام با موبایل. در صفحهٔ ورود شمارهٔ موبایلت را بزن و کد پیامکی را وارد کن.
2. شارژ کیف پول به تومان. از درگاه زیبال با کارت‌های شتاب؛ اشتراک ماهانه یا بستهٔ از پیش تعیین‌شده در کار نیست و فقط بابت مصرف واقعی پول می‌دهی.
3. ساخت کلید. در داشبورد یک کلید بساز؛ با sk-up- شروع می‌شود و فقط یک بار کامل نمایش داده می‌شود، پس همان لحظه در جای امنی ذخیره‌اش کن. می‌توانی برای کلید سقف خرج ماهانه و فهرست مدل‌های مجاز بگذاری.
4. اتصال با SDK رسمی OpenAI. base_url را https://api.uttapen.ir/v1 بگذار و شناسهٔ مدل را با پیشوند google/ بنویس. لازم نیست SDK جداگانهٔ Google نصب کنی.

قدم‌به‌قدم همین مسیر در شروع سریع آمده.

اتصال به API Gemini با Python

اگر SDK نصب نیست، pip install openai بزن و کلید را در متغیر محیطی بگذار:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.uttapen.ir/v1",
    api_key=os.environ["UTTAPEN_API_KEY"],  # کلید sk-up-... از داشبورد
)

raw = client.chat.completions.with_raw_response.create(
    model="google/gemini-2.5-flash",
    messages=[
        {"role": "system", "content": "به فارسی، کوتاه و دقیق جواب بده."},
        {"role": "user", "content": "سه پیشنهاد برای عنوان صفحهٔ محصول «کفش رانینگ مردانه» بنویس."},
    ],
    max_tokens=300,
)
resp = raw.parse()
print(resp.choices[0].message.content)
print("هزینه:", raw.headers.get("X-Uttapen-Cost-Toman"), "تومان")
print("موجودی:", raw.headers.get("X-Uttapen-Balance-Toman"), "تومان")

with_raw_response فقط برای رسیدن به هدرهای پاسخ است. X-Uttapen-Cost-Toman هزینهٔ دقیق همین درخواست است که از کیف پولت کم شده و X-Uttapen-Balance-Toman موجودی بعد از آن. اگر هدرها را لازم نداری، همان client.chat.completions.create(...) معمولی کافی است.

همان درخواست با Node.js و curl

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uttapen.ir/v1",
  apiKey: process.env.UTTAPEN_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "google/gemini-3.1-flash-lite",
  messages: [{ role: "user", content: "این نظر را مثبت، منفی یا خنثی دسته‌بندی کن: «بسته‌بندی خوب بود ولی دیر رسید.»" }],
  max_tokens: 20,
});
console.log(resp.choices[0].message.content);

curl https://api.uttapen.ir/v1/chat/completions \
  -H "Authorization: Bearer $UTTAPEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-lite",
    "messages": [
      {"role": "user", "content": "نام شهر را از این آدرس بیرون بکش: خیابان امام، کوچهٔ ۱۲، شیراز"}
    ],
    "max_tokens": 20
  }'

پاسخ در قالب OpenAI است: choices[0].message.content، finish_reason و بلوک usage. برای استریم، "stream": true (در SDK: stream: true) اضافه کن؛ بقیه‌اش همان SSE آشنای OpenAI است.

ارسال PDF، تصویر و سند بلند به Gemini

context یک‌میلیون‌توکنی یعنی می‌توانی یک قرارداد چندده‌صفحه‌ای یا کل مستندات یک محصول را در یک درخواست بفرستی، بدون اینکه اول تکه‌تکه‌اش کنی. فایل PDF با بخش file و تصویر با بخش image_url در همان آرایهٔ content می‌رود:

import base64, pathlib

pdf = base64.b64encode(pathlib.Path("contract.pdf").read_bytes()).decode()

resp = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "تعهدات طرف دوم و مهلت هر کدام را به‌صورت فهرست بنویس."},
            {"type": "file", "file": {"filename": "contract.pdf", "file_data": f"data:application/pdf;base64,{pdf}"}},
        ],
    }],
    max_tokens=1500,
)
print(resp.choices[0].message.content)

دو نکته پیش از فرستادن سند بلند: بدنهٔ هر درخواست حداکثر ۲۰ مگابایت است، و هزینهٔ ورودی با طول سند بالا می‌رود؛ یک سند صدهزارتوکنی روی gemini-2.5-flash به‌تنهایی حدود ۱۰٬۰۰۰ تومان ورودی است و روی gemini-3.1-pro-preview حدود ۶۹٬۰۰۰ تومان. اگر چند سؤال پشت سر هم دربارهٔ همان سند داری، تعداد توکن‌هایی که از کش خوانده شده‌اند در usage.prompt_tokens_details.cached_tokens می‌آید و آن بخش با قیمت ستون «خواندن از کش» حساب می‌شود. جزئیات قالب تصویر و فایل در مستندات ورودی تصویر و فایل است و یک نمونهٔ کامل خواندن فاکتور فارسی در مقالهٔ پردازش تصویر فاکتور.

استدلال در Gemini

مدل‌های Gemini جدول بالا می‌توانند قبل از جواب «فکر کنند». بلوک reasoning را در بدنه بفرست؛ علاوه بر effort، برای Gemini می‌توانی با max_tokens داخل همین بلوک سقف مستقیم توکن‌های استدلال را تعیین کنی:

resp = client.chat.completions.create(
    model="google/gemini-3.1-pro-preview",
    messages=[{"role": "user", "content": "یک جدول سفارش با ده میلیون ردیف دارم. برای گزارش فروش ماهانه چه ایندکسی بسازم و چرا؟"}],
    max_tokens=6000,
    extra_body={"reasoning": {"max_tokens": 3000}},  # یا {"effort": "low"}
)
msg = resp.choices[0].message
thinking = getattr(msg, "reasoning", None) or (msg.model_extra or {}).get("reasoning")
if thinking:
    print("[استدلال]", thinking[:300], "…")
print(msg.content)

توکن‌های استدلال با قیمت خروجی شارژ می‌شوند؛ روی gemini-3.1-pro-preview هر هزار توکن استدلال حدود ۴٬۲۰۰ تومان است. max_tokens کل را از بودجهٔ استدلال بزرگ‌تر بگذار، وگرنه مدل ممکن است وسط فکر کردن قطع شود و content خالی برگردد در حالی که هزینهٔ استدلال پرداخت شده. وقتی درخواست reasoning دارد، برآورد خروجی برای رزرو قبل از ارسال سه برابر حساب می‌شود و بعد از پاسخ فقط مصرف واقعی کم می‌شود. همهٔ گزینه‌ها در مستندات مدل‌های استدلالی است.

ساخت تصویر با Gemini (Nano Banana)

مدل‌های تصویر Google هم در کاتالوگ‌اند: Nano Banana 2 (google/gemini-3.1-flash-image)، Nano Banana Pro (google/gemini-3-pro-image) و جدیدترینشان Nano Banana 2.1 (google/gemini-nano-banana-2.1). (راهنمای جدای این خانواده: API نانو بنانا پرو در ایران.) این‌ها از همان مسیر chat/completions و با فیلد modalities کار می‌کنند و تصویر را به‌صورت base64 در message.images برمی‌گردانند:

import base64

resp = client.chat.completions.create(
    model="google/gemini-3.1-flash-image",
    messages=[{"role": "user", "content": "یک تصویر مینیمال از فنجان قهوه روی میز چوبی، نور طبیعی"}],
    extra_body={"modalities": ["image", "text"]},
)
for img in resp.choices[0].message.images or []:
    data = img["image_url"]["url"].split(",", 1)[1]
    open("out.png", "wb").write(base64.b64decode(data))

تصویر تولیدشده با نرخ جداگانهٔ «تصویر خروجی» همان مدل شارژ می‌شود که از قیمت توکن خروجی متن خیلی بالاتر است؛ قیمت هر کدام روی صفحهٔ خود مدل است و بقیهٔ مدل‌های تصویر کاتالوگ را در مدل‌های تصویر می‌بینی و مقایسه‌شان را با نمونه‌کد مسیر images/generations در راهنمای API ساخت عکس با هوش مصنوعی نوشته‌ایم. برای انتخاب خودکار مدل تصویر و گزینه‌هایی مثل نسبت ابعاد، مستندات ساخت تصویر را بخوان. اگر صدا لازم داری، google/gemini-3.8-flash-tts از مسیر /v1/audio/speech متن را به گفتار تبدیل می‌کند (مستندات تبدیل متن به گفتار)؛ نکته‌های خواندن متن فارسی را در راهنمای API تبدیل متن به صدای فارسی آورده‌ایم. برای جستجوی معنایی و RAG هم مدل embedding google/gemini-embedding-2 هست که از مسیر /v1/embeddings صدا زده می‌شود (راهنمای API embedding)؛ پیاده‌سازی کامل RAG را در مقالهٔ RAG فارسی ببین (آنجا فقط نام مدل را عوض کن).

API رایگان جمینای: واقعیت ماجرا

«api جمینای رایگان» یکی از پرجستجوترین سؤال‌هاست، پس صریح جواب بدهیم: در کاتالوگ ما هیچ مدل Gemini نسخهٔ رایگان ندارد و هر درخواست Gemini از کیف پول کم می‌شود. اینکه Google خودش برای حساب‌های خارج از ایران چه سهمیه‌ای می‌دهد به شرایط Google بستگی دارد و چیزی نیست که بشود محصول ایرانی را رویش بنا کرد.

دو راه کم‌هزینه هست. اول، اگر فقط می‌خواهی کار با API را یاد بگیری، مدل‌های رایگان کاتالوگ بدون شارژ کار می‌کنند؛ دو نسخهٔ :free از Gemma 4، خانوادهٔ متن‌باز Google، هم بینشان هست. ظرفیت این‌ها مشترک و محدود است، پس برای محصول واقعی رویشان حساب نکن. دوم، Flash Lite آن‌قدر ارزان است که هزینهٔ تست عملاً ناچیز است: یک درخواست کوتاه صدتوکنی با gemini-2.5-flash-lite حدود ۲۰ تومان است. یک راه دیگر هم هست: اگر به یک مدل متن‌باز ارزان با context کوچک‌تر راضی هستی، نسخهٔ پولی Gemma 4 31B هم گزینهٔ خوبی است.

کنترل هزینهٔ Gemini

• همیشه max_tokens بفرست. اگر نفرستی، رزرو قبل از ارسال با سقف پیش‌فرض ۳۲٬۷۶۸ توکن خروجی حساب می‌شود؛ روی gemini-3.1-pro-preview فقط بخش خروجی این رزرو حدود ۱۴۰٬۰۰۰ تومان است. اگر موجودی به آن نرسد، درخواست رد نمی‌شود و سقف خروجی تا جایی که موجودی می‌کشد پایین می‌آید (عددش در هدر X-Uttapen-Max-Tokens می‌آید)، ولی ممکن است پاسخ با finish_reason: "length" کوتاه تمام شود.
• مدل را پله‌ای بالا ببر. اول Flash Lite، اگر کیفیت نرسید Flash، و فقط در آخر Pro.
• سند بلند را بی‌دلیل نفرست. context یک‌میلیونی یعنی «می‌شود»، نه «باید». اگر فقط دو صفحه از سند به سؤال مربوط است، همان دو صفحه را بفرست.
• برای هر پروژه کلید جدا بساز. هر کلید می‌تواند سقف ماهانهٔ تومانی و فهرست مدل‌های مجاز داشته باشد؛ مثلاً کلید ربات دسته‌بندی را فقط به google/gemini-2.5-flash-lite محدود کن.
• خطا هزینه ندارد. درخواستی که با خطا تمام شود هیچ مبلغی کم نمی‌کند، و اگر استریم را وسط کار قطع کنی فقط بابت توکن‌های تولیدشده پول می‌دهی. جزئیات در صفحهٔ قیمت‌ها آمده.

سؤال‌های پرتکرار

کدی که با SDK رسمی Google نوشته‌ام اینجا کار می‌کند؟

مستقیم نه. یوتاپن قالب OpenAI را می‌فهمد، پس باید تماس‌ها را به SDK رسمی OpenAI (یا هر کتابخانهٔ سازگار با آن مثل LangChain و Vercel AI SDK) منتقل کنی. تغییرها معمولاً کوچک‌اند: generate_content می‌شود chat.completions.create، پیام‌ها در آرایهٔ messages با نقش‌های system و user و assistant می‌آیند، و نام مدل با پیشوند می‌شود (google/gemini-2.5-flash).

قیمت API جمینای ثابت است؟

نه. قیمت تومانی با نرخ دلار و قیمت سازنده عوض می‌شود (جدول بالا هم قیمت روز را نشان می‌دهد)، ولی هر درخواست با قیمتی تسویه می‌شود که لحظهٔ ارسالش معتبر بوده. قیمت زنده را در صفحهٔ هر مدل یا با GET /v1/models (بدون نیاز به کلید) بگیر.

Gemini فارسی را خوب می‌فهمد؟

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

برای شروع کار با API Gemini چقدر شارژ لازم است؟

کمترین شارژ کیف پول امروز برای حدود ۵۴۰ درخواست هزارکلمه‌ای با gemini-2.5-flash-lite یا ۱۰۴ درخواست با gemini-2.5-flash کافی است؛ برای تست با درخواست‌های کوتاه‌تر، خیلی بیشتر. اعتبار کیف پول تا وقتی مصرفش نکنی سر جایش می‌ماند.

جمع‌بندی

برای بیشتر پروژه‌ها با google/gemini-2.5-flash یا یکی از Flashهای نسل 3.x شروع کن، کارهای تکراری و پرحجم را به google/gemini-2.5-flash-lite یا google/gemini-3.1-flash-lite بسپار و فقط سخت‌ترین درخواست‌ها را به google/gemini-3.1-pro-preview بفرست. اگر سند بلند یا PDF داری، همین context یک‌میلیونی بزرگ‌ترین دلیل انتخاب Gemini است. برای شروع، یک حساب بساز، کیف پول را شارژ کن و نمونهٔ Python بالا را اجرا کن؛ هدر X-Uttapen-Cost-Toman همان لحظه می‌گوید درخواستت چند تومان تمام شد.