آموزش Gemini API: از دریافت کلید تا اولین درخواست متنی و تصویری
مدل‌های Gemini گوگل در سال‌های اخیر به یکی از گزینه‌های اصلی توسعه‌دهندگان تبدیل شده‌اند؛ به‌خصوص به خاطر پنجرهٔ زمینهٔ بزرگ، توانایی کار هم‌زمان با متن و تصویر و نسخه‌های سریع و اقتصادی. اما کاربر ایرانی برای استفادهٔ مستقیم از Gemini API با محدودیت‌های دسترسی و پرداخت روبه‌رو است. در این آموزش قدم‌به‌قدم توضیح می‌دهیم Gemini API چیست، نسخه‌های مختلف آن چه تفاوتی دارند و چطور با یک کلید سازگار با OpenAI و پرداخت ریالی، اولین درخواست متنی و تصویری را با پایتون بفرستید.
Gemini API چیست و چه کاربردهایی دارد؟
Gemini خانوادهٔ مدل‌های هوش مصنوعی شرکت گوگل است. نسخهٔ وب آن برای گفتگو طراحی شده، اما API به شما اجازه می‌دهد همین مدل‌ها را داخل نرم‌افزار، سایت، ربات یا اسکریپت‌های خودتان به کار ببرید. مهم‌ترین نقاط قوت Gemini عبارت‌اند از:
- پنجرهٔ زمینهٔ بزرگ: امکان پردازش متن‌های بسیار طولانی، مثل چند فصل کتاب، قرارداد مفصل یا بخش بزرگی از یک پروژهٔ نرم‌افزاری در یک درخواست.
- چندوجهی بودن (Multimodal): مدل‌ها علاوه بر متن، تصویر را هم می‌فهمند؛ مثلاً یک عکس فاکتور را می‌خوانند یا نمودار را تحلیل می‌کنند.
- تنوع نسخه‌ها: از نسخه‌های قدرتمند برای استدلال پیچیده تا نسخه‌های سبک و ارزان برای کارهای پرحجم.
- سرعت مناسب: نسخه‌های سبک برای کاربردهای بلادرنگ مثل چت‌بات و دسته‌بندی سریع مناسب‌اند.
آشنایی با نسخه‌های Gemini
گوگل مدل‌های Gemini را معمولاً در چند سطح عرضه می‌کند. شماره‌های نسخه با گذشت زمان تغییر می‌کند، اما منطق دسته‌بندی کم‌وبیش ثابت مانده است:
نسخه‌های Pro
قوی‌ترین مدل‌های خانوادهٔ Gemini برای استدلال چندمرحله‌ای، کدنویسی پیچیده، تحلیل اسناد طولانی و کارهایی که دقت در آن‌ها حیاتی است. هزینهٔ هر توکن در این نسخه‌ها بالاتر است.
نسخه‌های Flash
تعادلی میان کیفیت، سرعت و هزینه. برای بیشتر کاربردهای روزمره مثل چت‌بات پشتیبانی، تولید محتوا، خلاصه‌سازی و ترجمه، نقطهٔ شروع خوبی هستند.
نسخه‌های Flash-Lite
سبک‌ترین و اقتصادی‌ترین گزینه برای کارهای ساده و پرتکرار، مانند دسته‌بندی متن، استخراج اطلاعات کوتاه یا پاسخ‌های سریع.
نام دقیق مدل‌های فعال، به همراه نسخه‌های جدیدی که اضافه می‌شوند، همیشه در پنل کاربری الین لند نمایش داده می‌شود. پیش از نوشتن کد، نام مدل را از همان‌جا کپی کنید. برای مقایسهٔ Gemini با رقبای اصلی، مقالهٔ مقایسهٔ GPT، Claude و Gemini را ببینید.
دریافت کلید Gemini API با پرداخت ریالی
برای استفاده از Gemini از طریق الین لند، به حساب گوگل کلود یا کارت ارزی نیازی ندارید. مراحل کار ساده است:
- به صفحهٔ خرید کلید API Gemini بروید و پلن یا مقدار اعتبار موردنظر را انتخاب کنید.
- مبلغ را با کارت‌های عضو شتاب از طریق درگاه بانکی پرداخت کنید.
- کلید API و آدرس پایه (Base URL) را از پنل کاربری بردارید.
- کلید را در متغیرهای محیطی سیستم خود ذخیره کنید؛ نکات این کار را در راهنمای امنیت API Key توضیح داده‌ایم.
اگر هنوز مطمئن نیستید Gemini بهترین گزینه برای پروژهٔ شماست، می‌توانید با اعتبار OpenRouter چند مدل مختلف را با یک کلید امتحان کنید. راهنمای کلی خرید هم در مقالهٔ خرید API Key هوش مصنوعی در ایران آمده است.
اولین درخواست به Gemini با پایتون
سرویس الین لند با استاندارد OpenAI سازگار است؛ بنابراین برای کار با Gemini از همان کتابخانهٔ رسمی openai استفاده می‌کنید و فقط نام مدل را تغییر می‌دهید. ابتدا کتابخانه را نصب کنید:
pip install openai
سپس این کد را اجرا کنید:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ELIN_API_KEY"],
base_url=os.environ["BASE_URL"],
)
response = client.chat.completions.create(
model=os.environ.get("GEMINI_MODEL", "نام-مدل-Gemini-از-پنل"),
messages=[
{"role": "system", "content": "تو یک دستیار فارسی‌زبان دقیق هستی."},
{"role": "user", "content": "سه ایده برای نام یک کافه کتاب پیشنهاد بده."},
],
)
print(response.choices[0].message.content)
اگر با ساختار این کد آشنا نیستید، راهنمای کامل اتصال به API با پایتون همهٔ مراحل از نصب پایتون تا مدیریت خطا را پوشش می‌دهد.
ارسال تصویر به Gemini
یکی از قابلیت‌های جذاب Gemini درک تصویر است. در قالب سازگار با OpenAI، تصویر را می‌توانید به‌صورت Base64 در پیام قرار دهید. نمونهٔ زیر یک عکس فاکتور را می‌خواند و اطلاعات آن را استخراج می‌کند:
import base64
with open("invoice.jpg", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode()
response = client.chat.completions.create(
model=os.environ["GEMINI_MODEL"],
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "نام فروشنده، تاریخ و مبلغ کل این فاکتور را بنویس."},
{"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}},
],
}],
)
print(response.choices[0].message.content)
تصویرها هم مثل متن به توکن تبدیل و محاسبه می‌شوند؛ بنابراین پیش از ارسال، اندازهٔ تصویرهای خیلی بزرگ را کاهش دهید. پشتیبانی از تصویر به مدل انتخابی بستگی دارد؛ مدلی را انتخاب کنید که در پنل قابلیت ورودی تصویر برای آن ذکر شده باشد.
نکات حرفه‌ای برای کار با Gemini API
استریم پاسخ
در چت‌بات‌ها بهتر است پاسخ را کلمه‌به‌کلمه نمایش دهید تا کاربر منتظر نماند. کافی است در درخواست پارامتر stream=True را بگذارید و روی بخش‌های دریافتی حلقه بزنید.
خروجی ساختاریافته
اگر می‌خواهید خروجی را در برنامه پردازش کنید، از مدل بخواهید فقط JSON معتبر با فیلدهای مشخص برگرداند و نمونهٔ خروجی را در پرامپت قرار دهید. سپس در کد، خروجی را اعتبارسنجی کنید.
استفادهٔ هوشمندانه از زمینهٔ بزرگ
پنجرهٔ زمینهٔ بزرگ به این معنا نیست که همیشه باید از آن استفاده کنید. هر توکن ورودی هزینه دارد؛ فقط بخش‌های لازم را بفرستید. برای پاسخ‌گویی بر اساس اسناد زیاد، روش RAG معمولاً اقتصادی‌تر است.
پرامپت دقیق
نقش، قالب خروجی، طول پاسخ و مثال را مشخص کنید. Gemini مانند سایر مدل‌ها به دستورالعمل روشن بهتر پاسخ می‌دهد؛ تکنیک‌های آن را در راهنمای پرامپت‌نویسی ببینید.
کاربردهای عملی Gemini API
برای اینکه ایدهٔ روشن‌تری داشته باشید، چند کاربرد رایج Gemini در پروژه‌های واقعی را مرور می‌کنیم:
- خلاصه‌سازی اسناد طولانی: قراردادها، گزارش‌های مالی یا مقاله‌های علمی را به خلاصهٔ چندخطی فارسی تبدیل کنید و نکات کلیدی را استخراج کنید.
- استخراج اطلاعات از تصویر: خواندن فاکتور، رسید، کارت ویزیت یا فرم‌های اسکن‌شده و تبدیل آن‌ها به داده‌های ساختاریافته برای ورود به نرم‌افزار حسابداری یا CRM.
- تولید محتوای فروشگاه: نوشتن پیش‌نویس توضیحات محصول بر اساس عکس و مشخصات فنی، که بعد از بازبینی انسانی منتشر می‌شود.
- چت‌بات پشتیبانی: پاسخ سریع به سؤال‌های پرتکرار با نسخه‌های Flash که هزینهٔ هر پیام را پایین نگه می‌دارند.
- تحلیل بازخورد مشتریان: دسته‌بندی نظرها و پیام‌ها بر اساس موضوع و احساس، برای پیدا کردن مشکلات تکراری.
- کمک به کدنویسی: خواندن بخش بزرگی از کد پروژه و توضیح ساختار آن یا پیشنهاد اصلاح.
مدیریت خطا در کد
در محیط واقعی، درخواست‌ها گاهی با خطای شبکه، محدودیت نرخ (خطای 429) یا اتمام اعتبار روبه‌رو می‌شوند. درخواست‌ها را در بلوک try/except قرار دهید، برای خطاهای موقت چند بار با فاصلهٔ زمانی فزاینده دوباره تلاش کنید و پیام خطا را در لاگ ذخیره کنید تا علت مشکل قابل پیگیری باشد. برای خطای 401 تلاش دوباره فایده ندارد؛ کلید را بررسی کنید.
Gemini یا مدل‌های دیگر؟
Gemini برای پردازش اسناد طولانی، کارهای ترکیبی متن و تصویر و کاربردهای پرحجمی که سرعت و هزینه در آن‌ها مهم است، انتخاب بسیار خوبی است. برای نوشتن متن خلاقانهٔ فارسی یا کدنویسی ایجنتی، بسیاری از توسعه‌دهندگان Claude یا مدل‌های OpenAI را هم امتحان می‌کنند و برای کمترین هزینه، DeepSeek گزینهٔ محبوبی است. بهترین روش این است که چند مدل را روی نمونه‌های واقعی پروژهٔ خودتان آزمایش کنید و بر اساس کیفیت و هزینه تصمیم بگیرید. برای برآورد هزینه، مقالهٔ توکن و هزینهٔ API را بخوانید.
سؤالات متداول
آیا Gemini API فارسی را خوب می‌فهمد؟
بله، مدل‌های Gemini از زبان فارسی پشتیبانی می‌کنند و برای کارهایی مثل خلاصه‌سازی، ترجمه و پاسخ به سؤال عملکرد قابل قبولی دارند. کیفیت دقیق به نسخهٔ مدل و نوع کار بستگی دارد و بهتر است با نمونه‌های خودتان آزمایش کنید.
آیا برای استفاده از Gemini API به حساب گوگل نیاز دارم؟
اگر از طریق الین لند استفاده کنید، خیر. کلید و آدرس پایه را از پنل کاربری دریافت می‌کنید و با کتابخانهٔ OpenAI درخواست می‌فرستید.
کدام نسخهٔ Gemini برای چت‌بات مناسب‌تر است؟
برای بیشتر چت‌بات‌ها نسخه‌های Flash تعادل خوبی میان کیفیت، سرعت و هزینه دارند. اگر سؤال‌ها پیچیده و تخصصی است، نسخهٔ Pro و اگر حجم پیام‌ها بسیار زیاد و سؤال‌ها ساده است، Flash-Lite را امتحان کنید.
چرا خطای «مدل یافت نشد» می‌گیرم؟
نام مدل را دقیقاً از پنل کپی کنید. نام‌های مدل به حروف، خط تیره و شمارهٔ نسخه حساس‌اند و یک اختلاف کوچک باعث خطا می‌شود.
آیا می‌توانم با Gemini تصویر هم بسازم؟
گوگل برای تولید و ویرایش تصویر مدل‌های جداگانه‌ای دارد. در دسترس بودن این مدل‌ها از طریق الین لند به فهرست مدل‌های فعال در پنل بستگی دارد. اگر تمرکزتان تولید تصویر هنری است، اشتراک Midjourney را هم ببینید.
همین امروز با Gemini شروع کنید. کلید API Gemini را با پرداخت ریالی، تحویل فوری و پشتیبانی فارسی از الین لند تهیه کنید و اولین پروژهٔ هوشمندتان را بسازید.