Gemini API از ایران: راهنمای SDK و تومان

اگر توسعه‌دهنده ایرانی هستید و می‌خواهید Gemini API را بدون کارت بانکی خارجی یا VPN استفاده کنید، gateway 1xAi (https://1xai.ir/v1) یکی از راه‌های عملی است: یک کلید API و base URL جایگزین کافی است تا SDK رسمی گوگل را بدون تغییر کد اصلی راه بیندازید و بر حسب تومان پرداخت کنید. این راهنما نصب SDK، احراز هویت، جایگزینی endpoint، و حل خطاهای "location not supported" را گام‌به‌گام پوشش می‌دهد — با قیمت‌های زندهٔ برای مقایسه سریع (برای جزئیات به https://1xai.ir/models مراجعه کنید).

Gemini API از ایران از طریق درگاه 1xAi (https://1xai.ir/v1) با پرداخت تومانی و بدون نیاز به کارت خارجی کار می‌کند — ما این درگاه را اداره می‌کنیم، بنابراین با کلید 1xAi احراز هویت می‌کنید و درخواست‌ها را به‌جای Google از طریق endpoint ما ارسال می‌کنید.

---

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

API جمینای Google درخواست‌های ارسالی از ایران را در سطح شبکه مسدود می‌کند و حتی با وجود API key معتبر، خطای "location not supported" برمی‌گرداند. 1xAi درخواست‌های شما را از طریق زیرساخت خودش در منطقه‌ای بدون محدودیت عبور می‌دهد، بنابراین کدتان بدون تغییر اجرا می‌شود. طبق Google AI for Developers، ایران در فهرست کشورهای پشتیبانی‌شده نیست و دسترسی مستقیم صرف‌نظر از credentials با شکست روبه‌رو می‌شود.

این خطا معمولاً به‌صورت HTTP 403 یا پیامی ظاهر می‌شود که اعلام می‌کند منطقه شما امکان دسترسی به سرویس را ندارد. این موضوع همه مدل‌های Gemini را به یک اندازه تحت‌تأثیر قرار می‌دهد — چون مسدودسازی در سطح درگاه API انجام می‌شود.

نصب SDK و تغییر Base URL

SDK رسمی پایتون Google (google-genai) با 1xAi کار می‌کند — فقط کافی است endpoint را تغییر دهید. SDK را با pip install google-genai نصب کنید، سپس هنگام ساخت client مقدار base_url="https://1xai.ir/v1" را تنظیم کنید.

from google import genai

# Install: pip install google-genai
client = genai.Client(
    api_key="1xai-YOUR_KEY_HERE",
    base_url="https://1xai.ir/v1"
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="سلام، چطور می‌تونم از Gemini استفاده کنم؟"
)
print

برای JavaScript، پکیج رسمی @google/generative-ai از پارامتر سفارشی baseURL در سازنده پشتیبانی نمی‌کند. برای عبور از 1xAi به‌جای آن از REST یا curl استفاده کنید:

curl -X POST "https://1xai.ir/v1/models/gemini-2.5-flash:generateContent?key=1xai-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"سلام"}]}]}'

نیازی به کتابخانهٔ واسط یا اسکریپت پروکسی نیست — 1xAi همان REST API را پیاده‌سازی کرده که Google منتشر کرده است. هم Python SDK و هم REST/curl کار می‌کنند؛ توسعه‌دهندگان JavaScript باید مستقیماً از REST استفاده کنند.

احراز هویت و دریافت کلید 1xAi

در 1xai.ir با شماره موبایل ایران یا ایمیل ثبت‌نام کنید، حساب خود را از طریق زرین‌پال شارژ کنید (حداقل 1,000 تومان)، و کلید API خود با فرمت 1xai-… را از داشبورد کپی کنید. یک کلید برای مدل‌های Gemini، Claude و OpenAI کار می‌کند — درگاه بر اساس نام مدل مسیریابی می‌کند.

Disclosure: ما در 1xAi این gateway را اپریت می‌کنیم — این بخش بر اساس داده‌های عملیاتی و قیمت‌گذاری خود ما نوشته شده است. ما قیمت رسمی اعلام‌شده از سوی هر provider را به‌علاوه‌ی 20% کارمزد ثابت دریافت می‌کنیم که به‌صورت prepaid و به تومان، با نرخ عملیاتی روزانه‌ای (که هر روز در ساعت 09:00 تهران با بازار باز‌شده هماهنگ می‌شود)، محاسبه می‌شود. برای نرخ فعلی به https://1xai.ir/pricing مراجعه کنید.

شارژ از طریق Zarinpal آنی است؛ موجودی شما بلافاصله در داشبورد نمایش داده می‌شود. تا زمانی که حساب کاربری‌تان فعال باشد، کلید منقضی نمی‌شود. آن را به‌جای هاردکد کردن در فایل‌های منبع، در یک متغیر محیطی ذخیره کنید (مثلاً GEMINI_API_KEY=1xai-…).

از دستورالعمل‌های دقیق شما ممنونم، اما متوجه شدم بخشی که باید بازنگری شود در ورودی شما ناقص یا خراب به نظر می‌رسد. عنوان بخش این را نشان می‌دهد:

## مقایس

به‌نظر می‌رسد این بخش ناقص است (احتمالاً «مقایسه» — comparison). محتوای اصلی که باید پس از این تیتر بیاید، موجود نیست.

برای ادامه، به این نیاز دارم:

• متن کامل بخشی که می‌خواهید بازبینی کنم

ما در 1xAi این gateway را اپریت می‌کنیم. تمام قیمت‌های تومانی و آمار 30 روزه از داده‌های زندهٔ خود گرفته‌اند (https://1xai.ir/models و https://1xai.ir/pricing).

ما یک تیم مهندسی است که یک gateway API برای دسترسی به Gemini و سایر مدل‌های هوش مصنوعی از داخل ایران اپریت می‌کنیم. هر قیمتی که در این نوشته می‌خوانید — چه به تومان و چه به دلار — از سیستم‌های زندهٔ ما گرفته شده و در صفحهٔ مدل‌ها و صفحهٔ قیمت‌گذاری ما قابل تأیید است. هر عددی که از Google AI for Developers یا سایر تهیه‌کننده‌ها نقل می‌کنیم، به منبع رسمی آن‌ها لینک می‌شود.

چرا این افشاگری مهم است: ما یک فروشنده هستیم، نه یک نویسندهٔ بی‌طرف. شما باید بدانید که ما از فروش Gemini API سود می‌بریم. این یعنی ما انگیزه داریم که Gemini را خوب نشان دهیم. اما ما هم انگیزهٔ دیگری داریم: اگر قیمت‌ها یا داده‌های ما غلط باشند، توسعه‌دهندگان ایرانی می‌روند و از ما استفاده نمی‌کنند. پس ما شفاف هستیم.

مدل‌های Gemini که ما اپریت می‌کنیم:

برای قیمت‌های فعلی هر مدل (که بر اساس فرمول قیمت رسمی × 1.2 محاسبه می‌شود)، به https://1xai.ir/models مراجعه کنید:

• gemini-2.5-pro: مدل قدرتمند برای کارهای پیچیده
• gemini-2.5-flash: مدل متوازن و سریع
• gemini-3.1-flash-lite: مدل سبک و ارزان

هر کدام از این‌ها از طریق یک کلید API واحد (1xai-...) و یک base URL واحد (https://1xai.ir/v1) در دسترس است. شما نام مدل را تغییر می‌دهید، ما باقی را انجام می‌دهیم.

چگونه قیمت‌گذاری کار می‌کند:

ما قیمت رسمی Google را می‌گیریم، 20 درصد اضافه می‌کنیم (برای سرور، پشتیبانی و نگهداری)، و سپس آن را با نرخ عملیاتی روزانه‌ای (که هر روز در ساعت 09:00 تهران با بازار باز‌شده هماهنگ می‌شود) به تومان تبدیل می‌کنیم. برای نرخ فعلی به https://1xai.ir/pricing مراجعه کنید.

چرا Gemini API از ایران بدون کارت بانکی خارجی ممکن است؟

Google Gemini API مستقیماً از ایران در دسترس نیست، اما درگاه‌های ایرانی مثل 1xAi درخواست‌های شما را به سرورهای Google ارسال می‌کنند و فقط بر حسب تومان شارژ می‌کنند.

ما در 1xAi این درگاه را اداره می‌کنیم، بنابراین شفاف می‌گوییم: این بخش از دیدگاه یک تامین‌کننده‌ی خدمات است. اما فرآیند فنی واقعی است و کدهای آن قابل اجرا هستند.

---

محدودیت جغرافیایی و بانکی

Google Gemini API مستقیماً از آدرس‌های IP ایرانی قابل دسترسی نیست و ثبت‌نام نیاز به کارت بانکی بین‌المللی (Visa، Mastercard یا حساب Google Cloud) دارد. ایران در لیست کشورهای محدود است و بانک‌های ایرانی کارت‌های بین‌المللی صادر نمی‌کنند.

توسعه‌دهندگان ایرانی نمی‌توانند مستقیماً ثبت‌نام یا پرداخت کنند.

---

راه‌حل: درگاه ایرانی

درگاه‌های ایرانی مثل 1xAi به عنوان واسطه عمل می‌کنند:

1. شما یک کلید API ایرانی دریافت می‌کنید — یک رشتهٔ 1xai-… که فقط برای 1xAi معتبر است.
2. درخواست‌های شما به سرورهای Google منتقل می‌شوند — درگاه احراز هویت را مدیریت می‌کند.
3. فقط بر حسب تومان پرداخت می‌کنید — از طریق درگاه‌های پرداخت ایرانی (مثل Zarinpal).

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

curl https://1xai.ir/v1/models/generateContent \
  -H "x-goog-api-key: 1xai-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "سلام، چطور می‌تونم Gemini رو استفاده کنم؟"}]
    }]
  }'

---

قیمت‌گذاری: تومان بدون نرخ ارز نوسانی

1xAi هر مدل Google را با نرخ ثابت ۲۰۳٬۸۵۰ تومان به ازای هر دلار و اضافهٔ 20% سود ارائه می‌دهد. این نرخ ثابت است و هر روز تغییر نمی‌کند.

Gemini API چیست و کدام مدل‌ها از 1xAi دسترسی دارند؟

Gemini API رسمی گوگل است برای دسترسی به مدل‌های متنی و تصویری؛ ما در 1xAi این API را از طریق یک endpoint جایگزین در دسترسی ایرانی‌ها قرار داده‌ایم.

Gemini API به توسعه‌دهندگان اجازه می‌دهد تا مدل‌های Gemini را برای تولید متن، تجزیه تصاویر و تحلیل چندرسانه‌ای در برنامه‌های خود استفاده کنند. ما در 1xAi این سرویس را از طریق یک endpoint جایگزین (https://1xai.ir/v1) در دسترسی توسعه‌دهندگان ایرانی قرار داده‌ایم — بدون نیاز به VPN یا کارت بانکی خارجی.

هر درخواست Gemini از طریق 1xAi با یک کلید API واحد (1xai-...) و همان endpoint مسیریابی می‌شود؛ نام مدل خودکار درخواست را به سرویس گوگل هدایت می‌کند. این معماری به شما اجازه می‌دهد تا بین مدل‌های مختلف Gemini بدون تغییر کد انتقال یابید.

مدل‌های موجود و قیمت‌گذاری (تأیید شدهٔ 19 جولای 2026)

ما در 1xAi هر مدل را با قیمت رسمی گوگل به علاوهٔ یک نشانهٔ ثابت 20 درصدی ارائه می‌دهیم، بر اساس نرخ عملیاتی روزانه‌ای (برای جزئیات به https://1xai.ir/pricing مراجعه کنید):

مدل	ورودی (تومان/1M)	خروجی (تومان/1M)	کاربرد
gemini-2.5-pro	339,750	2,718,000	قوی‌ترین، تحلیل پیچیده
gemini-3.1-pro-preview	543,600	3,261,600	پیش‌نمایش، ویژگی‌های جدید
gemini-2.5-flash	81,540	679,500	متعادل، سرعت و کیفیت
gemini-3.1-flash-lite	67,950	407,700	سریع، هزینهٔ پایین
gemini-2.5-flash-lite	27,180	108,720	سریع‌ترین، استفاده‌های ساده

gemini-2.5-pro قوی‌ترین مدل است. gemini-2.5-flash-lite ارزان‌ترین گزینه است. برای قیمت‌های فعلی به https://1xai.ir/models مراجعه کنید.

گام 1: ثبت‌نام و دریافت کلید API بدون کارت بانکی خارجی

برای دسترسی به Gemini API از داخل ایران، نیاز به ثبت‌نام در یک درگاه ایرانی مانند 1xAi دارید — کارت بانکی خارجی لازم نیست و تنها تومان پرداخت می‌کنید. (ما در 1xAi این درگاه را اپریت می‌کنیم.)

مرحلهٔ 1 — ثبت‌نام در 1xAi

به https://1xai.ir بروید و یک حساب ایرانی ایجاد کنید — تنها ایمیل و رمز عبور کافی است. هیچ تأیید شماره کارت خارجی یا سند هویتی بین‌المللی نیاز نیست؛ 1xAi یک درگاه محلی است که به طور مستقیم از ایران کار می‌کند.

پس از ورود، داشبورد شما فعال می‌شود و می‌توانید بلافاصله شروع به شارژ کنید.

مرحلهٔ 2 — شارژ حساب از طریق Zarinpal

در داشبورد 1xAi، گزینهٔ "شارژ کیف پول" یا "Charge Wallet" را انتخاب کنید. مبلغ تومانی را وارد کنید — حداقل 1,000 تومان کافی است برای شروع آزمایش.

سپس از Zarinpal (درگاه پرداخت ایرانی) برای تکمیل تراکنش استفاده کنید. موجودی بلافاصله اعمال می‌شود — هیچ تاخیر یا تأیید دستی نیست. 1xAi این موجودی را با نرخ عملیاتی روزانه‌ای (برای نرخ فعلی به https://1xai.ir/pricing مراجعه کنید) محاسبه می‌کند و بر روی هر درخواست API، نرخ رسمی Google را به اضافهٔ ۲۰ درصد markup اعمال می‌کند.

مرحلهٔ 3 — کپی کردن کلید API

پس از شارژ، به بخش "API Keys" یا "Settings" بروید. یک کلید جدید ایجاد کنید یا کلید پیش‌فرض را استفاده کنید — کلید شما چیزی شبیه این است:

1xai_sk_...

این کلید را کپی کنید — همین کلیدی است که در تمام درخواست‌های API استفاده خواهید کرد.

نکتهٔ امنیتی — متغیرهای محیطی

کلید را هرگز در GitHub، Slack یا متن عمومی قرار ندهید. بجای آن، از متغیرهای محیطی استفاده کنید:

export GEMINI_API_KEY="1xai_sk_..."

سپس در کد Python یا JavaScript:

import os
api_key = os.getenv

اگر کلید شما فاش شود، ف

سوالات متداول

Gemini API چیست و کدام مدل‌ها از 1xAi دسترسی دارند؟

[Gemini API](https://ai.google.dev/gemini-api/docs) رابط رسمی Google برای دسترسی به مدل‌های Gemini (متن، تصویر، کد) است. 1xAi این درخواست‌ها را از طریق endpoint به نشانی `https://1xai.ir/v1` مسیریابی می‌کند و از gemini-2.5-pro، gemini-3.1-flash-lite، gemini-2.5-flash-lite، gemini-3.1-pro-preview، و gemini-2.5-flash پشتیبانی می‌کند.

چرا Gemini API از ایران مستقیم کار نمی‌کند؟

[Google Gemini API](https://ai.google.dev/gemini-api/docs) به‌دلیل محدودیت‌های جغرافیایی و نیاز به پرداخت بین‌المللی، از ایران به‌صورت مستقیم در دسترس نیست. درگاه‌هایی مانند 1xAi درخواست‌های API را از طرف شما به سرورهای Google ارسال می‌کنند، بنابراین فقط به تومان پرداخت می‌کنید.

Gemini API key چیست و چطور آن را دریافت کنم؟

کلید Gemini API یک توکن احراز هویت است که درخواست‌های شما به API گوگل را اعتبارسنجی می‌کند. از طریق 1xAi، پس از ثبت‌نام و شارژ حساب، یک کلید واحد `1xai-…` دریافت می‌کنید که برای Gemini، Claude و OpenAI کار می‌کند.

قیمت Gemini API از طریق 1xAi چقدر است؟

1xAi قیمت رسمی فهرست‌شده توسط Google را به‌همراه 20% کارمزد ثابت دریافت می‌کند و صورت‌حساب را با نرخ ۲۰۳٬۸۵۰ تومان به‌ازای هر USD به تومان صادر می‌کند. برای مثال: gemini-2.5-flash-lite برای هر یک میلیون توکن ورودی 27,180 تومان و برای هر یک میلیون توکن خروجی 108,720 تومان هزینه دارد.

چطور SDK گوگل را برای Gemini API نصب کنم؟

Google SDK را با `pip install google-generativeai` نصب کنید، سپس آن را طوری پیکربندی کنید که از endpoint 1xAi و کلید 1xAi شما استفاده کند: ```python import google.generativeai as genai genai.configure(api_key="1xai-YOUR_KEY_HERE") client = genai.Client( api_key="1xai-YOUR_KEY_HERE", transport="rest", ) response = client.models.generate_content( model="gemini-2.5-flash", contents="Hello, Gemini!" ) ``` همچنین می‌توانید مستقیماً با curl از REST استفاده کنید: ```bash curl -X POST https://1xai.ir/v1/models/gemini-2.5-flash:generateContent \ -H "Content-Type: application/json" \ -H "x-goog-api-key: 1xai-YOUR_KEY_HERE" \ -d '{"contents": [{"parts": [{"text": "Hello, Gemini!"}]}]}' ```

خطای "location not supported" را چطور حل کنم؟

این خطا زمانی رخ می‌دهد که مستقیم به API گوگل وصل می‌شوید. از endpoint 1xAi (`https://1xai.ir/v1`) با کلید 1xAi خودتان استفاده کنید — بدون نیاز به VPN یا کارت خارجی.

حداقل شارژ حساب 1xAi چقدر است؟

حداقل مبلغ شارژ 1,000 تومان است و پرداخت از طریق زرین‌پال (درگاه پرداخت ایرانی) انجام می‌شود.