Yusuf Khalidd

Posted on May 9 • Originally published at apidog.com

الحصول على Gemini API مجاني وغير محدود

توفّر عائلة Gemini من Google نماذج قوية لتطبيقات الذكاء الاصطناعي، لكن التكلفة قد تتزايد بسرعة عندما يبدأ آلاف المستخدمين في استدعاء نقطة النهاية الخاصة بك. يغيّر Puter.js هذا النمط: يمكنك استدعاء نماذج Gemini وGemma من المتصفح بدون مفتاح Google API، وبدون مشروع Google Cloud، وبدون خادم وسيط. يتحمّل المستخدم النهائي الاستخدام عبر حساب Puter الخاص به، بينما تبقى واجهة المطوّر مجانية وغير محدودة.

جرّب Apidog اليوم

الخلاصة

Puter.js يمنحك وصولًا مجانيًا وغير محدود من جهة المطوّر إلى كتالوج Gemini وGemma بدون مفتاح Google API.
النماذج المدعومة تشمل: 2.5 Pro و2.5 Flash و2.5 Flash Lite و2.0 Flash و2.0 Flash Lite و3 Flash Preview.
عائلة Gemma المدعومة تشمل: Gemma 2 وGemma 3 وGemma 4 بأحجام متعددة.
تحتاج إلى وسم <script> واحد واستدعاء دالة واحدة لتشغيل Gemini داخل المتصفح.
يدعم Puter.js البث المباشر، إدخال الصور، المحادثات متعددة الأدوار، وضبط درجة الحرارة.
استخدم Apidog لمقارنة التكاملات وتخطيط الانتقال إلى واجهة Gemini الرسمية عند الحاجة.

كيف يعمل نموذج "مجاني وغير محدود"

بدلًا من أن تحتفظ أنت بمفتاح Google AI Studio وتدفع تكلفة كل رمز مميز، يسجّل المستخدم الدخول إلى Puter، ثم تُخصم تكلفة الاستدعاء من حسابه. يحصل المستخدمون الجدد على رصيد بداية، ويمكنهم إعادة الشحن إذا احتاجوا إلى استخدام إضافي.

بالنسبة لك كمطوّر:

لا تحتاج إلى مشروع Google Cloud.
لا تحتاج إلى إدارة مفاتيح API أو متغيرات بيئة.
لا توجد علاقة فوترة مباشرة مع Google.
لا تحتاج إلى خادم وسيط فقط لإخفاء المفتاح.
يتوسع الاستخدام مع عدد المستخدمين بدلًا من أن يتراكم كله على حسابك.

المفاضلة المهمة: Puter.js موجّه أولًا للمتصفح. إذا كنت تحتاج إلى مهام خلفية مثل cron jobs أو webhooks أو معالجة دفعية بدون جلسة مستخدم، فاستخدم واجهة Gemini الرسمية.

الخطوة 1: تثبيت Puter.js

لصفحة HTML بسيطة، أضف سكريبت CDN:

<script src="https://js.puter.com/v2/"></script>

هذا يكفي لتشغيل Puter.js في المتصفح.

إذا كنت تستخدم تطبيقًا مبنيًا بأداة تجميع مثل Vite أو Next.js أو Webpack:

npm install @heyputer/puter.js

ثم استورده في الكود:

import { puter } from '@heyputer/puter.js';

الخطوة 2: اختيار نموذج Gemini أو Gemma

اختر النموذج بناءً على نوع المهمة:

معرف النموذج	متى تستخدمه
`google/gemini-2.5-pro`	للاستدلال العميق، التحليل المعقد، ومهام السياق الطويل
`google/gemini-2.5-flash`	الخيار الافتراضي لمعظم تطبيقات الدردشة والأسئلة والأجوبة
`google/gemini-2.5-flash-lite`	مهام التصنيف والوسم عالية الحجم حيث تكون السرعة مهمة
`google/gemini-2.0-flash`	خيار مستقر لسلوك معروف ومتوقع
`google/gemini-3-flash-preview`	تجربة أحدث إصدار معاينة من Flash
`google/gemma-3-27b-it`	نموذج Gemma مفتوح ومضبوط للتعليمات
`google/gemma-4-31b-it`	نموذج Gemma أكبر عندما تحتاج إلى جودة أعلى ضمن عائلة Gemma

للبداية، استخدم:

google/gemini-2.5-flash

ثم انتقل إلى google/gemini-2.5-pro فقط عندما تحتاج إلى تفكير أعمق أو تحليل أكثر تعقيدًا.

الخطوة 3: أول استدعاء إلى Gemini من المتصفح

هذا مثال كامل قابل للتشغيل:

<!DOCTYPE html>
<html lang="ar">
<body>
  <div id="output"></div>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    const output = document.getElementById('output');

    puter.ai.chat(
      "اشرح تعلم الآلة في ثلاث جمل",
      { model: 'google/gemini-2.5-flash' }
    ).then(response => {
      output.textContent = response;
    }).catch(error => {
      console.error(error);
      output.textContent = 'حدث خطأ أثناء استدعاء النموذج.';
    });
  </script>
</body>
</html>

افتح الملف في المتصفح. عند أول استخدام، يتعامل Puter مع تسجيل دخول المستخدم أو إنشاء حساب. لا تحتاج إلى مفتاح API أو خادم خلفي.

الخطوة 4: بث الاستجابة في واجهة الدردشة

في واجهات الدردشة، لا تنتظر اكتمال النص بالكامل. استخدم stream: true لعرض الاستجابة تدريجيًا:

const outputDiv = document.getElementById('output');

const response = await puter.ai.chat(
  "اشرح عملية البناء الضوئي بالتفصيل",
  {
    model: 'google/gemini-2.5-flash',
    stream: true,
  }
);

for await (const part of response) {
  if (part?.text) {
    outputDiv.innerHTML += part.text;
  }
}

كل part.text يمثل جزءًا من الاستجابة. أضفه مباشرة إلى واجهة المستخدم للحصول على تجربة شبيهة بتطبيقات الدردشة الحديثة.

الخطوة 5: استخدام Gemini مع الصور

يدعم Gemini الإدخال متعدد الوسائط. مرّر رابط الصورة كوسيط ثانٍ:

puter.ai.chat(
  "ماذا ترى في هذه الصورة؟ صف الألوان والعناصر والمزاج العام.",
  "https://assets.puter.site/doge.jpeg",
  { model: 'google/gemini-2.5-flash' }
).then(response => {
  puter.print(response);
});

أمثلة عملية:

توليد النص البديل للصور.
تحليل لقطات الشاشة.
استخراج معلومات من صور المنتجات.
مراجعة واجهات المستخدم بصريًا.
دعم أدوات الوصول.
التعرف الضوئي على الحروف OCR في بعض الحالات.

جودة رؤية Gemini قوية في الصور الطبيعية والرسوم البيانية، لكن لقطات الشاشة النصية الكثيفة قد تحتاج إلى اختبار ومقارنة حسب حالتك.

الخطوة 6: ضبط درجة الحرارة

استخدم temperature للتحكم في عشوائية المخرجات:

const response = await puter.ai.chat(
  'اكتب قصة قصيرة إبداعية عن روبوت يعمل طاهيًا',
  {
    model: 'google/gemini-2.5-flash',
    temperature: 0.8,
  }
);

console.log(response);

قاعدة عملية:

0.0 إلى 0.3: مخرجات أكثر ثباتًا، مناسبة للتصنيف والبيانات المنظمة.
0.4 إلى 0.7: توازن مناسب للدردشة العامة.
0.8 إلى 1.0: مخرجات أكثر تنوعًا، مناسبة للكتابة الإبداعية.

مثال لمهمة تصنيف:

const response = await puter.ai.chat(
  'صنّف هذه الرسالة كـ: دعم، مبيعات، أو شكوى. الرسالة: لا أستطيع تسجيل الدخول.',
  {
    model: 'google/gemini-2.5-flash-lite',
    temperature: 0.1,
  }
);

الخطوة 7: بناء محادثة متعددة الأدوار

مرّر مصفوفة رسائل بدلًا من نص واحد:

const messages = [
  { role: 'user', content: 'أنا أبني تطبيق Next.js مع PostgreSQL.' },
  { role: 'assistant', content: 'فهمت. ما الجزء الذي تحتاج مساعدة فيه؟' },
  { role: 'user', content: 'كيف أنظم ملفات migrations؟' },
];

const response = await puter.ai.chat(messages, {
  model: 'google/gemini-2.5-pro',
});

console.log(response);

للاستخدام داخل تطبيق دردشة، احتفظ بالحالة محليًا:

const messages = [];

async function sendMessage(userText) {
  messages.push({ role: 'user', content: userText });

  const assistantReply = await puter.ai.chat(messages, {
    model: 'google/gemini-2.5-flash',
  });

  messages.push({ role: 'assistant', content: assistantReply });

  return assistantReply;
}

بهذا الشكل يحصل النموذج على سياق المحادثة بالكامل في كل استدعاء.

مقارنة Gemini بنماذج أخرى على نفس المطالبة

يعرض Puter عدة نماذج عبر واجهة واحدة. يمكنك اختبار نفس المطالبة على أكثر من نموذج:

const models = [
  'google/gemini-2.5-flash',
  'claude-sonnet-4-6',
  'gpt-5.5',
  'x-ai/grok-4.3',
];

const prompt = "Refactor this React component to use hooks: ...";

for (const model of models) {
  const start = performance.now();

  const response = await puter.ai.chat(prompt, { model });

  const elapsed = performance.now() - start;

  console.log(`${model}: ${elapsed.toFixed(0)}ms`);
  console.log(response);
  console.log('---');
}

استخدم هذا النمط لتقييم:

زمن الاستجابة.
جودة الإجابة.
الاتساق بين المحاولات.
ملاءمة النموذج للمهمة.

لا تعتمد على تجربة واحدة فقط. اختبر مجموعة مطالبات تمثل استخدامك الحقيقي.

ماذا يدعم Puter.js مع Gemini

تحصل عادةً على:

نماذج Gemini 2.5 و2.0 و3 Flash Preview و2.5 Pro.
نماذج Gemma المفتوحة.
المحادثات متعددة الأدوار.
الاستجابات المتدفقة.
إدخال الصور عبر عنوان URL.
إعدادات مثل temperature وmax_tokens ومطالبات النظام حسب الدعم المتاح.

وقد لا تحصل على كل ميزات Gemini الرسمية، حسب إصدار Puter والدعم الحالي، مثل:

استدعاء الدوال الأصلي.
أدوات تنفيذ الأكواد.
ترسيخ بحث Google.
الوصول الكامل إلى نافذة سياق Gemini القصوى.
تشغيل خلفي بدون جلسة مستخدم.
رؤية مباشرة لحدود معدل Google.

إذا كنت تبني وكيلًا معقدًا يحتاج إلى أدوات تنفيذ، ترسيخ بحث، أو تحكم كامل في البنية الخلفية، فواجهة Google AI Studio الرسمية قد تكون أنسب. أما لتطبيقات الدردشة، الأسئلة والأجوبة، توليد المحتوى، والنماذج الأولية داخل المتصفح، فـ Puter.js يكفي غالبًا.

متى تستخدم Puter بدل واجهة Gemini الرسمية

استخدم Puter عندما:

تبني تطبيقًا عامًا مجانيًا وتريد تجنب مخاطر الفوترة.
تعمل على نموذج أولي أو مشروع هاكاثون.
تريد تشغيل Gemini داخل موقع ثابت.
لا تريد إعداد Google Cloud.
يمكن للمستخدمين تسجيل الدخول إلى Puter.

استخدم واجهة Gemini الرسمية عندما:

تحتاج إلى استدعاءات من الخادم.
لديك مهام مجدولة أو معالجة دفعية.
تحتاج إلى webhooks أو تكاملات خلفية.
تحتاج إلى تنفيذ أكواد أو ترسيخ بحث.
تحتاج إلى متطلبات امتثال أو علاقة مباشرة مع Google.
لا تريد إضافة خطوة تسجيل دخول Puter للمستخدمين.

لشرح أوسع حول Gemini 3 Flash، راجع: كيفية استخدام واجهة برمجة تطبيقات Gemini 3 Flash Preview.

اختبار التكامل باستخدام Apidog

استدعاءات Puter تحدث داخل المتصفح، لذلك لا تختبرها بنفس طريقة اختبار REST API خلفية. النمط العملي هو:

أنشئ صفحة HTML صغيرة تحتوي على Puter.js.
اجعل المطالبة قابلة للتمرير عبر query parameter.
استخدم الصفحة لاختبار تجربة المستخدم والتدفق داخل المتصفح.
استخدم Apidog لاختبار واجهة Gemini الرسمية إذا قررت الانتقال إلى الخادم.
احتفظ ببيئتين منفصلتين: واحدة للنموذج الأولي عبر Puter، وأخرى للإنتاج عبر Gemini API.

مثال صفحة اختبار بسيطة:

<!DOCTYPE html>
<html lang="ar">
<body>
  <pre id="output">جارٍ التحميل...</pre>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    const params = new URLSearchParams(location.search);
    const prompt = params.get('prompt') || 'اكتب ملخصًا قصيرًا عن REST APIs';

    puter.ai.chat(prompt, {
      model: 'google/gemini-2.5-flash',
    }).then(response => {
      document.getElementById('output').textContent = response;
    }).catch(error => {
      document.getElementById('output').textContent = error.message;
    });
  </script>
</body>
</html>

ثم شغّلها مثلًا:

http://localhost:5173/?prompt=اشرح%20JSON%20Schema

قم بـ تنزيل Apidog وأنشئ بيئتين:

puter-prototype: عنوان الصفحة المحلية التي تستضيف Puter.js.
gemini-prod: https://generativelanguage.googleapis.com/v1.

لأنماط اختبار API الأوسع، راجع: أداة اختبار API لمهندسي ضمان الجودة.

مسارات LLM مجانية أخرى عبر Puter

نفس نموذج الدفع من جهة المستخدم ينطبق على مزودين آخرين عبر Puter. يمكنك تغيير قيمة model فقط لتجربة نماذج مختلفة.

روابط مفيدة:

مثال تبديل النموذج:

const response = await puter.ai.chat(
  "لخّص هذا النص في خمس نقاط: ...",
  {
    model: 'google/gemini-2.5-flash',
  }
);

غيّرها إلى نموذج آخر عند المقارنة:

const response = await puter.ai.chat(
  "لخّص هذا النص في خمس نقاط: ...",
  {
    model: 'claude-sonnet-4-6',
  }
);

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

هل الاستخدام غير محدود فعلًا؟

غير محدود من جهة المطوّر. المستخدم النهائي يستخدم رصيد حسابه على Puter، والحسابات الجديدة تحصل على رصيد بداية.

هل أحتاج إلى حساب Google أو مشروع Google Cloud؟

لا. Puter يتعامل مع الاستدعاء الأساسي، ولن تحتاج إلى مفتاح Google API داخل تطبيقك.

هل يمكن استخدامه في الإنتاج؟

نعم لتطبيقات الويب المعتمدة على المتصفح، بشرط أن تكون خطوة تسجيل دخول Puter مناسبة لتجربة المستخدم لديك.

هل يعمل Gemini عبر Puter مثل واجهة Gemini الرسمية؟

النموذج الأساسي هو Gemini، لكن طبقة الاستدعاء تمر عبر Puter. قد تختلف بعض الميزات أو الحدود حسب الدعم المتاح.

ماذا عن سياق Gemini الكبير جدًا؟

إذا كنت تحتاج إلى الوصول الكامل لسياق طويل جدًا، فاستخدم واجهة Google AI Studio الرسمية. معظم تطبيقات الدردشة والأسئلة والأجوبة لا تحتاج إلى هذا الحد.

هل يمكن استخدامه في بوت Discord أو خدمة خلفية؟

ليس بسلاسة. Puter.js يفترض وجود متصفح وجلسة مستخدم. للخدمات الخلفية، استخدم Gemini API الرسمية.

ما النموذج الافتراضي المقترح؟

ابدأ بـ google/gemini-2.5-flash. استخدم google/gemini-2.5-pro للمهام الأصعب، وgoogle/gemini-2.5-flash-lite للتصنيف عالي الحجم.

هل يدعم Puter توليد الصور عبر Imagen؟

حسب المحتوى الأصلي، Puter يعرض توليد الصور عبر gpt-image-2 ومتغيرات DALL-E من OpenAI، وليس Imagen. راجع احصل على واجهة برمجة تطبيقات GPT-5.5 مجانية وغير محدودة لمسار توليد الصور.

خاتمة

إذا كنت تريد تشغيل Gemini داخل تطبيق ويب بدون مفاتيح API أو Google Cloud أو خادم وسيط، فإن Puter.js هو أسرع مسار عملي. أضف السكريبت، اختر google/gemini-2.5-flash، ثم ابدأ بإرسال المطالبات من المتصفح.

استخدم واجهة Gemini الرسمية عندما تحتاج إلى تشغيل خلفي، ضبط دقيق، أدوات تنفيذ أكواد، أو تحكم كامل في السياق والامتثال. أما للنماذج الأولية، تطبيقات الهاكاثون، المواقع الثابتة، وتطبيقات الدردشة العامة، فـ Puter.js يقلل وقت الإعداد بشكل كبير.

قم ببناء الطلبات ومقارنتها في Apidog، ثم اختر المسار الأنسب بين Puter والنشر الرسمي عبر Gemini API.

DEV Community