Gemini API: راهنمای نصب و اولین درخواست

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 ارزان‌ترین گزینه است — ورودی ۲۵٬۷۱۶ تومان و خروجی ۱۰۲٬۸۶۴ تومان به‌ازای هر ۱M توکن، طبق صفحه قیمت‌گذاری 1xAi. برای وظایفی که دقت اهمیت بیشتری دارد، gemini-2.5-pro با ورودی ۳۲۱٬۴۵۰ تومان و خروجی ۲٬۵۷۱٬۶۰۰ تومان به‌ازای هر ۱M توکن مناسب‌تر است.

نکات اضافی برای نویسنده

ترتیب منطقی محتوا باید از تعریف gemini api شروع شود، سپس انتخاب مدل، دریافت کلید، نصب و کد، استفاده از 1xAi و در پایان پرسش‌های متداول را پوشش دهد؛ هر H2/H3 با یک جمله‌ی مستقیم و قابل استناد به سؤال خودش شروع می‌شود، نه با مقدمه‌چینی.

هر کد نمونه باید کامل و قابل اجرا باشد، نه قطعه‌ای بریده‌شده؛ برای مثال یک درخواست ساده با base_url روی https://1xai.ir/v1 باید همراه توضیح خط‌به‌خط بیاید، از وارد کردن کتابخانه تا چاپ خروجی. دستورهای curl هم باید هدرها و بدنه‌ی کامل JSON را نشان دهند، نه نسخه‌ی خلاصه‌سازی متن با هوش مصنوعی.

فهرست مدل‌های Gemini که در متن و جدول ذکر می‌شوند باید دقیقاً با موارد موجود در dossier یکی باشند: gemini-2.5-pro، gemini-2.5-flash، gemini-2.5-flash-lite، gemini-3.5-flash و gemini-3.1-flash-lite. مدل‌هایی که در dossier نیستند (مثل gemini-3.1-pro-preview یا هر نام دیگری) نباید در جدول یا FAQ ذکر شوند، و در بحث «ارزان‌ترین گزینه» باید gemini-2.5-flash-lite معرفی شود چون کمترین قیمت ورودی را در dossier دارد.

هر جا که به دسترسی مستقیم گوگل برای کاربران ایرانی اشاره می‌شود، باید بیان مشروط و غیرقطعی باشد (مثل «برای بسیاری از کاربران ممکن است نیاز به VPN یا روش پرداخت بین‌المللی پیش بیاید») نه یک قانون قطعی و همگانی. همچنین هرجا از «اندپوینت‌های Gemini» یا مشابه آن یاد می‌شود باید روشن شود که 1xAi یک gateway با API سازگار با OpenAI روی https://1xai.ir/v1 است که دسترسی به مدل‌های Gemini فهرست‌شده در صفحه مدل‌های 1xAi را فراهم می‌کند؛ این عبارت نباید القا کند که همان اندپوینت رسمی گوگل است.

لینک‌دهی داخلی باید طبیعی و پخش‌شده باشد: مستندات رسمی گوگل در مستندات Gemini API، دریافت کلید در aistudio.google.com/apikey، فهرست مدل‌های دستیاب در صفحه مدل‌های 1xAi، قیمت‌گذاری تومانی در صفحه قیمت‌گذاری و برای یکپارچه‌سازی سفارشی مثل چت‌بات یا اتوماسیون، فرم درخواست سفارشی.

قیمت هر مدل باید فقط یک‌بار و با توکن‌های {{live:…}} نمایش داده شود، نه با عدد دستی و نه با نرخ تبدیل دلار مشخص؛ مثلاً برای gemini-2.5-flash از `{{live:gemini-2.

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

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](https://1xai.ir/models) دسترسی بگیرید.

کدام مدل Gemini برای شروع مناسب‌تر است؟

برای پروژه‌های حساس به هزینه و سرعت، gemini-2.5-flash-lite در حال حاضر ارزان‌ترین گزینه است (ورودی ۲۵٬۷۱۶ تومان و خروجی ۱۰۲٬۸۶۴ تومان به‌ازای هر میلیون توکن). برای تحلیل پیچیده‌تر، gemini-2.5-pro با کیفیت بالاتر و هزینه بیشتر مناسب‌تر است؛ قیمت دقیق هر مدل را می‌توانید در [صفحه قیمت‌گذاری](https://1xai.ir/pricing) ببینید.

هزینه استفاده از Gemini API چقدر است؟

هزینه بر اساس مدل انتخابی و تعداد توکن ورودی/خروجی متغیر است؛ مثلاً gemini-2.5-flash ورودی ۷۷٬۱۴۸ تومان و خروجی ۶۴۲٬۹۰۰ تومان به‌ازای هر میلیون توکن از طریق 1xAi دارد. توکن‌های کش‌شده هزینه بسیار کمتری دارند و برای درخواست‌های تکراری صرفه‌جویی قابل‌توجهی ایجاد می‌کنند؛ قیمت زنده همه مدل‌ها در [صفحه قیمت‌گذاری](https://1xai.ir/pricing) به‌روز می‌ماند.

آیا برای استفاده از Gemini API از ایران نیاز به VPN یا کارت بانکی خارجی داریم؟

از طریق دسترسی مستقیم Google، در بسیاری از موارد به VPN و کارت اعتباری بین‌المللی نیاز خواهید داشت. اما با استفاده از 1xAi، یک gateway سازگار با OpenAI که مدل‌های Gemini را از طریق base URL `https://1xai.ir/v1` ارائه می‌دهد، می‌توانید بدون این پیش‌نیازها و با پرداخت تومانی مستقیماً به این مدل‌ها متصل شوید.