AR ▾
احصل على مفتاح API

نقطة نهاية متوافقة مع OpenAI لعملاء OpenRouter

نقطة نهاية OpenRouter المتوافقة مع OpenAI هي مجرد عنوان URL أساسي يتحدث بتنسيق دردشة OpenAI، لذا فإن استبدالها بآخر يتطلب بضعة أسطر. إليك القيم الدقيقة، وأشكال الطلب والأخطاء التي قد تواجهها.

تم التحديث

كابل واحد يربط طرفًا بنموذج متوهج، يمثل نقطة نهاية API تم استبدالها

نقاط رئيسية

  • عنوان URL الأساسي هو https://api.openrouteralternativeapi.com/v1 ومعرف النموذج هو uncensored.
  • المصادقة هي رأس Bearer قياسي؛ يوجد فقط POST /v1/chat/completions وGET /v1/models.
  • يعمل البث المتدفق، والأدوات، ووضع JSON، لكن الحقول الخاصة بالموجّه فقط غير مدعومة.
  • عند استجابة HTTP 429، اقرأ رمز الخطأ للتمييز بين حدّ المعدل وحدّ التزامن.

القيم التي تحتاجها

أي أداة تتيح لك تعديل نقطة النهاية على نمط OpenAI تحتاج إلى ثلاث قيم. انسخها من الجدول ولن يتغير شيء آخر في الإعداد النموذجي.

الإعدادالقيمة
عنوان URL الأساسيhttps://api.openrouteralternativeapi.com/v1
مفتاح APIتم الإنشاء في صفحة مفتاح API
معرّف النموذجuncensored
رأس المصادقةAuthorization: Bearer YOUR_API_KEY
مسار الدردشةPOST /v1/chat/completions
مسار قائمة النماذجGET /v1/models

ينتهي عنوان URL الأساسي بـ /v1. تقوم معظم مكتبات SDK بإلحاق /chat/completions تلقائياً، لذا لا تضيفها مرتين. بعض الأدوات تتطلب المسار الكامل للمحادثة؛ في تلك الحالة استخدم عنوان URL الأساسي متبوعاً بـ /chat/completions.

ما هي نقطة النهاية وما ليست عليه

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

الخدمة تدعم النصوص فقط. لا يتم تقديم توليد الصور أو الصوت أو الفيديو أو التضمينات (embeddings) أو ضبط الدقة (fine-tuning)، لذا سيفشل العميل الذي يستدعي /v1/embeddings أو أي مسار للصور عند استخدام نقطة الأساس هذه. وجه تلك الاستدعاءات إلى أي خدمة تستخدمها بالفعل لتلك الأغراض، واضبط نقطة الأساس لكل ميزة على حدة بدلاً من ضبطها عالمياً إذا كان تطبيقك يخلط بين عدة خدمات.

نقطة توافق إضافية تتعلق بقائمة النماذج. العميل الذي يستدعي GET /v1/models عند بدء التشغيل، لملء قائمة منسدلة أو للتحقق من إعداد، سيحصل على النموذج الوحيد. هذا متوقع. إذا كان الكود الخاص بك يتحقق من ظهور اسم النموذج المكون في القائمة، اضبط الاسم إلى uncensored وستنجح الفحص. إذا كان تطبيقك يحدد اسم نموذج لمورد معين في مكان عميق في ملف الإعداد، ابحث في المستودع عنه قبل التشغيل الأول، لأن السلسلة المتبقية هي السبب الأكثر شيوعاً لفشل التطبيق المهاجر بعد تغيير نقطة النهاية.

الطلب الأول، بثلاث طرق

ابدأ بطلب من الطرفية. هذا يثبت صحة المفتاح، نقطة النهاية ومعرف النموذج قبل أي إطار عمل.

curl https://api.openrouteralternativeapi.com/v1/models   -H "Authorization: Bearer $API_KEY"

curl https://api.openrouteralternativeapi.com/v1/chat/completions   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 10
  }'

نفس الاستدعاء مع مجموعة أدوات Python SDK. لاحظ أن لا شيء يختلف عن كود OpenAI الأصلي سوى base_url و api_key.

from openai import OpenAI

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

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with the word ready."}],
    max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)

و مع Node، قراءة المفتاح من متغير البيئة:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openrouteralternativeapi.com/v1",
  apiKey: process.env.API_KEY,
});

const r = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Reply with the word ready." }],
  max_tokens: 10,
});
console.log(r.choices[0].message.content);

تقرأ العديد من الأدوات متغيرات البيئة بدلاً من حجج البناء. تحترم مكتبات SDK الرسمية عادةً OPENAI_BASE_URL و OPENAI_API_KEY، مما يتيح لك إعادة توجيه سكريبت غير معدل. تحقق من وثائق إصدار SDK الخاص بك لتأكيد الأسماء.

البث المتدفق، الأدوات ووضع JSON

الميزات التي يعتمد عليها معظم العملاء موجودة. اضبط stream: true لتلقي أحداث البث المتدفق؛ يتم الإبلاغ عن الاستخدام في نهاية البث. يدعم استدعاء الأدوات tools و tool_choice، ويبث أجزاء (deltas) من tool_calls، ويتوقع النتائج كرسائل بـ role: "tool". تم تمكين وضع JSON مع response_format: {"type":"json_object"}. يتم تمرير حقول أخذ العينات temperature، top_p، stop، seed وعقوبات التكرار والوجود كما هي.

مثال للبث المتدفق في Python:

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write three short taglines for a coffee cart."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

ووضع JSON، والذي يستحق الاقتران بتوجيه في الموجّه يحدد المفاتيح التي تتوقعها:

r = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Return JSON with keys title and tags (array of strings)."},
        {"role": "user", "content": "Summarise: a guide to brewing cold coffee at home."},
    ],
    response_format={"type": "json_object"},
)
print(r.choices[0].message.content)

قم دائماً بتحليل النتيجة في كتلة try. وضع JSON يزيد من احتمالات الإخراج الصحيح، لكن يجب أن يتعامل الكود الخاص بك مع رد غير صالح، على سبيل المثال عن طريق إعادة المحاولة مرة واحدة.

الدردشات متعددة الجولات واستدعاءات الأدوات

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

history = [{"role": "system", "content": "You answer in two sentences."}]

def chat(text):
    history.append({"role": "user", "content": text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

لاستدعاء الأدوات، صف دوالك في tools، نفذ ما يطلبه النموذج، وأرسل المخرجات كرسالة role: "tool" تحمل tool_call_id المطابق. تعريف بسيط يبدو هكذا:

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by its number",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Where is order 1042?"}],
    tools=tools,
    tool_choice="auto",
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

تحقق من الحجج قبل تنفيذ أي شيء. يقترح النموذج استدعاءً؛ يقرر الكود الخاص بك ما إذا كان آمناً للتنفيذ، خاصة عندما تلمس الدالة المال أو الملفات أو بيانات الآخرين.

الحقول المراد إزالتها من طلبات على نمط OpenRouter

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

  • استبدل أي معرف نموذج (model ID) يتضمن بادئة مزود بـ uncensored.
  • تجاهل قوائم التراجع. إذا كان النموذج الوحيد غير متاح، فقم بمعالجته في منطق إعادة المحاولة الخاص بك.
  • لا ترسل أجزاء من الصور أو الصوت. يقرأ النموذج النص فقط.
  • حافظ على إجمالي جسم الطلب أقل من 8 MB.

تُظهر صفحة التوثيق المعلمات المدعومة، وهي المكان الذي يجب التحقق منه عندما يتصرف حقل بشكل مختلف عما يتوقعه العميل الخاص بك.

الحدود واستجابات 429

يتيح المفتاح الكامل 8 طلبات متزامنة و300 طلب في الدقيقة؛ ويتيح مفتاح التجربة 2 و60. تحمل كل استجابة X-Request-Id، وX-Balance-USD، وX-RateLimit-Limit-Requests، وX-RateLimit-Limit-Concurrency. سجّل معرف الطلب مع كل فشل، لأنه أول شيء تطلبه خدمة الدعم.

هناك ثلاثة أنواع من أخطاء HTTP 429. يعني رمز الخطأ rate_limited أنك تجاوزت الحد الأقصى للطلبات في الدقيقة: أبطئ. يعني الرمز concurrency أن هناك طلبات كثيرة قيد التنفيذ في آن واحد: قم بترتيبها في طابور. يشير 429 مع رأس Retry-After: 5 إلى زيادة مؤقتة في الحمل: انتظر خمس ثوانٍ وحاول مرة أخرى. تذكر أن الطلب المبعث (streamed) يحتفظ بمكانه في الـ concurrency حتى ينتهي البث، لذا فإن العميل العالق الذي لا يقرأ حتى النهاية سيستهلك السعة.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openrouteralternativeapi.com/v1",
    api_key="YOUR_API_KEY",
    max_retries=0,
)

def ask(prompt, tries=4):
    for i in range(tries):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = 5 if i == 0 else 5 * (i + 1)
            time.sleep(wait)
    raise RuntimeError("still rate limited")

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

فحص التكلفة قبل توجيه الإنتاج إليها

التسعير هو $0.15 لكل مليون رمز إدخال و $0.50 لكل مليون رمز إخراج من الرصيد المسبق الدفع. خذ طلباً يحتوي على 2,000 رمز إدخال و 500 رمز إخراج. تكلفة الإدخال هي 2,000 / 1,000,000 x $0.15 = $0.0003. تكلفة الإخراج هي 500 / 1,000,000 x $0.50 = $0.00025. تكلفة الطلب هي $0.00055، لذا فإن 1,000 طلب من هذا النوع تكلف $0.55. الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها. انظر صفحة التسعير لمبالغ الشحن والمكافآت؛ رصيد التجربة المجاني بقيمة $0.50 يغطي حوالي 900 طلب من هذا الحجم (0.50 / 0.00055).

أسئلة وأجوبة

ما هو عنوان URL الأساسي لنقطة النهاية المتوافقة مع OpenAI؟

استخدم https://api.openrouteralternativeapi.com/v1 كعنوان URL أساسي وأرسل مفتاحك كرمز Bearer. معرف النموذج هو uncensored.

ما هي المسارات المتاحة؟

POST /v1/chat/completings للتوليد و GET /v1/models لقائمة النماذج. لا توجد مسارات للـ embeddings أو الصور أو الصوت أو ضبط الدقة (fine-tuning).

هل أحتاج إلى تغيير الكود الخاص بي بخلاف URL والمفتاح؟

عادةً فقط سلسلة النموذج. أزل الحقول الخاصة بـ router مثل تفضيلات المزوّد أو قوائم التراجع من جسم الطلب.

لماذا أحصل على HTTP 429؟

تحقق من رمز الخطأ. يعني rate_limited تجاوز عدد الطلبات المسموح به في الدقيقة، ويعني concurrency تجاوز الحد الأقصى للطلبات المتزامنة، ويشير رأس Retry-After: 5 إلى زيادة مؤقتة في الحمل.

مفتاحك يحتاج إلى استمارة واحدة فقط

أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.