كيفية استخدام واجهة Groq API مجانًا

يمنح Groq كل حساب ضمن الخطة المجانية مفتاحًا للوصول إلى نقطة نهايته المتوافقة مع OpenAI، وهذا المفتاح يعمل بمجرد التسجيل. الجزء الذي يربك الناس ليس الحصول على الوصول، بل البقاء داخل الحدود بمجرد أن يتصل تطبيقك بالنموذج فعليًا. تنشر Groq أرقام الخطة المجانية لكل نموذج في وثائقها، لكن تلك الأرقام تتغير ويمكن أن تختلف من حساب لآخر. العادة الموثوقة هي التحقق من إعدادات حسابك، ثم قراءة رؤوس الاستجابة في كل استدعاء، لأن الحدود قد تتغير أثناء الجلسة.

جرّب Apidog اليوم

يغطي هذا الدليل الحصول على مفتاح، وتوجيه عميل OpenAI قياسي إلى نقطة نهاية Groq، والجزء الذي تتخطاه معظم منشورات «الطبقة المجانية»: مراقبة حدودك في الوقت الفعلي بدلًا من اكتشافها من خطأ 429 في الإنتاج. ثم يحوّل وكيل البرمجة لديك هذا الفحص إلى اختبار Apidog CLI، ليكون قابلًا للتكرار، وليس أمر curl لمرة واحدة تنساه.

باختصار

تشغّل Groq طبقتين: الخطة المجانية وخطة المطور. تنطبق حدود المعدل على مستوى المؤسسة (وليس لكل مستخدم)، وتصطدم بأي سقف يأتي أولًا من بين الطلبات أو الرموز أو الإجماليات اليومية، ولا تُحتسب الرموز المخزنة مؤقتًا ضدك. تنشر Groq أرقام الخطة المجانية لكل نموذج، لكن الأرقام التي تنطبق على حسابك موجودة على صفحة الحدود في وحدة التحكم لديك، لذا الخطوة الموثوقة هي قراءتها من رؤوس الاستجابة x-ratelimit-* في كل استدعاء بدلًا من الوثوق بجدول قد يتغير دون إشعار.

الحصول على مفتاح واستدعاء نقطة النهاية

أنشئ حسابًا على console.groq.com وأنشئ مفتاحًا من صفحة المفاتيح. تكشف Groq عن هذا المفتاح عبر واجهة برمجة تطبيقات متوافقة مع OpenAI، لذا إذا سبق أن استدعيت SDK الخاصة بـ OpenAI، فأنت تعرف الشكل بالفعل. وجّه عنوان URL الأساسي إلى Groq بدلًا من OpenAI وأبقِ كل شيء آخر كما هو:

curl https://api.groq.com/openai/v1/chat/completions \ -H "Authorization: Bearer $GROQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "llama-3.1-8b-instant", "messages": [{"role": "user", "content": "Summarize this ticket in one sentence."}] }' 

أو باستخدام عميل Python الرسمي من OpenAI:

import os from openai import OpenAI client = OpenAI( [REDACTED CREDENTIAL]_API_KEY"], base_url="https://api.groq.com/openai/v1", ) response = client.chat.completions.create( model="llama-3.3-70b-versatile", messages=[{"role": "user", "content": "List three causes of API timeout errors."}], ) print(response.choices[0].message.content) 

تشير وثائق التوافق مع OpenAI من Groq إلى بعض الفجوات التي يستحسن معرفتها قبل نسخ الكود الحالي: logprobs وlogit_bias وtop_logprobs وmessages[].name كلها تُرجع خطأ 400، ويجب أن يساوي n القيمة 1 إذا قمت بتعيينه، وتُحوَّل درجة الحرارة 0 إلى عدد عشري موجب صغير جدًا بدلًا من فك ترميز جشع حقيقي.

الخطة المجانية مقابل خطة المطور

صياغة Groq نفسها مباشرة: «قم بالترقية إلى خطة المطور للوصول إلى حدود أعلى، ومعالجة Batch وFlex، والمزيد.» الخطة المجانية هي ما يبدأ عليه كل مفتاح جديد، وهي قابلة للاستخدام فعلًا للاختبار والمشاريع الجانبية الصغيرة.

إليك ما تسمح به الخطة المجانية لبعض النماذج، وفقًا لوثائق حدود المعدل من Groq كما قُرئت في 2026-09-15:

تحتوي الصفحة نفسها على تبويب خطة المطور بحدود أعلى لكل نموذج، بالإضافة إلى معالجة Batch وFlex. تعامل مع الجدول أعلاه كلقطة سريعة، لأن Groq يمكنها تغيير هذه الأرقام دون إشعار. أرقامك الخاصة موجودة على صفحة الحدود في إعدادات حسابك: ثق بتلك الصفحة أكثر من هذه إذا اختلفتا.

هناك تفصيلان في السياسة يهمان أكثر من الأرقام الخام. تنطبق حدود المعدل «على مستوى المؤسسة، وليس المستخدمين الأفراد»، لذا خمسة أشخاص يتشاركون مؤسسة Groq واحدة يتشاركون حدًا واحدًا، وليس خمسة حدود منفصلة. كما أن «الرموز المخزنة مؤقتًا لا تُحتسب ضمن حدود المعدل لديك»، ما يعني أن بنية موجّه جيدة التخزين المؤقت تمنحك إنتاجية فعلية أكبر مما يوحي به الرقم الرئيسي.

نماذج يستحسن معرفتها قبل أن تصل إلى الحد

يعتمد الحد المهم على النموذج الذي تستدعيه. تعمل نماذج النصوص وأنظمة Compound من Groq بسياق 131,072 رمزًا:

لا تندرج نماذج Whisper، وهما whisper-large-v3 وwhisper-large-v3-turbo، في هذا الجدول. فهي نماذج نسخ صوتي، وتقيس Groq إنتاجيتها بالثواني الصوتية في الساعة واليوم (ASH/ASD) إلى جانب حدود RPM وRPD الخاصة بها، وليس بالرموز.

لكل نموذج حدود RPM وRPD ورموز خاصة به، لذا لا تفترض أن حدود llama-3.1-8b-instant تنطبق على openai/gpt-oss-120b.

اقرأ رؤوس حدود المعدل بدلًا من التخمين

تحمل كل استجابة من api.groq.com مجموعة رؤوس تخبرك بالضبط أين تقف، دون حاجة لزيارة وحدة التحكم:

• x-ratelimit-limit-requests وx-ratelimit-limit-tokens، سقفك للنافذة الحالية
• x-ratelimit-remaining-requests وx-ratelimit-remaining-tokens، ما تبقى الآن
• x-ratelimit-reset-requests وx-ratelimit-reset-tokens، متى تُحدَّث النافذة
• retry-after، يُرسل عند خطأ 429، ويخبرك كم يجب الانتظار

اقرأ x-ratelimit-remaining-tokens بعد كل استدعاء وستحصل على مقياس حي، وليس رقمًا ثابتًا بحثت عنه مرة ونسيت مراجعته. إليك فحصًا سريعًا باستخدام cURL، يطبع الرؤوس فقط:

curl -sD - https://api.groq.com/openai/v1/chat/completions \ -H "Authorization: Bearer $GROQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "llama-3.1-8b-instant", "messages": [{"role": "user", "content": "hi"}]}' \ -o /dev/null | grep -i ratelimit 

شغّل ذلك عدة مرات في حلقة ضد نص اختبار كثير الطلبات وستشاهد x-ratelimit-remaining-tokens ينخفض. إذا احتاج تطبيقك يومًا إلى منطق تراجع، فراجع دليلنا حول كيفية تنفيذ تحديد معدل API لأنماط تحترم رأس retry-after بدلًا من تخمين مدة انتظار.

دع وكيل البرمجة لديك ينفذ الفحص باستخدام Apidog CLI

القيام برقصة curl-and-grep يدويًا ينجح لجلسة تصحيح واحدة. لكنه لا يتوسع لفريق، ولا أحد يعيد تشغيل أمر shell لمرة واحدة قبل كل نشر. سلّم الفحص إلى وكيل البرمجة لديك بدلًا من ذلك: مع 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 

يأتي الرمز المميز من Apidog ضمن إعدادات الحساب، API Access Token. ثم أعطِ الوكيل موجّهًا واحدًا:

Use Apidog CLI on project <id>. Create a Groq environment with base URL https://api.groq.com/openai/v1 and add POST /chat/completions with Bearer [REDACTED] from {{GROQ_API_KEY}}. Create one test case per model we run in production (llama-3.1-8b-instant, openai/gpt-oss-120b) that asserts status 200 and fails when x-ratelimit-remaining-tokens drops below 10% of x-ratelimit-limit-tokens. Put both cases in a "Groq limits" test suite, run it, and report the headers. 

الأوامر التي يشغّلها، متحقَّق منها مقابل Apidog CLI 2.2.7:

apidog environment create Groq --project <id> --base-url https://api.groq.com/openai/v1 apidog endpoint create --project <id> --file groq-chat.json apidog cli-schema validate test-case-create --file groq-8b-case.json apidog test-case create --project <id> --file groq-8b-case.json apidog test-suite create --project <id> --name "Groq limits" apidog run --test-suite <suiteId> --project <id> -e <envId> \ --env-var "GROQ_API_KEY=$GROQ_API_KEY" -r cli,junit 

تظهر الميزانية المتقلصة الآن كاختبار فاشل بدلًا من خطأ 429 مفاجئ أثناء عرض توضيحي. ضع السطر الأخير في مهمة CI قبل النشر، كما في دليلنا حول خط أنابيب CI/CD الخاص بـ Apidog CLI، أو اطلب من الوكيل تنفيذ apidog scheduled-task create، الذي يشغّل المجموعة على runner وفق cron. يهم هذا أكثر نظرًا لتجميع Groq على مستوى المؤسسة: زميل واحد يشغّل مهمة دفعية يمكن أن يستهلك الميزانية المشتركة التي تحتاجها نقطة نهاية الإنتاج لديك بعد ساعة. إنها الفكرة نفسها وراء منشورنا حول اختبار API لحدود معدل GPT.

ماذا تفعل عندما تصل فعليًا إلى الحد

عندما يعود خطأ 429، احترم retry-after بدلًا من إعادة المحاولة فورًا. حلقة إعادة محاولة ضيقة ضد حد على مستوى الطلب تستهلك فقط ميزانيتك المتبقية بسرعة أكبر وتدفع نافذة إعادة الضبط إلى أبعد. إذا كنت تبني هذا في خدمة إنتاج بدلًا من نص اختبار، فإن دليلنا الكامل لخطأ تجاوز حد المعدل يستعرض استراتيجيات تراجع تعمل عبر مزوّدين مختلفين، وليس Groq فقط.

إذا كنت تصطدم باستمرار بالسقف في الخطة المجانية، فأسرع حل هو الترقية إلى خطة المطور التي تشير إليها Groq مباشرة في وثائقها. ثاني أسرع حل، خاصة لنموذج أولي، هو توزيع الحركة على أكثر من مزوّد. تغطي مجموعتنا حول بدائل OpenRouter نقاط نهاية أخرى يستحسن الاحتفاظ بها في جعبتك لهذا الموقف تحديدًا.

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

هل لدى Groq طبقة مجانية لواجهة API الخاصة بها؟ نعم. يبدأ كل حساب جديد على الخطة المجانية مع الوصول إلى نقطة النهاية المتوافقة مع OpenAI. تنشر Groq أمثلة على حدود الخطة المجانية لعدة نماذج، لكن السقوف التي تنطبق فعليًا على حسابك موجودة على صفحة الحدود في إعدادات وحدة التحكم لديك.

كيف أتحقق من حد معدل Groq الحالي لدي؟ بطريقتين: افتح صفحة الحدود في إعدادات حسابك، أو اقرأ رؤوس x-ratelimit-limit-requests وx-ratelimit-limit-tokens في أي استجابة API. تعكس الرؤوس الحد الحقيقي لحسابك في لحظة استدعائك، وهذا أكثر موثوقية من رقم رأيته مرة وتذكرته.

ماذا يحدث عندما أتجاوز حد معدل Groq؟ تحصل على استجابة 429 مع رأس retry-after يخبرك بعدد الثواني التي يجب انتظارها. راجع دليل تجاوز حد المعدل للتعامل مع هذا في الكود بدلًا من تخمين مدة انتظار.

هل تُحتسب الرموز المخزنة مؤقتًا ضمن حد معدل Groq لدي؟ لا. تذكر Groq مباشرة أن الرموز المخزنة مؤقتًا لا تُحتسب ضمن حدود المعدل لديك، لذا بنية موجّه تعيد استخدام رسالة نظام مخزنة مؤقتًا تحصل على إنتاجية فعلية أكبر مما يوحي به حد الرموز الخام.

هل حد معدل Groq لكل مستخدم أم لكل مؤسسة؟ لكل مؤسسة. كل مفتاح تحت مؤسسة Groq نفسها يتشارك مجموعة واحدة من الطلبات والرموز، لذا يمكن لنص زميل أن يأكل من الميزانية التي يحتاجها تطبيقك الإنتاجي.

أي نماذج Groq لديها أكبر نافذة سياق؟ يعمل llama-3.1-8b-instant وllama-3.3-70b-versatile وopenai/gpt-oss-120b وopenai/gpt-oss-20b وأنظمة Compound جميعها بسياق 131,072 رمزًا. نماذج Whisper هي نسخ صوتي، وليست نصًا، لذا تقيس Groq حدودها بمدة الصوت بدلًا من ذلك. تختلف حدود المعدل من نموذج لآخر حتى ضمن نافذة السياق نفسها، لذا تحقق من كل واحد على حدة.

إلى أين يتركك هذا

الطريقة المجانية لاستخدام Groq API ليست رقمًا سريًا، بل عادة. احصل على مفتاح، ووجّه نقطة النهاية المتوافقة مع OpenAI إليه، واقرأ رؤوس الاستجابة في كل استدعاء بدلًا من الوثوق برقم وجدته في منشور مدونة، بما في ذلك هذا المنشور.

اجعل وكيل البرمجة لديك يبني هذا الفحص مرة واحدة باستخدام Apidog CLI، مع تأكيد على الرموز المتبقية لكل نموذج، وسيعمل في كل عملية نشر من ذلك الحين. يستغرق الإعداد وقتًا أقل من قراءة بقية وثائق Groq. لتغطية أعمق لاختبار طبقة API ذكاء اصطناعي تحت الحمل، فإن دليلنا حول أفضل أدوات اختبار API لوكلاء الذكاء الاصطناعي هو محطة تالية جيدة.