# أنشئ مفتاح Gemini API وأضفه

> إعداد مفتاح من Google AI Studio مع تفعيل الفوترة، وحفظه في Keychain، ثم اختباره على مقطع قصير.
>
> جرى التحقق من المحتوى مقابل تطبيق RoughCut الحالي بتاريخ 28 أغسطس 2026
> https://www.roughcuteditor.com/ar/docs/gemini-api-key

Gemini هو المزود الافتراضي في RoughCut لمرحلة المونتاج بالذكاء الاصطناعي. تنشئ المفتاح في Google AI Studio، ثم تفعّل الفوترة على مشروع Google Cloud المرتبط به لأن النموذج الافتراضي في RoughCut ضمن فئة مدفوعة، ثم تلصق المفتاح في إعدادات RoughCut حيث يُحفظ في Keychain على macOS. اختبره بمقطع قصير مفعّل فيه استبعاد المحاولات غير الموفقة. وتحاسبك Google على مفتاحك مباشرة وفق أسعارها المعلنة، ولا يرى RoughCut استخدامك أبدا. وواجهة Google تتغير بمعزل عن RoughCut، لذا اعتبر وثائق Google نفسها هي المرجع للشاشات بالضبط، واتبع منطق الخطوات لا نص الأزرار حرفيا.

## المتطلبات المسبقة

- حساب Google.
- وسيلة دفع تقبل ربطها بمشروع على Google Cloud.
- تثبيت RoughCut. ولا تحتاج نموذج التعرف على الكلام في هذه الخطوة.

> تتحكم Google بهذا المسار وتغيّره من حين إلى آخر. والخطوات أدناه تصف شكل العملية الحالي؛ فإذا وجدت زرا باسم مختلف، اتبع الإجراء المكافئ بدل البحث عن النص الحرفي. ووثائق Google عن [مفاتيح API](https://ai.google.dev/gemini-api/docs/api-key) وعن [الفوترة](https://ai.google.dev/gemini-api/docs/billing) هي المرجع.

## الخطوات

1. افتح [صفحة مفاتيح API في Google AI Studio](https://aistudio.google.com/apikey) وسجّل الدخول. وفي جولة الترحيب في RoughCut زر باسم `فتح Google AI Studio` يأخذك إلى الوجهة نفسها.
2. أنشئ مفتاح API. وسينشئ AI Studio مشروع Google Cloud نيابة عنك، أو يطلب منك اختيار مشروع قائم.
3. **فعّل الفوترة على ذلك المشروع وأضف وسيلة دفع.** فالنموذج الافتراضي في RoughCut ضمن الفئة المدفوعة لدى Google، ومفتاح بلا فوترة سيفشل عند تشغيل مرحلة المونتاج. وهذه هي الخطوة التي يتجاوزها الناس أكثر من غيرها.
4. انسخ المفتاح.
5. في RoughCut، افتح `Settings`. ومن تبويب `Basic` (أو `Full → LLM`) اعثر على `مفتاح Gemini API`.
6. ألصق المفتاح في الحقل واضغط زر `حفظ`. يؤكد RoughCut بالرسالة `تم حفظ مفتاح Gemini API في Keychain.`
7. تأكد من أن `مزود LLM` مضبوط على `gemini`. وهو الوضع الافتراضي.
8. اختبره: أنشئ مشروعا قصيرا مع تفعيل `استبعاد المحاولات غير الموفقة`. فإذا كان المفتاح والفوترة سليمين، يكتمل المشروع وتعرض قائمة المراجعة ملخص محرر يسمي المزود والنموذج.

## النتيجة المتوقعة

يعرض حقل `مفتاح Gemini API` تأكيدا أخضر والقيمة مخفية، مع العبارة `محفوظ في Keychain` وزري `استبدال...` و`استبعاد`. ويكتمل مشروع الاختبار بعمليات استبعاد مقترحة من الذكاء الاصطناعي بدل نتيجة تعتمد على الصمت وحده.

## ملاحظة عن الخصوصية والتكلفة

يُحفظ المفتاح في Keychain على macOS، مشفرا بواسطة النظام، ولا يُرسل إلا إلى Google. ولا توجد لـ RoughCut خوادم في هذا المسار، ولا يرى استخدامك ولا فاتورتك أبدا.

وتحاسبك Google على مفتاحك وفق أسعارها المعلنة. والتسجيلات الطويلة أعلى تكلفة، و[المراجعة الثانية](/ar/docs/second-look) تضيف مكالمة أخرى. ولا ينشر RoughCut رقما لكل فيديو لأن الأسعار وخيارات النماذج تتغير.

## إدارة المفتاح وتبديله

- **`استبدال...`** يضع مفتاحا جديدا مكان القديم من دون كشف القديم.
- **`استبعاد`** يحذف المفتاح من Keychain. وعندها يتصرف RoughCut كأنه بلا مفتاح: يظل المونتاج المعتمد على الصمت وحده يعمل، بينما يفشل `استبعاد المحاولات غير الموفقة` في الفحص المسبق برسالة تطلب منك إضافة مفتاح أو تعطيل الميزة.
- وإذا تسرب مفتاح يوما ما، ألغِه من Google AI Studio وأنشئ غيره. التبديل يستغرق ثوانٍ ولا شيء يحتاج ترحيلا.

## أخطاء شائعة

- **إنشاء المفتاح دون تفعيل الفوترة.** يوجد المفتاح ويبدو سليما، ثم تفشل مرحلة المونتاج بخطأ في الحصة أو الفوترة. فعّل الفوترة على المشروع الذي يملك المفتاح.
- **تفعيل الفوترة على مشروع آخر.** قد ينشئ AI Studio مشروعا جديدا بصمت؛ فتأكد أن الفوترة مفعّلة على المشروع صاحب المفتاح.
- **لصق مفتاح تحيط به مسافات أو علامات اقتباس.** ألصق القيمة الخام وحدها.
- **توقع ظهور المفتاح في ملف إعدادات.** لا يظهر أبدا — فالأسرار تعيش في Keychain وحده، وتُنزع قبل كتابة الإعدادات على القرص.

## حل المشكلات

| الرسالة أو العَرَض | السبب المرجح | الحل |
|---|---|---|
| `لا يوجد مفتاح API للمزود «gemini». أضفه في الإعدادات، أو عطّل استبعاد المحاولات غير الموفقة لإنشاء مونتاج يعتمد على الصمت فقط.` | لا مفتاح محفوظ | احفظ مفتاحا، أو عطّل `استبعاد المحاولات غير الموفقة` |
| خطأ حصة أو فوترة من Google | الفوترة غير مفعّلة على مشروع المفتاح | فعّل الفوترة ثم أعد المحاولة |
| مفتاح غير صالح أو غير مصرح له | لُصقت قيمة خاطئة، أو أُلغي المفتاح | أنشئ مفتاحا جديدا واستخدم `استبدال...` |
| رفض الوصول إلى النموذج | مشروعك لا يستطيع الوصول إلى النموذج المضبوط | راجع اسم النموذج في `Settings → Full → LLM` ضمن حقل `نموذج Gemini` مقابل ما يستطيع مشروعك استدعاءه |
| انتهاء المهلة | نص مفرغ طويل جدا أو اتصال بطيء | المهلة 600 ثانية افتراضيا وقابلة للضبط؛ أعد المحاولة، أو قسّم التسجيل |