مفتاح Codex API، مُشرَح للمطوِّرين

فهم تنسيق مفتاح API

عند تسجيل حسابك في خدمة توفر codex api key، تتلقى سلسلة فريدة من الأحرف والأرقام. يعمل هذا المفتاح كجواز مصادقة لكل طلب تُرسله إلى الخادم الخلفي. عادةً ما يتبع التنسيق نمطاً قياسياً، مثل sk-... أو بادئات مشابهة، اعتماداً على تنفيذ المزوّد. ومع ذلك، بما أنك تستخدم وسيطاً مستقلاً، فقد تختلف البادئة الدقيقة. العامل الحاسم ليس التنسيق نفسه، بل ضمان تمرير المفتاح بشكل صحيح في رأس HTTP Authorization بصيغة Bearer <your_key>.

مفتاح API الخاص بك مرتبط بحساب معين وطبقة استخدام محددة. على عكس بعض الخدمات التي تولد مفاتيح متعددة لبيئات مختلفة (dev مقابل prod)، فإن إعدادنا مباشر: حساب واحد، مفتاح واحد. إذا فقدت مفتاحك أو اشتبهت في تعرضه للاختراق، يمكنك إعادة إنشائه فورًا من لوحة التحكم. يؤدي ذلك إلى إلغاء سريان المفتاح القديم على الفور، مما يضمن عدم استمرار الوصول غير المصرح به. تذكر تحديث متغيرات البيئة أو ملفات التكوين كلما قمت بتدوير المفاتيح.

أفضل ممارسات الأمان

• احفظ مفتاحك في متغيرات البيئة، وليس في رمز المصدر الخاص بك.
• لا تقم أبداً بإدراج codex api key الخاص بك في المستودعات العامة.
• استخدم وظيفة إعادة الإنشاء إذا اشتبهت في التعرض.

خطأ شائع: 401 غير مصرح

يُعد خطأ 401 غير مصرح به أكثر المشكلات شيوعًا عند دمج مفتاح API جديد. يشير هذا إلى أن الخادم رفض بيانات الاعتماد الخاصة بالمصادقة. في سياق claude code proxy أو أي نقطة نهاية متوافقة مع OpenAI، يعني هذا تقريبًا دائمًا أن المفتاح مفقود أو غير صحيح أو منتهي الصلاحية.

لحل المشكلات، تحقق أولاً من أنك تنسخ المفتاح بالضبط كما هو مقدم. غالبًا ما تكون المفاتيح حساسة لحالة الأحرف وقد تحتوي على مسافات إذا تم نسخها بشكل غير صحيح. تأكد من استخدام عنوان URL الأساسي الصحيح لمنطقتك أو طبقة الخدمة. إذا قمت مؤخرًا بإعادة إنشاء مفتاحك، فتأكد من أن عميلك يستخدم القيمة الجديدة. خطأ 401 لا علاقة له برصيد الاستخدام أو حدود المعدل؛ إنه فشل مصادقة بحت.

قائمة مراجعة للحل

1. تأكد من مطابقة سلسلة مفتاح API للوحة التحكم بالضبط.
2. تحقق من تنسيق رأس المصادقة: Authorization: Bearer YOUR_KEY.
3. تحقق من صحة عنوان URL الأساسي لنوع حسابك.
4. تأكد من عدم إضافة مسافات بيضاء زائدة أثناء النسخ واللصق.

تم تجاوز حدّ المعدل: أخطاء 429

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

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

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

تكوين عنوان URL الأساسي بشكل صحيح

عنوان URL الأساسي هو أساس أي تكامل API. بالنسبة لخدمة متوافقة مع OpenAI، يحدد عنوان URL الأساسي مكان إرسال طلباتك. عنوان URL الأساسي الخاص بنا هو https://api.claudecodeapikey.com/v1. يجب تكوين هذا العنوان في مكتبة العميل أو SDK الخاص بك قبل إرسال أي طلبات. إذا استخدمت عنوان URL الأساسي الخاطئ، فستحصل على أخطاء اتصال أو استجابات غير متوقعة.

يستخدم العديد من المطورين مكتبة SDK الرسمية من OpenAI لـ Python أو Node.js أو لغات أخرى. للتبديل إلى الوكيل الخاص بنا، قم ببساطة بتحديث تكوين عنوان URL الأساسي. على سبيل المثال، في Python، قد تضبط base_url='https://api.claudecodeapikey.com/v1'. تأكد من صحة البروتوكول (https) والمسار (/v1). يعد حذف مسار /v1 خطأً شائعًا يؤدي إلى أخطاء 404.

تحقق دائمًا من إرسال العميل الخاص بك للطلبات إلى نقطة النهاية الصحيحة. يمكنك القيام بذلك عن طريق التحقق من سجلات الشبكة أو باستخدام أداة مثل curl لاختبار الاتصال. يؤكد الاتصال الناجح بعنوان URL الأساسي أن تكوينك صحيح.

معالجة استجابات البث المتدفق

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

لتمكين البث المتدفق، اضبط المعلمة stream على true في طلبك. ستتعامل مكتبة العميل بعد ذلك مع بروتوكول SSE تلقائيًا. يمكنك معالجة كل شريحة عند وصولها، وتحديث واجهة المستخدم الخاصة بك أو تسجيل التقدم. يوفر هذا تجربة مستخدم أفضل، خاصة لتوليد الرمز الطويل.

لا يغير البث المتدفق النموذج الأساسي أو قدراته. إنه مجرد آلية نقل. لا يزال النموذج يعالج الموجّه بالكامل ويولّد الاستجابة الكاملة؛ والفرق يكمن في كيفية تسليم المخرجات إلى العميل الخاص بك.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.claudecodeapikey.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

مشكلات تكوين استدعاء الأداة

يسمح استدعاء الأداة (أو استدعاء الدالة) لنموذج اللغة الكبير بطلب إجراءات محددة، مثل تشغيل مقتطف رمز أو استعلام قاعدة بيانات. تدعم الـ API الخاصة بنا استدعاء الأداة، مما يعني أنه يمكنك تعريف الدوال في طلبك والحصول على استجابات JSON هيكلية من النموذج. يعد هذا أمرًا أساسيًا لوكلاء البرمجة المتقدمة الذين يحتاجون إلى التفاعل مع الأنظمة الخارجية.

لتكوين استدعاء الأداة، يجب أن توفر قائمة بتعريفات الدوال في المعلمة tools. يجب أن تحتوي كل أداة على اسم ووصف ومخطط المعلمات. سيقرر النموذج بعد ذلك متى يستدعي أداة بناءً على الموجّه. إذا قرر النموذج استدعاء أداة، فستتضمن الاستجابة مصفوفة tool_calls مع اسم الدلة والحجج.

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

حدود نافذة السياق

تحدد نافذة السياق الحد الأقصى لكمية النص التي يمكن للنموذج معالجتها في طلب واحد، بما في ذلك كل من الموجّه (الإدخال) والإكمال (الإخراج). لدى نموذجنا نافذة سياق تتكون من 100,000 رمز (token). هذه كمية كبيرة من النص، لكنها ليست لا نهائية. إذا تجاوز مجموع الموجّه والإخراج المتوقع هذا الحد، ستعيد الـ API خطأ.

لإدارة السياق بكفاءة، راقب استخدام الرموز (token) لموجّهاتك. يمكن للملفات الطويلة أو سجلات المحادثات الموسعة استهلاك الرموز المتاحة بسرعة. إذا اقتربت من الحد، فكر في اختصار الرسائل الأقدم أو تلخيص التفاعلات السابقة. تتعامل بعض العملاء تلقائيًا مع هذا عن طريق انزلاق النافذة، لكن من الأفضل أن تكون على علم بالحد لتجنب الأخطاء غير المتوقعة.

تذكر أن نافذة السياق تشمل جميع الرموز (token) المرسلة إلى النموذج، بما في ذلك رسائل النظام ورسائل المستخدم ورسائل المساعد. خطط لميزانية الرموز الخاصة بك وفقًا لذلك لضمان التشغيل السلس أثناء جلسات البرمجة الطويلة.

إعادة إنشاء مفتاحك

يُعدّ إعادة توليد مفتاح API عملية بسيطة تضمن الأمان. إذا كنت تشك في أن مفتاحك قد تعرض للخطر أو ترغب في تجديد بيانات الاعتماد بشكل دوري، يمكنك إنشاء مفتاح جديد من لوحة التحكم. يتم إبطال المفتاح القديم فوراً، لذا ستفشل أي طلبات جارية تستخدم المفتاح القديم.

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

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

Copycurl https://api.claudecodeapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'