واجهة Gemini API CLI: مكّن وكيل البرمجة لديك من استدعاء Gemini للصور والفيديو وملفات PDF والبحث المتعمق

واجهة سطر أوامر Gemini API (gemini-api) هي عميل سطر الأوامر مفتوح المصدر من Google لواجهة Gemini API، مصمم لوكلاء البرمجة مثل Claude Code و Codex و Cursor و Antigravity. قم بتثبيت ملف Go الثنائي الواحد، واضبط GEMINI_API_KEY، ويمكن لوكيلك إنشاء الصور والفيديو والكلام والموسيقى، وتحليل ملفات PDF والتسجيلات، ونسخ الصوت إلى SRT، وبدء Deep Research في الخلفية.

أدناه: التثبيت، المصادقة، الأوامر التي سيشغلها وكيلك، وكيف يختلف عن Gemini CLI، وكيفية إقرانه مع Apidog CLI. تم نسخ كل علامة من gemini-api --help في الإصدار 0.4.5، الصادر في 30 أكتوبر 2026.

ما هو Gemini API CLI؟

Gemini API CLI هو عميل عديم الحالة، ثنائي واحد، لواجهة Interactions API من Google. كل أمر هو استدعاء HTTP واحد: يدخل طلب، ويخرج مسار ملف أو نسخة أو تحليل أو معرّف تفاعل. إنها أداة يستدعيها وكيلك الحالي عندما تحتاج مهمة إلى Gemini.

صفحة الوثائق الرسمية من Google تسميها "إصدار تجريبي مفتوح المصدر يتطور جنبًا إلى جنب مع Interactions API". الكود موجود في google-gemini/gemini-api-cli تحت رخصة Apache 2.0، ويعمل على macOS و Linux و Windows.

هذا ما يسرده gemini-api --help في 0.4.5، مع النموذج الافتراضي لكل أمر:

Gemini API CLI مقابل Gemini CLI

الأسماء متقاربة، لذا إليك الفرق. Gemini CLI (@google/gemini-cli) هو وكيل برمجة تفاعلي، بديل لـ Claude Code تتحدث معه. Gemini API CLI (gemini-api) ليس لديه حلقة وكيل على الإطلاق. إنها أداة يشغلها وكيل آخر.

إذا كنت تعمل في Claude Code أو Codex وتريد نماذج الوسائط والبحث من Gemini داخل سير العمل هذا، استخدم gemini-api. إنه نفس النمط الذي يتبعه OpenAI CLI، ولكن موجه إلى Google.

كيفية تثبيت Gemini API CLI

اختر أحد المسارات الأربعة من README.

macOS و Linux:

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

Windows (PowerShell):

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

Go:

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

ملفات ثنائية جاهزة: قم بتنزيل الأرشيف الخاص بمنصتك من GitHub Releases، وتحقق منه مقابل checksums.txt، وضع gemini-api على PATH الخاص بك. استخدمنا أرشيف Darwin_arm64؛ وطبع shasum -a 256 -c checksums.txt --ignore-missing OK.

تحذر Google من أن التغييرات الكاسرة قد تظهر بين الإصدارات الثانوية، لذا ثبّت إصدارًا في CI. تُظهر الوثائق سكريبت التثبيت مع GEMINI_VERSION=<release-tag> موضوعًا قبل bash.

أكّد التثبيت:

gemini-api version
# gemini-api 0.4.5

مصادقة Gemini API CLI

أنشئ مفتاحًا في Google AI Studio (دليلنا للحصول على مفتاح Gemini API مجانًا يشرح ذلك)، ثم صدّره:

export GEMINI_API_KEY="YOUR_API_KEY"

على محطة العمل الخاصة بك، يمكنك تخزينه بدلاً من ذلك:

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

configure يحفظ المفتاح في سلسلة مفاتيح نظام التشغيل (macOS Keychain أو Linux Secret Service أو Windows Credential Manager). أضف العلامة العامة --no-keyring للاحتفاظ به في ~/.config/gemini-api/config.yaml بدلاً من ذلك. يُظهر whoami أي بيانات اعتماد نشطة ومن أين أتت.

مع عدم تعيين مفتاح، يطبع gemini-api --help سطرًا موجهًا إلى الوكيل نفسه: مفتاح API "يجب إنشاؤه يدويًا بواسطة المستخدم في Google AI Studio. توقف واطلب من المستخدم إنشاء واحد". سيسألك وكيلك بدلاً من تكوين مفتاح من تلقاء نفسه.

معاينة أي استدعاء باستخدام --dry-run

--dry-run يتحقق من العلامات ويطبع الطلب مع حجب بيانات الاعتماد، دون استدعاء شبكة ودون قراءة سلسلة المفاتيح. يعمل قبل تعيين مفتاح، وهكذا تحققنا من كل مثال هنا.

إليك تشغيل تجريبي حقيقي لمهمة Deep Research في الخلفية:

كل أمر يرسل POST إلى https://generativelanguage.googleapis.com/v1beta/interactions. أضف -o json للحصول على كائن JSON واحد لكل طلب على stdout، والذي يمكن للوكيل تحليله قبل إنفاق رمز مميز.

أوامر Gemini API CLI التي سيشغلها وكيلك

إنشاء الصور وتعديلها

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg

أوامر الوسائط تكتب الملف وتطبع مساره فقط، لذا يلتقطه الوكيل باستخدام $(...) ويستمر في البناء. يأخذ image أيضًا --aspect-ratio و --image-size (512، 1K، 2K أو 4K). النموذج الافتراضي هو Nano Banana 2.1؛ راجع دليل Nano Banana 2.1 API لما يبرع فيه.

إنشاء الفيديو والكلام والموسيقى

gemini-api video "A slow camera move through a sunlit workshop" --resolution 1080p --out ./assets/
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/

يستغرق الفيديو وقتًا أطول، لذا يقوم video بالاستطلاع نيابة عنك. استخدم --async للحصول على مقبض العملية فورًا و --resume <id> لاستئناف الاستطلاع لاحقًا. الإعداد الافتراضي لـ --resolution هو 720p.

تحليل ملفات PDF والصور وعناوين URL من YouTube

gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze -i before.png -i after.png "Summarize the visual design changes"

-i/--input قابل للتكرار ويقبل مسارًا محليًا، أو معرف URI files/<id>، أو عنوان URL من YouTube. تقتصر المدخلات المضمّنة على حوالي 14 ميغابايت خام. للملفات الأكبر، ارفعها مرة واحدة وأعد استخدام معرف URI:

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps"

يتم حذف الملفات المرفوعة بعد 48 ساعة.

نسخ الصوت والفيديو

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt

--format يأخذ md (افتراضي)، text، json أو srt. أضف --no-speakers أو --no-timestamps لإزالة أي منهما من المخرجات.

تشغيل Deep Research في الخلفية

ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json

--background يعيد معرّف تفاعل فورًا بدلاً من إبقاء التدفق مفتوحًا. يخزن الوكيل المعرّف، ويعمل على شيء آخر، ويتحقق مرة أخرى باستخدام agent status. يوقف agent cancel التشغيل. تسرد مساعدة 0.4.5 أيضًا deep-research-max-preview-04-2026 و antigravity-preview-05-2026 كوكلاء مُدارين.

العلامات التي تجعل gemini-api آمنًا للوكلاء

هذه هي العلامات العامة الجديرة بالوضع في تعليمات وكيلك، كلها من gemini-api --help-global:

• --agent-mode (أو GEMINI_CLI_AGENT_MODE=1): أخطاء JSON منظمة على stderr ومخرجات TOON مضغوطة على stdout.
• -o, --output-format: pretty أو json أو yaml أو table أو toon.
• -q, --jq: تصفية المخرجات في السطر، على سبيل المثال --jq '.id'.
• --no-interactive: لا توجد مطالبات أو نماذج TUI، وهو ما يحتاجه وكيل بلا واجهة.
• --usage: شجرة الأوامر الكاملة بصيغة KDL قابلة للقراءة آليًا.
• --schema (لكل أمر): مخطط JSON لحمولة --body.

تخبر رموز الخروج الوكيل بما حدث خطأ دون تحليل النص: 0 حسنًا، 1 فشل وقت التشغيل أو API، 2 خطأ استخدام أو تحقق، 3 مصادقة. ملاحظة واحدة: أوامر البث (generate، agent run) تحتاج إلى --stream=false قبل أن يعطي -o json أو --jq نتيجة واحدة قابلة للتحليل.

امنح وكيل البرمجة الخاص بك Gemini API CLI

يشحن README الخاص بـ Google كتلة للصق في AGENTS.md أو CLAUDE.md أو .cursorrules. مختصرة:

You have access to gemini-api through the shell.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run.
3. For JSON output or --jq on streaming commands, pass --stream=false --output-format json.
4. Capture returned file paths and interaction IDs to continue multi-step tasks.

تأكد من وصول GEMINI_API_KEY إلى بيئة العملية الفرعية للوكيل. ثم اطلب كالمعتاد: "ابنِ صفحة الهبوط، واستخدم Gemini لصورة تميمة وتعليق صوتي مدته 20 ثانية، وابدأ تشغيل Deep Research على المنتجات المنافسة." يختار الوكيل الأوامر.

ما لا يفعله: الصوت أو الفيديو في الوقت الفعلي. لا يوجد دعم WebSocket، لذا لا تزال Live API بحاجة إلى GenAI SDKs.

اختبر واجهة API التي تبنيها باستخدام Apidog CLI

gemini-api يمنح وكيلك نماذج Gemini. إنه لا يعرف شيئًا عن واجهة API الخاصة بك: نقطة النهاية /summarize أو /thumbnail التي يلفها تطبيقك حول Gemini، أو بيئاتها، أو التأكيدات التي تثبت أن الإصدار لم ينكسر. هذه مهمة Apidog CLI، ويمكن للوكيل نفسه تشغيل كليهما.

قم بإعداده مرة واحدة:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

ثم أعط وكيلك مطالبة واحدة:

Use gemini-api to dry-run an analyze call on ./docs/sample-invoice.pdf, then run it for real.
Import ./openapi.yaml into Apidog project <id>, create a test case for POST /v1/invoices/extract
that uploads the same PDF and asserts a 200 and a non-empty "total" field, run it against the
staging environment, and summarize any failures.

يتحقق الوكيل من إجابة Gemini باستخدام gemini-api، ثم يقرأ مخطط Apidog قبل كتابة حمولة، ويتحقق من صحتها، وينشئ الحالة ويشغلها:

apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json

apidog test-case create --help يشير إلى فخ واحد: تحتاج الحالة إلى categoryId صالح، لذا اسردها أولاً باستخدام apidog test-case category --project <id>. استبدل -r cli,json بـ -r junit وسيعمل نفس السطر في CI. إذا كان Claude Code هو وكيلك، فابدأ بـ Apidog CLI في Claude Code. تغطي خطة Apidog المجانية حتى 4 مستخدمين.

الأسئلة الشائعة

هل Gemini API CLI مجاني؟ الأداة نفسها مجانية ومفتوحة المصدر تحت رخصة Apache 2.0. كل استدعاء يُحتسب على مفتاح API الخاص بك وفقًا لتسعير Gemini API العادي. لمعرفة ما تغطيه الطبقة المجانية، راجع دليل الطبقة المجانية من Gemini API.

هل gemini-api هو نفسه Gemini CLI؟ لا. Gemini CLI هو وكيل برمجة تفاعلي. gemini-api هو أداة عديمة الحالة يستدعيها وكلاء آخرون ونصوص برمجية ومهام CI للوصول إلى نماذج Gemini والوكلاء المُدارين.

هل يمكنني اختبار الأوامر بدون مفتاح API؟ نعم. --dry-run يتحقق من الأمر ويطبع الطلب الدقيق دون استدعاء شبكة ودون قراءة سلسلة المفاتيح. تم التحقق من كل مثال في هذا المنشور بهذه الطريقة على 0.4.5.

كيف أتعامل مع الملفات الأكبر من 14 ميغابايت؟ شغّل gemini-api files upload <file> --wait، واحتفظ بـ files/<id> المُعاد، ومرّره إلى -i في analyze أو transcribe أو generate أو image أو video أو agent run. تنتهي صلاحية التحميلات بعد 48 ساعة.

هل يجب تثبيت إصدار؟ نعم، في CI. تقول Google إن التغييرات الكاسرة يمكن أن تحدث بين الإصدارات الثانوية بينما الأداة في النسخة التجريبية.