Gemini API CLI چیه؟ نصب، ساخت زیرنویس خودکار و فرقش با Gemini CLI

یه پوشه پر از اپیزود داری و حوصله‌ی زیرنویس و فصل‌بندی دستی رو نداری؟ Gemini API CLI ابزار خط فرمان آزمایشی گوگله که مدل‌های جمنای رو مستقیم از ترمینال صدا می‌زنه. با یه حلقه‌ی کوچیک می‌تونی صدا رو به SRT و بعد به عنوان و فصل‌بندی تبدیل کنی.

توی این مطلب:

1. Gemini API CLI چیه؟

2. فرق Gemini API CLI با Gemini CLI، AI Studio و API خام

3. نصب Gemini API CLI

4. سناریو: زیرنویس و فصل‌بندی خودکار

5. به درد کیا می‌خوره؟

6. محدودیت‌ها

7. اشتراک Gemini Pro کجای این ماجراست؟

8. سوال‌های پرتکرار

ویدیوی کامل: Gemini API CLI در ۶ دقیقه

Gemini API CLI چیه؟

گوگل ۱۹ اکتبر ۲۰۲۶ توی بلاگ رسمی AI Studio Gemini API CLI رو معرفی کرد. نسخه‌ی v0.4.3 همون روز توی صفحه‌ی Releases گیت‌هاب منتشر شد. کد ابزار توی مخزن google-gemini/gemini-api-cli با لایسنس Apache-2.0 هست.

فرق Gemini API CLI با Gemini CLI، AI Studio و API خام

اسم‌ها شبیه هم‌ان، کارشون نه. نویسنده‌ی بلاگ گوگل هم توی X این فرق رو توضیح داده.

از ویدیوی پیکسول: هر ابزار برای یه کار.

یه نکته‌ی جانبی: داکیومنت Gemini CLI می‌گه برای کاربرهای سطح بدون پرداخت و Google One، از ۱۸ ژوئن ۲۰۲۶ Antigravity CLI جای Gemini CLI رو گرفته.

نصب Gemini API CLI؛ فقط قدم‌های رسمی

دستورهای نصب از README رسمی برداشته شدن. یکی رو انتخاب کن:

1. macOS و لینوکس:

   text

   کپی کد

   curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

2. ویندوز (PowerShell):

   text

   کپی کد

   iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

3. با Go:

   text

   کپی کد

   go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

   یا فایل اجرایی رو از Releases بگیر.

4. بررسی نصب و کلید:

   text

   کپی کد

   gemini-api version
   export GEMINI_API_KEY="YOUR_API_KEY"
   # یا ذخیره‌ی کلید در keychain سیستم:
   gemini-api configure --interactive
   gemini-api whoami

کلید رو از صفحه‌ی API key در AI Studio می‌گیری. whoami نشون می‌ده کدوم کلید و تنظیمات فعاله. ما این مراحل رو بدون کلید اجرا کردیم: gemini-api version عدد 0.4.3 رو برگردوند و درخواست واقعی بدون کلید با خطای احراز هویت (HTTP 403، کد خروج 3) متوقف شد.

سناریو: زیرنویس SRT و فصل‌بندی یوتیوب با Gemini API CLI

فرض کن پوشه‌ی episodes/ سه اپیزود صوتی داره. می‌خوای برای هر کدوم زیرنویس، عنوان فارسی و فصل‌بندی داشته باشی.

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

قدم ۱: صدا به SRT با transcribe

اول با --dry-run درخواست رو بدون ارسال ببین:

gemini-api transcribe -i episodes/ep01.mp3 -i episodes/ep02.mp3 -i episodes/ep03.mp3 \
  --format srt --out ./subs/ --dry-run

خروجی واقعی ما برای هر فایل [DRY-RUN] Would send: POST …/v1beta/interactions با مدل پیش‌فرض gemini-3.8-flash بود و هیچ درخواستی فرستاده نشد. با چند ورودی، --out یه پوشه‌ست. بعد --dry-run رو بردار.

فایل بزرگ داری؟ اول files upload

طبق راهنمای دستور، درخواست درون‌خطی زیر حدود ۲۰ مگابایت base64 (حدود ۱۴ مگابایت فایل خام) جا می‌شه. برای فایل بزرگ‌تر، اول آپلود کن:

FILE=$(gemini-api files upload long-episode.mp4 --wait --output-format json --jq '.name')
gemini-api transcribe -i "$FILE" --format srt --out long-episode.srt

طبق راهنمای files upload، فایل‌ها بعد از ۴۸ ساعت منقضی می‌شن. سقف هر فایل ۲ گیگابایت و سقف هر پروژه ۲۰ گیگابایته.

قدم ۲: عنوان و فصل‌بندی با analyze (و نکته‌ی SRT)

اگه فایل SRT رو مستقیم بدی، این خطای واقعی رو می‌گیری (کد خروج 2):

Error (validation_error): --input[1] "ep01.srt": MIME type application/x-subrip is not accepted by the Interactions API

راه‌حل همونیه که خود خطا پیشنهاد می‌ده: --mime-type text/plain. ما این رو با --dry-run امتحان کردیم و بدون خطا رد شد. حلقه‌ی کامل:

for f in subs/*.srt; do
  gemini-api analyze -i "$f" --mime-type text/plain \
    --system "Answer in Persian." \
    "Write a title and chapters" > "${f%.srt}.md"
done

نمونه‌ی نمایشی خروجی (واقعی نیست، فقط شکل کار رو نشون می‌ده):

عنوان: [عنوان فارسی پیشنهادی اپیزود]
00:00 [فصل اول]
02:10 [فصل دوم]
…

قدم ۳: خروجی JSON برای اسکریپت و ایجنت

برای خروجی ساخت‌یافته از --output-format json استفاده کن. با --jq هم فقط فیلدی که لازم داری رو بیرون می‌کشی:

gemini-api analyze -i subs/ep01.srt --mime-type text/plain \
  "Write a title and chapters" --output-format json

README دو گزینه‌ی دیگه هم داره: --output-format toon و --agent-mode که خطاها رو به شکل JSON روی stderr می‌ده. کدهای خروج هم ثابت‌ان: ۰ موفق، ۱ خطای اجرا، ۲ خطای استفاده، ۳ احراز هویت. اسکریپت‌ت می‌تونه روی همین‌ها تصمیم بگیره.

Gemini API CLI به درد کیا می‌خوره و به درد کیا نه؟

از ویدیوی پیکسول:

محدودیت‌های Gemini API CLI و Gemini API

این موارد ممکنه تغییر کنن؛ قبل از شروع خودت چک کن.

• بتاست: README می‌گه تغییرات ناسازگار ممکنه بیاد و توی CI نسخه رو ثابت کن.

• سطح رایگان: صفحه‌ی رسمی Pricing سطح Free، Paid و Enterprise داره. طبق همین صفحه، بعضی مدل‌های تصویر، ویدیو و موسیقی روی سطح رایگان در دسترس نیستن و محتوای سطح رایگان برای بهبود محصولات گوگل استفاده می‌شه.

• سقف درخواست: طبق صفحه‌ی Rate limits سقف‌ها (RPM، TPM، RPD) برای هر پروژه حساب می‌شن، نه هر کلید. سقف فعال رو داخل AI Studio می‌بینی و تضمینی نیست.

• کشورها: در فهرست رسمی Available regions ایران جزو کشورهای پشتیبانی‌شده‌ی Gemini API و AI Studio نیست (بررسی ۲۳ اکتبر ۲۰۲۶). قبل از هر استفاده‌ای شرایط رسمی رو بخون.

اشتراک Gemini Pro کجای این ماجراست؟

صادقانه: اشتراک Gemini Pro کلید API نیست و Gemini API CLI رو راه نمی‌اندازه. اون ابزار کلید جدا از AI Studio می‌خواد. اشتراک برای اینه که خود جمنای رو توی اپ Gemini، Gmail، Drive و ابزارهای گوگل با امکانات پلن Pro استفاده کنی.

اگه این همون چیزیه که لازم داری، اشتراک Gemini Pro رو ببین. قیمت لحظه خرید روی PDP نمایش داده می‌شه.

• آنی: لینک فعال‌سازی بعد از پرداخت توی بخش سفارشت قرار می‌گیره.

• اصل: فعال‌سازی از مسیر رسمی گوگل و روی جیمیل خودت انجام می‌شه.

• امن: شرایط ضمانت و بازگشت وجه توی رویه بازگشت وجه نوشته شده.

• درگاه: پرداخت بانکی ریالی.

چک‌لیست خرید امن از ایران

1. یه جیمیل انتخاب کن که اشتراک فعال یا تازه‌منقضی Google AI Pro / Google One نداشته باشه. این محصول برای تمدید نیست.

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

3. بعد از پرداخت، لینک رو از بخش سفارش بگیر و فقط با همون جیمیل باز کن.

4. اگه لینک مشکل داشت، داخل مهلت به پشتیبانی پیکسول پیام بده.

5. سوال درباره‌ی پرداخت و تحویل داری؟ سوالات متداول رو ببین.

مشاهده‌ی اشتراک Gemini Pro و قیمت لحظه‌ای

اگه بیشتر با ایجنت کدنویسی کار می‌کنی، اشتراک کلاد (Claude AI) و بقیه‌ی ابزارهای کدنویسی AI رو هم ببین. همه‌ی گزینه‌ها توی ابزارهای هوش مصنوعی هستن.

سوال‌های پرتکرار درباره‌ی Gemini API CLI

جمع‌بندی

• Gemini API CLI یه ابزار آزمایشی و سبک برای صدا زدن Gemini API از ترمیناله، نه Gemini CLI.

• نصبش یه خطه، ولی کلید API از AI Studio لازمه.

• برای کار دسته‌ای مثل زیرنویس و فصل‌بندی عالیه. برای SRT یادت نره --mime-type text/plain.

• بتاست، سقف و سطح رایگان داره و ایران در فهرست رسمی کشورها نیست.

خرید اشتراک جمنای پرو: اشتراک Gemini Pro

منابع رسمی

• Introducing the Gemini API CLI — Google AI Studio

• google-gemini/gemini-api-cli — GitHub (README)

• Gemini API CLI Releases — GitHub

• Gemini API Pricing

• Gemini API Rate limits

• Gemini API Available regions

• google-gemini/gemini-cli — GitHub

• Gemini CLI docs

• توضیح Dmitry Lyalin درباره‌ی فرق API و CLI — X

آخرین بررسی منابع: ۱ آبان ۱۴۰۵ (۲۳ اکتبر ۲۰۲۶).