۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مقاله

Gemini Developer API و AI Studio از ایران: راهنمای ۱۴۰۵

«Gemini Developer Hub» نام رسمی یک محصول واحد نیست، و مسیر واقعی توسعه با Gemini از Gemini Developer API و Google AI Studio می‌گذرد: AI Studio برای آزمون…

  • منتشر: ۱۸ آبان ۱۴۰۵
  • بروزرسانی: ۱ آذر ۱۴۰۵
  • ۹ دقیقه مطالعه
  • gemini
  • developer

تیمِ فنیِ 1xAi گیت‌وی را می‌سازد و می‌گرداند — همان‌هایی که هر روز با APIهای OpenAI‏، Anthropic‏، Google و DeepSeek از داخلِ ایران کار می‌کنند. آنچه اینجا می‌خوانی از همان کارِ روزمره درآمده، نه از بازنویسیِ مستنداتِ انگلیسی.

Gemini Developer API و AI Studio از ایران: راهنمای ۱۴۰۵

در این مقاله (۱۹)

«Gemini Developer Hub» نام رسمی یک محصول واحد نیست، و مسیر واقعی توسعه با Gemini از Gemini Developer API و Google AI Studio می‌گذرد: AI Studio برای آزمون پرامپت و گرفتن کلید است و Gemini Developer API خودِ رابط برنامه‌نویسی است. از داخل ایران، یک راه عملی برای فراخوانی مدل‌های Gemini استفاده از اندپوینت سازگار با OpenAI در 1xAi است. ما این گیت‌وی را اداره می‌کنیم، پس این توصیه دیدگاه یک فروشنده است. در ادامه اولین فراخوانی با پایتون و Node، مدیریت کلید تیمی، محدودیت نرخ و رفع خطای ۴۰۳ را قدم‌به‌قدم می‌بینید.

Gemini Developer API و AI Studio و Agent Platform: هرکدام چه کاری می‌کنند؟

برای شروع، آزمون پرامپت و گرفتن کلید را در AI Studio انجام دهید؛ کد را به Gemini Developer API وصل کنید؛ و فقط اگر کنترل محل دسترسی به مدل یا اکوسیستم Google Cloud لازم دارید، سراغ Agent Platform بروید. این سه چیز یکی نیستند و جستجوهایی مثل gemini developer studio یا gemini developer console معمولاً اولی را می‌خواهند.

ابزار کار کی انتخابش کنیم
Google AI Studio آزمون پرامپت، گرفتن و مدیریت کلید، پایش مصرف شروع کار و امتحان مدل‌ها
Gemini Developer API خود API که کدتان صدایش می‌زند ساخت محصول با gemini developer api key
Agent Platform API (پیش‌تر Vertex AI) دسترسی به مدل با کنترل محل و اتصال به Google Cloud تیمی که به این کنترل و آن اکوسیستم نیاز دارد

صفحه Android Developers هم این دو مسیر API را کنار هم می‌گذارد و Agent Platform را «پیش‌تر Vertex AI» معرفی می‌کند.

طبق Google AI for Developers، پروژه‌های جدید بهتر است از Interactions API شروع کنند. Google برای Python و JavaScript و Go و Java و C++ هم SDK رسمی دارد؛ این‌ها اطلاعات خود Google است، نه ارزیابی ما. برای نصب SDK و پرداخت تومانی از داخل ایران، راهنمای Gemini API از ایران را ببینید.

درباره مالک Gemini: Gemini محصول Google است و در دوسیه، Google DeepMind به‌عنوان سازنده‌اش آمده است.

چطور از ایران به Gemini API وصل شویم؟ (مسیر عملی و قدم‌به‌قدم)

با ساخت حساب در 1xAi، شارژ تومانی کیف پول و تنظیم base_url روی https://1xai.ir/v1 بدون VPN و کارت خارجی به Gemini وصل می‌شوید. جزئیات پرداخت و نصب در Gemini API: راهنمای نصب و اولین درخواست آمده است؛ اینجا فقط خود مسیر را می‌بینید.

چهار گام

  1. در 1xAi حساب بسازید.
  2. کیف پول تومانی را از طریق زرین‌پال پیش‌پرداخت کنید. ۱۰٪ مالیات در لحظه پرداخت به مبلغ اضافه می‌شود.
  3. از حساب کاربری‌تان کلید API بگیرید و در متغیر محیطی ONEXAI_API_KEY نگه دارید.
  4. در SDK، base_url را روی https://1xai.ir/v1 بگذارید. نام مدل‌ها در فهرست مدل‌ها هست؛ مثال‌های زیر از gemini-2.5-flash استفاده می‌کنند. این مدل در ۳۰ روز گذشته روی درگاه ما ۲٬۳۷۸ درخواست با ۱۰۰٪ موفقیت داشته است (آمار تأییدشده در ۸ نوامبر ۲۰۲۶).

پایتون

نیاز: پایتون ۳.۹ به بالا و بسته openai نسخه ۱ یا جدیدتر.

pip install openai
export ONEXAI_API_KEY="your-key-here"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEXAI_API_KEY"],
    base_url="https://1xai.ir/v1",
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "در یک جمله بگو API چیست؟"}],
)

print(response.choices[0].message.content)

خروجی یک جمله کوتاه فارسی در تعریف API است و متن دقیق آن در هر اجرا کمی فرق می‌کند.

Node.js

نیاز: Node 18 به بالا. فایل را با پسوند .mjs ذخیره کنید یا در package.json مقدار "type": "module" بگذارید.

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEXAI_API_KEY,
  baseURL: "https://1xai.ir/v1",
});

const response = await client.chat.completions.create({
  model: "gemini-2.5-flash",
  messages: [{ role: "user", content: "در یک جمله بگو API چیست؟" }],
});

console.log(response.choices[0].message.content);

curl

curl https://1xai.ir/v1/chat/completions \
  -H "Authorization: Bearer $ONEXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "سلام"}]
  }'

پاسخ یک JSON است و متن مدل در choices[0].message.content قرار دارد.

این کلید، کلید Google نیست

کلیدی که اینجا می‌گیرید کلید 1xAi است و فقط روی https://1xai.ir/v1 کار می‌کند. اگر دنبال Gemini developer API key خود Google هستید، آن کلید را کنسول Google می‌دهد و ربطی به این مسیر ندارد.

برعکس هم صادق است: این کلید را در SDK رسمی Google (google-genai) یا اندپوینت‌های اختصاصی گوگل نگذارید. برای اتصال از طریق ما همان SDK سازگار با OpenAI را به کار ببرید، مثل مثال‌های بالا.

کدام مدل Gemini را انتخاب کنیم و هزینه‌اش چقدر است؟

پیش‌فرض ما gemini-2.5-flash است؛ برای کار ساده و پرحجم به flash-lite و برای استدلال سنگین به مدل‌های Pro بروید. gemini-2.5-flash در ۳۰ روز اخیر بیشترین درخواست را میان مدل‌های Gemini همین جدول روی درگاه ما داشته است: ۲٬۳۷۸ درخواست با ۱۰۰٪ موفقیت.

قیمت‌های جدول زیر هر صبح با نرخ روز بازار هماهنگ می‌شوند. منبع زنده و قابل‌بررسی آن‌ها 1xai.ir/models است. اگر دنبال gemini developer api pricing به تومان می‌گردید، همین جدول را مبنا بگیرید.

مدل مارک‌آپ ورودی (تومان / ۱M توکن) خروجی (تومان / ۱M توکن) ۳۰ روز اخیر
gemini-2.5-flash-lite ۳۰٪ ۳۵٬۳۹۹ ۱۴۱٬۵۹۶ ۲٬۱۳۰ درخواست، ۱۰۰٪ موفقیت
gemini-2.5-flash ۳۰٪ ۱۰۶٬۱۹۷ ۸۸۴٬۹۷۵ ۲٬۳۷۸ درخواست، ۱۰۰٪ موفقیت
gemini-3.1-flash-lite ۲۰٪ ۸۱٬۶۹۰ ۴۹۰٬۱۴۰ ۲٬۲۵۰ درخواست، ۱۰۰٪ موفقیت
gemini-3.5-flash ۲۰٪ ۴۹۰٬۱۴۰ ۲٬۹۴۰٬۸۴۰ ۹۱ درخواست، ۱۰۰٪ موفقیت
gemini-3.1-pro-preview ۱۵٪ ۶۲۶٬۲۹۰ ۳٬۷۵۷٬۷۴۰ ۷۵۳ درخواست، ۹۸٫۸٪ موفقیت
gemini-2.5-pro ۱۵٪ ۳۹۱٬۴۳۱ ۳٬۱۳۱٬۴۵۰ آمار این بازه در این نوشته نیامده

چطور از جدول تصمیم بگیریم

  • کار ساده و پرحجم (دسته‌بندی، استخراج فیلد، خلاصه‌ی کوتاه): با flash-lite شروع کنید. gemini-3.1-flash-lite هم با ۲٬۲۵۰ درخواست و ۱۰۰٪ موفقیت گزینه‌ی هم‌خانواده است.
  • استدلال و کدنویسی سنگین: سراغ gemini-3.1-pro-preview یا gemini-2.5-pro بروید. مارک‌آپ هر دو ۱۵٪ است، اما آمار ۳۰ روزه‌ی gemini-2.5-pro در این نوشته نیامده.
  • ظرافت‌های جدول: gemini-3.1-pro-preview تنها ردیفِ دارای آمار است که زیر ۱۰۰٪ موفقیت دارد (۹۸٫۸٪ از ۷۵۳ درخواست). نمونه‌ی gemini-3.5-flash هم فقط ۹۱ درخواست است و برای نتیجه‌گیری قطعی کوچک است.

مارک‌آپ ما بسته به مدل بین ۱۵ تا ۳۰٪ است. حساب‌هایی که در ۳۰ روز اخیر مصرف کیف پولشان از آستانه‌ی پرمصرف ما بالاتر رفته باشد، حداکثر ۱۵٪ می‌پردازند؛ مبلغ زنده و دقیق هر مدل همیشه در صفحه‌ی قیمت مدل‌ها آمده است.

چند پروژه و کلید را در تیم استارتاپی چطور مدیریت کنیم؟

برای هر سرویس و هر محیط یک کلید جدا بگیرید و کلید را فقط سمت سرور نگه دارید. موارد زیر راهنمای عمومی است و ویژگی پنل 1xAi نیست:

  • کلید جدا برای هر سرویس و محیط (توسعه، تست، تولید): نشت یک کلید فقط همان بخش را درگیر می‌کند و مصرف هر بخش جدا دیده می‌شود.
  • چرخش کلید پس از خروج هر عضو تیم: هر کلیدی که او به آن دسترسی داشت را ابطال و جایگزین کنید.
  • بودجه یا کف مصرف: برای هر محیط سقفی تعیین کنید و موجودی کیف پول را در حد نیاز نگه دارید تا یک حلقهٔ خطا کل اعتبار را مصرف نکند.

در سمت Google، AI Studio جایی است که کلیدها را می‌سازید و مصرفشان را پایش می‌کنید. مستندات Google هم می‌گوید کلید API در کلاینت وب یا موبایل فقط برای نمونه‌سازی مناسب است. برای تولید باید از Firebase AI Logic یا یک بک‌اند استفاده کنید.

تنظیم امن متغیر محیطی

# کلید را در .env بگذارید و آن را از git کنار بگذارید
echo "GEMINI_API_KEY=your-key-here" > .env
echo ".env" >> .gitignore

# بارگذاری در شل فعلی
set -a; source .env; set +a

# بررسی بدون چاپ کامل کلید
echo "${GEMINI_API_KEY:0:4}..."

در CI، کلید را در secret manager همان سرویس نگه دارید و هنگام اجرا به‌صورت متغیر محیطی تزریق کنید، نه داخل فایل مخزن. به همین ترتیب فایل‌های جدا مثل .env.dev و .env.test را هم به .gitignore اضافه کنید. اگر تولید محتوا با API را هم در برنامه دارید، تولید محتوا با API در ۲۰۲۶ ادامهٔ مسیر از سمت سرور را نشان می‌دهد. کلید را هرگز در کد فرانت‌اند یا مخزن نگذارید.

محدودیت نرخ، سهمیه رایگان و خطاهای ۴۰۳: چک‌لیست رفع مشکل

سقف سهمیه رایگان و rate limit در Gemini به مدل و سطح حساب بستگی دارد، و عدد معتبر آن فقط در صفحه rate limit مستندات Google AI for Developers آمده است. ما عددی از Google نقل نمی‌کنیم، چون با تغییر مدل یا سطح حساب عوض می‌شود. چیزی که صفحه Android Developers تأیید می‌کند فقط وجود «سطح رایگان بدون اطلاعات پرداخت» است، نه سقف آن. برای سقف‌های 1xAi هم عددی نداریم که اینجا بیاوریم.

اگر فقط می‌خواهید بدون هزینه شروع کنید، چرخ هدیه 1xAi برای هر حساب یک چرخش دارد و نتیجه آن اعتبار کیف پول است که منقضی نمی‌شود. مبلغ اعتبار با قرعه‌کشی سمت سرور مشخص می‌شود و محدوده آن در همان صفحه آمده است.

جدول علامت، دلیل محتمل، اقدام

علامت دلیل محتمل اقدام
۴۰۳ یا پیام «location not supported» هنگام اتصال مستقیم به اندپوینت Google محدودیت منطقه‌ای سمت Google درخواست را از مسیر https://1xai.ir/v1 بفرستید. ما دور زدن شرایط ارائه‌دهنده را توصیه نمی‌کنیم.
۴۰۱ کلید اشتباه، کلید Google به‌جای کلید 1xAi، یا فاصله و خط جدید اضافه در متغیر محیطی کلید 1xAi را دوباره کپی کنید و متغیر را پاکسازی کنید (دستور زیر).
۴۲۹ ارسال درخواست بیش از سقف مدل یا حساب فاصله درخواست‌ها را بیشتر کنید و با backoff تکرار کنید. سقف را در صفحه rate limit مستندات Google بررسی کنید.
خطای «model not found» نام مدل با نام موجود در گیت‌وی یکی نیست نام دقیق را از فهرست مدل‌ها بردارید.

برای حذف فاصله و خط جدید از کلید در پوسته bash:

export ONEXAI_API_KEY="$(printf %s "$ONEXAI_API_KEY" | tr -d '[:space:]')"

اگر پس از این اصلاحات هم خطا ماند، متن کامل پاسخ سرور و نام مدل را نگه دارید؛ با همین دو مورد ریشه مشکل معمولاً سریع پیدا می‌شود.

پژوهش و نگارش: the CodeNest content engine

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

چطور کار با Gemini API را شروع کنم؟

کلید را از Google AI Studio بگیرید و پرامپت را همان‌جا آزمایش کنید. SDKهای رسمی Google برای Python، JavaScript، Go، Java و C++ هستند. از ایران، ساده‌ترین مسیر عملی در 1xAi اندپوینت سازگار با OpenAI است که بدون VPN و کارت خارجی، با پرداخت تومانی، مدل‌های Gemini را فراخوانی می‌کند.

مالک Gemini کدام کشور است؟

Gemini محصول Google و تیم Google DeepMind است. Google شرکتی آمریکایی است، بنابراین مالک Gemini از نظر شرکتی آمریکایی محسوب می‌شود. دسترسی از ایران به این مدل‌ها از طریق گیت‌وی 1xAi انجام می‌شود، نه مستقیم.

توسعه‌دهنده هوش مصنوعی چه کسی است؟

توسعه‌دهنده هوش مصنوعی کسی است که مدل‌ها را در نرم‌افزار یا محصول به کار می‌گیرد، مثلاً با فراخوانی API، نوشتن پرامپت و مدیریت کلید و خطاها. لازم نیست خودش مدل را آموزش دهد. در این راهنما منظور، برنامه‌نویسی است که Gemini را از طریق API در محصول خود استفاده می‌کند.

قیمت gemini-2.5-pro در 1xAi چقدر است؟

قیمت رسمی این مدل ۱٫۲۵ دلار برای ورودی و ۱۰ دلار برای خروجی به ازای هر یک میلیون توکن است. در 1xAi کارمزد این مدل ۱۵٪ است و قیمت جاری هر یک میلیون توکن ورودی ۳۹۱٬۴۳۱ تومان و خروجی ۳٬۱۳۱٬۴۵۰ تومان است. این ارقام هر روز صبح با نرخ بازار دلار هماهنگ می‌شوند. قیمت رسمی توکن ورودی کش‌شده (کش پرامپت) ۰٫۱۲۵ دلار برای هر یک میلیون توکن است.

gemini-3.1-flash-lite برای پروژه‌های کم‌هزینه مناسب است؟

قیمت رسمی ۰٫۲۵ دلار ورودی و ۱٫۵ دلار خروجی برای هر یک میلیون توکن است. در 1xAi با کارمزد ۲۰٪، ورودی ۸۱٬۶۹۰ تومان و خروجی ۴۹۰٬۱۴۰ تومان به ازای هر یک میلیون توکن است. در ۳۰ روز گذشته روی گیت‌وی ما ۲٬۲۵۰ درخواست با ۱۰۰٪ موفقیت ثبت شده است.

مدل‌هایی که در این مقاله دیدی را از داخل ایران امتحان کن.

بدون VPN، صورت‌حساب تومانی، کارمزدِ ۱۵ تا ۳۰٪ بسته به مدل روی نرخِ هر سرویس‌دهنده.