Gemini API: راهنمای نصب و اولین درخواست
Gemini API همان زیرساختی است که گوگل برای توسعهدهندگان بیرون از Google AI Studio طراحی کرده: یک رابط REST و SDK که با یک Gemini API key میتوانید مدلهای…
تیمِ فنیِ 1xAi گیت‌وی را می‌سازد و می‌گرداند — همان‌هایی که هر روز با APIهای OpenAI، Anthropic، Google و DeepSeek از داخلِ ایران کار می‌کنند. آنچه اینجا می‌خوانی از همان کارِ روزمره درآمده، نه از بازنویسیِ مستنداتِ انگلیسی. پروفایلِ نویسنده
در این مقالهCONTENTS
۸
- Gemini API اصلاً چیست؟
- مدلهای Gemini دستیاب و انتخاب مناسب
- سوالات متداول
- Gemini API چیست و چه فرقی با Google AI Studio دارد؟
- چطور Gemini API Key بگیریم؟
- کدام مدل Gemini برای شروع مناسبتر است؟
- هزینه استفاده از Gemini API چقدر است؟
- آیا برای استفاده از Gemini API از ایران نیاز به VPN یا کارت بانکی خارجی داریم؟
Gemini API همان زیرساختی است که گوگل برای توسعهدهندگان بیرون از Google AI Studio طراحی کرده: یک رابط REST و SDK که با یک Gemini API key میتوانید مدلهای Gemini را مستقیم در چتبات، موتور جست‌وجوی هوشمند یا سیستم تحلیل نظرات خودتان ادغام کنید. سؤال اصلی توسعه‌دهنده‌ی ایرانی معمولاً این نیست که Gemini API چیست، بلکه این است که چطور بدون سروکله‌زدن با کارت بین‌المللی یا VPN به آن دسترسی پایدار بگیرد و هزینه‌اش را به تومان حساب کند؛ برای بسیاری از کاربران داخل ایران، مسیر رسمی Google در این دو مورد محدودیت‌هایی ایجاد میکند. ما در 1xAi همین مسیر را برای مدلهای Gemini از طریق یک gateway سازگار با OpenAI با base URL https://1xai.ir/v1 فراهم کرده‌ایم؛ در ادامه، هم مفهوم و معماری API را با مثال کد باز میکنیم و هم مسیر عملی نصب SDK و اولین درخواست را قدم‌به‌قدم نشان می‌دهیم.
Gemini API اصلاً چیست؟
Gemini API یک رابط برنامهنویسی REST و SDK از گوگل است که مدلهای Gemini را مستقیماً در کد شما در دسترس میگذارد، بدون نیاز به باز کردن رابط وب. در معماری آن، کلاینت (کد پایتون یا جاوااسکریپت) درخواست را همراه کلید API به سرورهای Google ارسال میکند، مدل پردازش را انجام میدهد و پاسخ بهصورت JSON برمیگردد. کاربردهای رایج شامل تولید متن، تحلیل تصویر، ساخت چتباتهای هوشمند و خودکارسازی تولید محتوا است.
تفاوت اصلی با Google AI Studio این است که Studio یک محیط وب برای آزمایش سریع پرامپتهاست، در حالیکه API برای ادغام در برنامههای واقعی و ترافیک تولیدی طراحی شده. نکته کلیدی این است که Gemini API یک رابط REST/SDK برای ادغام در پروژه واقعی است، نه یک ابزار وب مثل Gemini app یا سایت Gemini AI. برای دسترسی به همین مدلهای Gemini از طریق یک API سازگار با OpenAI و با پرداخت تومانی، ما در 1xAi یک gateway اداره میکنیم که با base URL یکسان https://1xai.ir/v1 کار میکند؛ فهرست مدلهای در دسترس در مدلهای 1xAi بهروز میماند.
مدلهای Gemini دستیاب و انتخاب مناسب
انتخاب مدل مناسب Gemini به تعادل بین سرعت، کیفیت خروجی و حجم متن ورودی بستگی دارد؛ برای مصارف پرحجم و حساس به هزینه، مدلهای سبک‌تر خانواده flash-lite معمولاً گزینه اول‌اند. در حال حاضر مدلهای gemini-3.5-flash، gemini-2.5-flash، gemini-2.5-pro و gemini-2.5-flash-lite در دسترس‌اند و فهرست کامل آن‌ها را میتوانید در مدلهای 1xAi ببینید.
| مدل | سرعت | کاربرد بهینه |
|---|---|---|
| gemini-2.5-flash-lite | بسیار بالا | پاسخ سریع، حجم بالا |
| gemini-2.5-flash | بالا | چتبات و خودکارسازی روزمره |
| gemini-3.5-flash | بالا | وظایف عمومی با کیفیت بهتر |
| gemini-2.5-pro | متوسط | استدلال پیچیده، تحلیل عمیق |
برای اپلیکیشن‌های حساس به هزینه و تأخیر، gemini-2.5-flash-lite ارزانترین گزینه است — ورودی <span data-live="gemini-2.5-flash-lite:in_1m">۳۵٬۱۳۹</span> تومان و خروجی <span data-live="gemini-2.5-flash-lite:out_1m">۱۴۰٬۵۵۶</span> تومان بهازای هر ۱M توکن، طبق صفحه قیمتگذاری 1xAi. برای وظایفی که دقت اهمیت بیشتری دارد، gemini-2.5-pro با ورودی <span data-live="gemini-2.5-pro:in_1m">۳۸۸٬۵۵۶</span> تومان و خروجی <span data-live="gemini-2.5-pro:out_1m">۳٬۱۰۸٬۴۵۰</span> تومان بهازای هر ۱M توکن مناسبتر است.
پژوهش و نگارش: the CodeNest content engine
سوالات متداول
Gemini API چیست و چه فرقی با Google AI Studio دارد؟
Gemini API یک رابط REST و SDK است که به توسعهدهندگان اجازه میدهد مدلهای Gemini را در برنامههای واقعی (چتبات، تحلیل تصویر، خودکارسازی محتوا) ادغام کنند. Google AI Studio ابزار وب برای آزمایش سریع است، در حالی که API برای استفاده تولیدی و مقیاسپذیر طراحی شده است.
چطور Gemini API Key بگیریم؟
معمولاً باید از طریق Google AI Studio یک کلید API صادر کنید، اما برای بسیاری از کاربران داخل ایران این مسیر می‌تواند با محدودیت‌هایی مثل نیاز به کارت بانکی بین‌المللی یا VPN همراه باشد. از طریق 1xAi میتوانید بدون VPN و کارت بین‌المللی، با پرداخت تومانی و از طریق یک gateway سازگار با OpenAI (base URL https://1xai.ir/v1) به مدلهای Gemini موجود در مدلهای 1xAi دسترسی بگیرید.
کدام مدل Gemini برای شروع مناسبتر است؟
برای پروژههای حساس به هزینه و سرعت، gemini-2.5-flash-lite در حال حاضر ارزانترین گزینه است (ورودی ۳۵٬۱۳۹ تومان و خروجی ۱۴۰٬۵۵۶ تومان بهازای هر میلیون توکن). برای تحلیل پیچیدهتر، gemini-2.5-pro با کیفیت بالاتر و هزینه بیشتر مناسبتر است؛ قیمت دقیق هر مدل را میتوانید در صفحه قیمتگذاری ببینید.
هزینه استفاده از Gemini API چقدر است؟
هزینه بر اساس مدل انتخابی و تعداد توکن ورودی/خروجی متغیر است؛ مثلاً gemini-2.5-flash ورودی ۱۰۵٬۴۱۷ تومان و خروجی ۸۷۸٬۴۷۵ تومان بهازای هر میلیون توکن از طریق 1xAi دارد. توکن‌های کش‌شده هزینه بسیار کمتری دارند و برای درخواست‌های تکراری صرفه‌جویی قابل‌توجهی ایجاد می‌کنند؛ قیمت زنده همه مدل‌ها در صفحه قیمتگذاری بهروز میماند.
آیا برای استفاده از Gemini API از ایران نیاز به VPN یا کارت بانکی خارجی داریم؟
از طریق دسترسی مستقیم Google، در بسیاری از موارد به VPN و کارت اعتباری بین‌المللی نیاز خواهید داشت. اما با استفاده از 1xAi، یک gateway سازگار با OpenAI که مدلهای Gemini را از طریق base URL https://1xai.ir/v1 ارائه میدهد، میتوانید بدون این پیش‌نیازها و با پرداخت تومانی مستقیماً به این مدل‌ها متصل شوید.
1xAi
تیمِ 1xAi پروکسیِ تخصصیِ مدلهای OpenAI، Claude، Gemini و DeepSeek — و همچنین Grok، Kimi، GLM، Qwen، MiniMax و Hunyuan — برای کاربرانِ ایرانی را اداره میکند — از زیرساختِ شبکه تا صورت‌حسابِ تومانی. هرچه اینجا می‌نویسیم بر اساسِ تجربه‌ٔ روزانه با APIهای OpenAI، Anthropic و Google و نیازهای واقعیِ توسعه‌دهندگانِ داخلِ ایران است.