راهنمای اتصال به API

اتصال Gemini CLI به 1ai؛ GOOGLE_GEMINI_BASE_URL و کلید API

Gemini CLI عامل برنامه‌نویسی گوگل در ترمینال است: کد پروژه را می‌خواند، فایل‌ها را ویرایش می‌کند و دستور اجرا می‌کند. وان ای آی (1ai) قالب Google را در مسیر POST /v1beta/models/<model>:generateContent دارد، پس Gemini CLI با عوض کردن آدرس و کلید به 1ai وصل می‌شود و هر مدل چت را می‌پذیرد. اعتبار را با پرداخت ریالی می‌خرید و برای کلید سقف مصرف می‌گذارید. این تنظیمات با Gemini CLI نسخه‌ی 0.67 و با یک نوبت فراخوانی ابزار آزموده شده‌اند.

ساخت کلید APIمدل‌های مناسب Gemini CLI (با پشتیبانی از ابزار)

چرا با 1ai

همان قالبی که Gemini CLI می‌فرستد

Gemini CLI درخواست را به مسیرهای /v1beta/models/… می‌فرستد و 1ai همین قالب را با استریم و فراخوانی ابزار جواب می‌دهد.

Gemini و مدل‌های دیگر

هر مدل چت 1ai در Gemini CLI کار می‌کند. کافی است شناسه‌ی کامل مدل را با -m بدهید.

پرداخت ریالی

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

سقف مصرف برای هر کلید

برای کلید Gemini CLI سقف ماهانه، مدل‌های مجاز و تاریخ انقضا بگذارید و مصرف را در پنل توسعه‌دهنده ببینید.

در چند قدم

  1. ۱

    Gemini CLI را نصب کنید

    با npm install -g @google/gemini-cli نصبش کنید.

  2. ۲

    کلید API بسازید

    در پنل 1ai از بخش توسعه‌دهندگان ← کلیدها یک کلید با نام Gemini CLI و سقف ماهانه بسازید.

  3. ۳

    متغیرها را تنظیم کنید

    کلید را در GEMINI_API_KEY و آدرس https://1ai.ir را در GOOGLE_GEMINI_BASE_URL بگذارید.

  4. ۴

    روش ورود را تعیین کنید

    در ~/.gemini/settings.json مقدار selectedType را gemini-api-key بگذارید؛ متن کامل در بخش بعد آمده است.

  5. ۵

    Gemini CLI را اجرا کنید

    در پوشه‌ی پروژه gemini -m google/gemini-3.8-flash را بزنید و با یک کار کوچک شروع کنید.

مدل‌های مناسب Gemini CLI (با پشتیبانی از ابزار)

همه‌ی مدل‌ها

GPT-6 Luna

اوپن‌ای‌آی
گفتگو

سریع و بسیار ارزان؛ مدل پیش‌فرض و در نسخه‌ی رایگان

شروع پاسخ ۲٫۶ ثانیه و سرعت ۷۴ توکن در ثانیه

در نسخه‌ی رایگان
رایگانAPI

GPT-6.1 Sol

اوپن‌ای‌آی
گفتگو

پرچم‌دار اوپن‌ای‌آی برای کارهای دقیق، تحلیلی و چندمرحله‌ای

شروع پاسخ ۵٫۶ ثانیه و سرعت ۵۷ توکن در ثانیه

با اشتراک
API

Claude Sonnet 5.5

آنتروپیک
گفتگو

نویسندگی روان و برنامه‌نویسی دقیق

با اشتراک
API

Gemini 3.8 Flash

گوگل
گفتگو

سریع، چندوجهی و با حافظه‌ی متنی بسیار بلند

با اشتراک
API

Claude Haiku 5.5

آنتروپیک
گفتگو

سریع‌ترین کلود؛ در نسخه‌ی رایگان

شروع پاسخ ۴٫۶ ثانیه و سرعت ۲۹۸ توکن در ثانیه

در نسخه‌ی رایگان
رایگانAPI

Gemini 3.5 Flash Lite

گوگل
گفتگو

سبک و ارزان؛ در نسخه‌ی رایگان

در نسخه‌ی رایگان
رایگانAPI

نمونه پرامپت‌ها

پرامپت را کپی کنید، در 1ai بگذارید و جزئیات خودتان را جایگزین کنید.

شناخت پروژه

Explain the structure of this project and how a request flows through it. Do not change any file yet.

پیش از هر تغییری ببینید پروژه را درست فهمیده است.

رفع خطا

Find the cause of this error and fix it with minimal changes: [متن خطا]. Run `[دستور تست، مثلاً npm test]` afterwards and report what passed.

بررسی یک فایل

@[مسیر فایل] Find possible null or undefined errors in this file and fix them with minimal changes. Explain each fix in one line.

گزارش فارسی

با git log بررسی کن در ده commit آخر چه تغییرهایی داده شده و به فارسی خلاصه کن کدام بخش‌های پروژه بیشترین تغییر را داشته‌اند.

تنظیم متغیرها و settings.json برای 1ai

این دو متغیر را تنظیم کنید:

bash
export GEMINI_API_KEY=sk-1ai-...
export GOOGLE_GEMINI_BASE_URL=https://1ai.ir

بعد روش ورود را در ~/.gemini/settings.json مشخص کنید:

json
{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

بدون این تنظیم، Gemini CLI با پیام Invalid auth method selected. متوقف می‌شود. اگر این فایل را از قبل دارید، فقط بخش security را به آن اضافه کنید.

آدرس پایه را بدون /v1 و /v1beta بنویسید. برای ماندگار شدن تنظیمات، خطوط export را در ~/.zshrc یا ~/.bashrc بگذارید و کلید را در مخزن پروژه commit نکنید.

انتخاب مدل در Gemini CLI

هر مدل چت 1ai با پرچم -m انتخاب می‌شود:

bash
gemini -m google/gemini-3.8-flash
gemini -m anthropic/claude-sonnet-5.5
gemini -m openai/gpt-6.1-sol

نام gemini-… بدون پیشوند هم خودکار به google/gemini-… می‌رسد و مدل‌های دیگر پیشوند سازنده‌شان را نگه می‌دارند. Gemini CLI بدون فراخوانی ابزار کار نمی‌کند، پس مدلی انتخاب کنید که tools داشته باشد. فهرست این مدل‌ها در همین صفحه آمده و مقایسه‌ی کلی خانواده‌ها در برنامه‌نویسی با هوش مصنوعی است.

چه چیزهایی کار نمی‌کند؟

  • ابزار جستجوی وب خود Gemini CLI کار نمی‌کند، چون ابزارهای میزبانی‌شده‌ی گوگل (googleSearch، codeExecution و urlContext) با خطای 400 رد می‌شوند.
  • فیلدهای cachedContent، candidateCount، responseModalities و speechConfig نادیده گرفته می‌شوند.

فراخوانی مستقیم قالب Google

اگر از کد خودتان این قالب را صدا می‌زنید، کلید را در سرآیند x-goog-api-key بفرستید:

bash
curl https://1ai.ir/v1beta/models/gemini-3.8-flash:generateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "role": "user", "parts": [{ "text": "سلام، خودت را در یک جمله معرفی کن." }] }]
  }'

پارامتر ?key= هم پذیرفته می‌شود، ولی سرآیند را پیشنهاد می‌کنیم؛ چون نشانی ممکن است در مسیر ثبت شود و کلید همراهش بماند.

مدل‌های دیگر هم پیشوند سازنده را در مسیر دارند، مثل /v1beta/models/openai/gpt-6.1-sol:generateContent. برای استریم :streamGenerateContent، برای شمارش توکن :countTokens و برای فهرست مدل‌ها GET /v1beta/models را به کار ببرید.

خطاهای رایج Gemini CLI با 1ai و راه‌حل

  • Invalid auth method selected.: مقدار selectedType در ~/.gemini/settings.json تنظیم نشده است.
  • 401: کلید اشتباه، باطل یا منقضی است، یا GEMINI_API_KEY در همین ترمینال تنظیم نشده است.
  • 402: اعتبار یا سقف ماهانه‌ی کلید تمام شده است.
  • 404: شناسه‌ی مدل اشتباه است، یا آدرس پایه با /v1beta نوشته شده است.
  • 400 هنگام جستجوی وب: ابزار جستجوی خود Gemini CLI در 1ai کار نمی‌کند؛ از آن استفاده نکنید.
  • 429: سقف درخواست یا توکن در دقیقه پر شده؛ کمی صبر کنید و جلسه‌های هم‌زمان را کم کنید.

چطور هزینه‌ی Gemini CLI را کنترل کنیم؟

  • برای موضوع تازه جلسه‌ی تازه باز کنید تا تاریخچه‌ی قبلی در هر درخواست فرستاده نشود.
  • برای کارهای ساده مدل ارزان‌تری با -m انتخاب کنید.
  • برای Gemini CLI کلید جدا با سقف ماهانه و فهرست مدل‌های مجاز بسازید.

جزئیات در راهنمای کلیدها و کنترل هزینه آمده است. برای عامل‌های ترمینالی دیگر، راهنمای Claude Code و راهنمای Codex CLI را ببینید.

ابزارهای آماده

توضیح کد و رفع باگ

کد را بفهمید، خطایش را پیدا کنید و تمیزش کنید

ساخت عبارت باقاعده (Regex)

الگوی Regex با توضیح و نمونه‌ی آزمون

ساخت کوئری SQL

درخواست فارسی، کوئری درست و توضیح‌داده‌شده

دستیارهای مرتبط

برنامه‌نویس ارشد

نوشتن، مرور و اشکال‌زدایی کد با توضیح روشن

  • «این کد را مرور کن و باگ‌ها و مشکلات امنیتی‌اش را بگو: »
  • «یک API ساده برای مدیریت کارها با Node.js و Express بنویس»

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

برای Gemini CLI با 1ai به حساب گوگل نیاز دارم؟

خیر. با این تنظیمات Gemini CLI با کلید 1ai کار می‌کند و هزینه‌ی هر درخواست از اعتبار API کم می‌شود. اعتبار را جدا می‌خرید و اشتراک چت 1ai شامل آن نمی‌شود.

چرا با پیام Invalid auth method selected متوقف می‌شود؟

Gemini CLI باید بداند با کلید API وارد می‌شوید. در ~/.gemini/settings.json مقدار security.auth.selectedType را gemini-api-key بگذارید و دوباره اجرا کنید.

می‌توانم Gemini CLI را با Claude یا GPT اجرا کنم؟

بله. هر مدل چت 1ai در این قالب کار می‌کند. شناسه‌ی کامل مدل را با -m بدهید، مثل gemini -m anthropic/claude-sonnet-5.5. مدل باید فراخوانی ابزار داشته باشد.

جستجوی وب Gemini CLI کار می‌کند؟

خیر. این ابزار به ابزارهای میزبانی‌شده‌ی گوگل تکیه دارد و 1ai آن‌ها را با خطای 400 رد می‌کند. اگر در کارتان به جستجو نیاز دارید، نتیجه‌ی جستجو را خودتان به گفتگو بدهید یا از Claude Code روی مدلی که برای جستجو قیمت دارد استفاده کنید.

کلید را در سرآیند بفرستم یا در نشانی؟

در فراخوانی مستقیم، سرآیند x-goog-api-key را پیشنهاد می‌کنیم. ?key= هم کار می‌کند، ولی نشانی ممکن است در مسیر ثبت شود.

چطور پیش از Gemini CLI مطمئن شوم کلید و آدرس درست است؟

در ترمینال curl https://1ai.ir/v1beta/models -H "x-goog-api-key: sk-1ai-..." را اجرا کنید. اگر فهرست مدل‌ها برگشت، کلید و آدرس سالم‌اند و مشکل در متغیرهای محیطی یا settings.json است.

مطالب مرتبط

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

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

۴ دقیقه مطالعه
مقایسه ChatGPT، Claude و Gemini: کدام مدل برای چه کاری؟
کاربردها

مقایسه ChatGPT، Claude و Gemini: کدام مدل برای چه کاری؟

سه خانواده‌ی مطرح مدل‌های زبانی، یعنی GPT از OpenAI، Claude از Anthropic و Gemini از گوگل، هر کدام کجا می‌درخشند و چطور برای کار خودتان بهترین را انتخاب کنید.

۴ دقیقه مطالعه
گوی سرامیکی هوش مصنوعی در حلقه‌ای فلزی با نمادهای سند، تصویر و موج صدا روی زمینهٔ آبی و بنفش
ابزارها و مدل‌ها

جمنای (Gemini) چیست؟ مدل‌های گوگل و راهنمای استفاده در ایران

Gemini خانوادهٔ مدل‌های هوش مصنوعی گوگل برای کار با متن، تصویر و ورودی‌های چندرسانه‌ای است. مدل‌های فعلی، مزیت زمینهٔ طولانی و روش استفاده در ایران با 1ai را همراه چند پرامپت فارسی بشناسید.

۱۱ دقیقه مطالعه
لپ‌تاپ مینیاتوری سرامیکی و دست رباتیک در حال تکمیل قطعات هندسی روی پس‌زمینهٔ آبی و بنفش
کاربردها

بهترین هوش مصنوعی برای برنامه نویسی؛ مقایسه مدل‌ها و ابزارها

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

۱۴ دقیقه مطالعه

صفحه‌های مرتبط

همه‌ی امکانات

اتصال Claude Code

Claude Code را با چند متغیر محیطی به 1ai وصل کنید، در ترمینال با Claude یا هر مدل چت دیگر کدنویسی کنید و بدانید برای کار بدون خطای اعتبار چه موجودی‌ای لازم است.

اتصال Codex CLI

Codex CLI را با چند خط در config.toml به 1ai وصل کنید و در ترمینال با مدل‌های GPT، Gemini و Claude از یک کلید کدنویسی کنید.

اتصال OpenCode

OpenCode را با یک ارائه‌دهنده‌ی سفارشی در opencode.json به 1ai وصل کنید و در ترمینال با Claude، GPT، Qwen و DeepSeek از یک کلید کدنویسی کنید.

اتصال Continue

Continue را با چند خط config.yaml به API سازگار با OpenAI در 1ai وصل کنید و برای چت، ویرایش، Agent و تکمیل خودکار مدل جداگانه بگذارید.

اتصال Gemini CLI به 1ai؛ GOOGLE_GEMINI_BASE_URL و کلید API

Gemini CLI را با دو متغیر محیطی و یک خط در settings.json به 1ai وصل کنید و در ترمینال با Gemini یا هر مدل چت دیگر از یک کلید کدنویسی کنید.

ساخت کلید API