كيفية اختبار مفتاح API للذكاء الاصطناعي باستخدام curl وPython

إليك كيفية اختبار وصول مفتاح API دون بناء أي شيء: ثلاث مكالمات، حوالي دقيقتين، وستعرف ما إذا كان المفتاح صالحاً، ممولاً، ومسموحاً له بتوليد النص.
نقاط رئيسية
- استدعِ GET /v1/models أولاً: يثبت أن المفتاح مقبول دون إنفاق الرصيد.
- أرسل طلب دردشة قصير واحد إلى النموذج uncensored لتأكيد أن التوليد يعمل.
- اقرأ رأس X-Balance-USD أو GET /v1/balance لمعرفة ما تبقى.
- يشير 401 إلى المفتاح، و402 إلى الرصيد، و429 إلى معدل طلبك.
اختبار الاستدعاءات الثلاث
للاختبار السليم لمفتاح API الخاص بالذكاء الاصطناعي، يجب إثبات ثلاثة أشياء منفصلة: قبول الخادم للمفتاح، وجود رصيد مرتبط به، واستلام إكمال حقيقي. يظل التشخيص بسيطاً إذا كان هناك استدعاء واحد لكل سؤال. عند الفشل، تعرف على الفور الطبقة المسؤولة.
- قائمة النماذج. يوثق المفتاح ولا يكلف شيئاً.
- إكمال المحادثة. يؤكد أن النموذج يجيب وأن تنسيق طلبك صحيح.
- الرصيد. يؤكد ما تبقى بعد الاختبار.
كل ما يلي يستخدم عنوان URL الأساسي https://api.aiapisource.com/v1 ومعرف النموذج uncensored. ضع مفتاحك في متغير بيئة حتى لا ينتهي في سجل الـ shell أو في مستودع.
export AIAPI_KEY="paste-your-key-here"
إذا لم يكن لديك مفتاح بعد، يعرض صفحة مفتاح API كيفية إنشائه. يمكن للحسابات الجديدة المطالبة برصيد تجريب بقيمة $0.50 هناك بنقرة واحدة، وهو أكثر من كافٍ لكل اختبار في هذا المقال.
الخطوة 1: سرد النماذج باستخدام curl
أرخص فحص هو طلب للقراءة فقط. يُرجع GET /v1/models قائمة النماذج ويتطلب مفتاحاً صالحاً، لذا فإن الإجابة الناجحة تثبت المصادقة.
curl -s https://api.aiapisource.com/v1/models \
-H "Authorization: Bearer $AIAPI_KEY"
الاستجابة الصحية هي JSON مع مصفوفة data تتضمن uncensored. إذا رأيت صفحة HTML أو خطأ في الاتصال أو ردًا فارغاً، فالمشكلة هي عنوان URL وليس المفتاح. تحقق من أنك أبقيت على لاحقة /v1 وأن لا يوجد مسافة لاحقة بعد المفتاح في متغيرك.
أضف -i إلى أمر curl لعرض رؤوس الاستجابة. ترسل الـ API X-Request-Id في كل طلب. احتفظ بهذه القيمة إذا اتصلت بـ الدعم، لأنها تحدد الطلب بدقة.
الخطوة 2: إرسال طلب محادثة واحد
الآن تحقق من التوليد. اجعل الـ prompt صغيراً وقم بتقييد المخرجات بحيث يكلف الاختبار جزءاً من سنت واحد.
curl -s https://api.aiapisource.com/v1/chat/completions \
-H "Authorization: Bearer $AIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Reply with the single word: ready"}],
"max_tokens": 10
}'
ابحث عن choices[0].message.content وكائن usage يحتوي على prompt_tokens و completion_tokens. طلب يتكون من حوالي 20 رمز إدخال و 5 رموز إخراج يكلف 20 / 1,000,000 x $0.15 بالإضافة إلى 5 / 1,000,000 x $0.50، وهو ما يعادل حوالي $0.0000055. يمكنك تشغيل مئة من هذه الطلبات بأقل من سنت واحد.
نقطة النهاية نفسها تعمل أيضاً للبث المتدفق: أضف "stream": true وتصل الرموز كـ أحداث مرسلة من الخادم. اختبر ذلك بشكل منفصل بمجرد أن يعمل الاستدعاء الأساسي.
الخطوة 3: نفس الاختبار بلغة Python
إذا كان كودك الحقيقي يستخدم SDK الخاص بـ OpenAI، فاختبر من خلال الـ SDK أيضاً. يلتقط المشاكل التي لن يلتقطها curl، مثل عنوان URL الأساسي الذي تم تمريره إلى وسيط خاطئ.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AIAPI_KEY"],
base_url="https://api.aiapisource.com/v1",
)
print([m.id for m in client.models.list().data])
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the single word: ready"}],
max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)
يجب أن يعرض الطبع الأول قائمة تحتوي على uncensored. يعرض الطبع الثاني رد النموذج. لمزيد من التفاصيل حول إعداد SDK، راجع دليل Python لواجهة برمجة تطبيقات OpenAI على هذا الموقع.
قم بتشغيل نسخة Python من نفس الـ shell الذي صدرت فيه المفتاح. إذا أثار خطأ KeyError على AIAPI_KEY، فهذا يعني أن المتغير غير مضبوط في تلك الجلسة، وهو السبب الأكثر شيوعاً لفشل الاختبار قبل وصوله إلى الشبكة.
يعمل Node بنفس الطريقة: مرر baseURL: "https://api.aiapisource.com/v1" والمفتاح إلى مُنشئ عميل OpenAI.
فحص الرصيد
قد يكون المفتاح صالحاً ومع ذلك لا يوجد رصيد للإنفاق. طريقتان لقراءة الرصيد:
curl -s https://api.aiapisource.com/v1/balance \
-H "Authorization: Bearer $AIAPI_KEY"
# OpenAI-style alternative
curl -s https://api.aiapisource.com/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer $AIAPI_KEY"
يحمل كل استجابة أيضًا رأس X-Balance-USD، لذا فإن مكالمة الدردشة من الخطوة 2 كانت قد أخبرتك بالفعل بالرصيد المتبقي إذا قمت بتشغيلها مع -i. في Python، يعرض SDK الخاص بـ OpenAI هذا من خلال client.chat.completions.with_raw_response.create(...)، حيث تقرأ response.headers["X-Balance-USD"].
الطلبات الفاشلة أو المرفوضة لا تُحسب، لذا فإن الاختبار الذي ينتهي بخطأ لا يستهلك الرصيد. الرصيد المسبق الدفع لا ينتهي، مما يعني أن الرصيد غير المستخدم لا يزال موجوداً الأسبوع المقبل.
قراءة رموز الخطأ
عند فشل الاختبار، يحدد رمز HTTP السبب بسرعة.
| الحالة | المعنى المعتاد | الإجراء المطلوب |
|---|---|---|
| 401 | المفتاح مفقود أو مُخطئ فيه أو مُلغى | تحقق من رأس Authorization: Bearer، انسخ المفتاح مرة أخرى، وابحث عن مسافات مخفية أو علامات اقتباس |
| 402 | لا يوجد رصيد كافٍ لدفع ثمن الطلب | اقرأ الرصيد، ثم قم بشحن الرصيد على صفحة التسعير |
| 404 | مسار خاطئ أو معرف نموذج خاطئ | استخدم /v1/chat/completions والنموذج uncensored |
| 429 | حدّ المعدل أو الطلبات المتزامنة، أو زيادة الحمل | انتظر وأعد المحاولة؛ انظر أدناه |
يحمل 429 رمز خطأ. يعني rate_limited تجاوز عدد الطلبات في الدقيقة، ويعني concurrency تجاوز عدد الطلبات المتزامنة. يسمح المفتاح الكامل بـ 300 طلب في الدقيقة و8 طلبات متزامنة؛ ويسمح المفتاح التجريبي بـ 60 طلباً في الدقيقة و2 طلب متزامن. عند الحمل الزائد المؤقت، تجيب الـ API بـ 429 مع Retry-After: 5، لذا انتظر خمس ثوانٍ وأرسل الطلب مرة أخرى. يحتفظ الطلب المتدفق بمكانه في الطلبات المتزامنة حتى انتهاء البث، وهو سبب شائع لتجاوز المفتاح التجريبي للحد أثناء الاختبارات المتزامنة.
تتبع أكواد الحالة 401 و402 و404 الاتفاقيات القياسية لواجهة برمجة التطبيقات، لذا تعامل مع الجدول كتخمين أولي واقرأ جسم الخطأ JSON للحصول على الرسالة الدقيقة.
سكربت اختبار دخان قابل لإعادة الاستخدام
بمجرد نجاح الاختبار اليدوي، احتفظ بسكربت يمكنك تشغيله بعد تدوير المفاتيح أو تغيير البيئات.
import os, sys
import requests
BASE = "https://api.aiapisource.com/v1"
H = {"Authorization": "Bearer " + os.environ["AIAPI_KEY"]}
m = requests.get(BASE + "/models", headers=H, timeout=15)
print("models", m.status_code)
c = requests.post(
BASE + "/chat/completions",
headers=H,
json={"model": "uncensored",
"messages": [{"role": "user", "content": "ping"}],
"max_tokens": 5},
timeout=60,
)
print("chat", c.status_code, "balance", c.headers.get("X-Balance-USD"))
sys.exit(0 if m.ok and c.ok else 1)
يُسهّل رمز الخروج من إدراج التحقق في النشر. بالنسبة للمعاملات التي تتجاوز هذا الحد الأدنى، يدرج مستندات API كل ما تقبله نقطة النهاية.
المزيد من الأدلة
أسئلة وأجوبة
هل يكلف اختبار مفتاح API مالاً؟
قائمة النماذج مجانية للاستدعاء. يكلف طلب دردشة قصير مع max_tokens منخفض بضعة مليونيات من الدولار بسعر $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج. لا تُحسب الطلبات الفاشلة.
كيف أختبر مفتاحاً بدون بطاقة؟
احصل على رصيد التجربة بقيمة $0.50 في صفحة مفتاح API بعد التسجيل. لا يتطلب بطاقة وهو صالح لمدة 7 أيام، لكل شخص واحد.
لماذا يعيد مفتاح صالح 429 فوراً؟
على الأرجح أنك تجاوزت حدّ الطلبات المتزامنة أو حدّ المعدل. تتيح المفاتيح التجريبية 2 طلب متزامن و60 طلب في الدقيقة؛ بينما تتيح المفاتيح الكاملة 8 و300. تحقق من رمز الخطأ، ثم قلّل السرعة أو أعد المحاولة بعد بضع ثوانٍ.
هل يمكنني اختبار المفتاح في Postman أو تطبيق آخر بدلاً من curl؟
نعم. أي عميل متوافق مع OpenAI يعمل: اضبط عنوان URL الأساسي إلى https://api.aiapisource.com/v1، وألصق المفتاح كرمز Bearer، واستخدم النموذج uncensored.
مفتاحك على بُعد استمارة واحدة
أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.