الانتقال من OpenRouter يكلّفك سطرًا واحدًا

غيّر عنوان base URL وضع مفتاح OrcaRouter. أما نماذجك و SDK وبقية شيفرتك فتبقى كما هي تمامًا — وما يُعاد تسميته هو معرّفات الموجِّهات ⁨openrouter/⁩ وحدها.

ثلاثة أمور للتحقق منها

1. استخدم base URL الصحيح لـ SDK لديك — يتطلب SDK الخاص بـ OpenAI العنوان ⁨https://api.orcarouter.ai/v1⁩، أما الاثنان الآخران فيكفيهما ⁨https://api.orcarouter.ai⁩، إذ يضيف كلٌّ منهما مساره بنفسه.
2. استبدل مفتاح API بمفتاح OrcaRouter الخاص بك — القيمة تتغيّر — مفتاح OpenRouter لا يُصادَق عليه هنا — أما الموضع فلا يتغيّر: نقرأ الترويسة نفسها التي ترسلها حزمة التطوير لديك بالفعل.
3. احتفظ بأسماء نماذجك — نستخدم صيغة التسمية نفسها ⁨vendor/model⁩، لذا يعمل ⁨anthropic/claude-sonnet-4⁩ كما هو. والاستثناء هو معرّفات موجِّهات OpenRouter نفسها التي تبدأ بـ ⁨openrouter/⁩، فهذه يُعاد تسميتها.

قبل وبعد: السطر الذي يتغيّر

يتعامل OrcaRouter مع واجهات OpenAI وAnthropic وGemini مباشرةً، لذا تحتفظ بـ SDK الذي تستخدمه أصلًا. في كل مقتطف، الأسطر التي تبدأ بـ ⁨-⁩ هي ما تحذفه، والأسطر التي تبدأ بـ ⁨+⁩ هي ما تضيفه.

OpenAI — Python

  client = OpenAI(
-     base_url="https://openrouter.ai/api/v1",
+     base_url="https://api.orcarouter.ai/v1",
      api_key=ORCAROUTER_API_KEY,
  )

هذا هو التغيير الوحيد في الشيفرة. وضَع أيضًا مفتاح OrcaRouter — أسماء نماذجك ورسائلك والبثّ تبقى كما هي، ما لم تستدعِ معرّف موجِّه يبدأ بـ ⁨openrouter/⁩.

Anthropic — Python

  client = Anthropic(
+     base_url="https://api.orcarouter.ai",
      api_key=ORCAROUTER_API_KEY,
  )

نحن ندعم واجهة Anthropic مباشرةً، وهو ما لا يوفّره OpenRouter. فإن كنت تستدعي Claude عبر SDK الخاص بـ OpenAI لمجاراة OpenRouter، فلم تعد بحاجة إلى ذلك.

Gemini — TypeScript

  const ai = new GoogleGenAI({
    apiKey: ORCAROUTER_API_KEY,
+   httpOptions: { baseUrl: "https://api.orcarouter.ai" },
  });

وندعم كذلك واجهة Gemini مباشرةً، لذا يعمل SDK من Google دون أي تعديل.

أمثلة كاملة لكل SDK

يشمل الاستيراد وتهيئة العميل واستدعاءً حقيقيًا واحدًا. يعمل كما هو بمجرّد ضبط ORCAROUTER_API_KEY في بيئتك.

OpenAI — Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.orcarouter.ai/v1",
    api_key=os.environ["ORCAROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

OpenAI — TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.orcarouter.ai/v1",
  apiKey: process.env.ORCAROUTER_API_KEY,
});

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

OpenAI — cURL

curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $ORCAROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Anthropic — Python

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.orcarouter.ai",
    api_key=os.environ["ORCAROUTER_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-sonnet-4",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)

Anthropic — TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.orcarouter.ai",
  apiKey: process.env.ORCAROUTER_API_KEY,
});

const message = await client.messages.create({
  model: "anthropic/claude-sonnet-4",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content[0].text);

Anthropic — cURL

curl https://api.orcarouter.ai/v1/messages \
  -H "x-api-key: $ORCAROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Gemini — Python

import os
from google import genai

client = genai.Client(
    api_key=os.environ["ORCAROUTER_API_KEY"],
    http_options={"base_url": "https://api.orcarouter.ai"},
)

response = client.models.generate_content(
    model="google/gemini-2.5-pro",
    contents="Hello",
)
print(response.text)

Gemini — TypeScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.ORCAROUTER_API_KEY,
  httpOptions: { baseUrl: "https://api.orcarouter.ai" },
});

const response = await ai.models.generateContent({
  model: "google/gemini-2.5-pro",
  contents: "Hello",
});
console.log(response.text);

Gemini — cURL

curl "https://api.orcarouter.ai/v1beta/models/google/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $ORCAROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'

معرّفات النماذج: ما الذي تُعيد تسميته

نستخدم صيغة التسمية نفسها ⁨vendor/model⁩، لذا يعمل ⁨anthropic/claude-sonnet-4⁩ كما هو. والاستثناء هو معرّفات موجِّهات OpenRouter نفسها التي تبدأ بـ ⁨openrouter/⁩، فهذه يُعاد تسميتها.

الفروق في الفوترة

• تُحتسب الرموز (tokens) بسعر القائمة الخاص بكل مزوّد دون أي هامش من OrcaRouter — فالمنصة تموَّل من الباقات، لا من فرق سعر على حركة طلباتك.
• نفس نقطة النهاية — اقرأ المعرّف من ترويسة الاستجابة. استدعِ ‎⁨/v1/generation⁩ تمامًا كما تفعل اليوم. الفارق الوحيد هو مصدر المعرّف: ترويسة الاستجابة X-Orca-Request-Id بدلًا من المعرّف الموجود في متن الاستجابة.
• تحصل على المبلغ المحتسب فعليًا مع أعداد الرموز التي استند إليها. وقد يعني الرمز 404 أنّ الطلب لم تكتمل تسويته بعد، فأعد الاستعلام بضع مرّات خلال ثوانٍ قليلة ثم توقّف — وقد يعني كذلك أنّ المعرّف غير معروف، أو أنّه يخصّ مفتاحًا آخر، أو أنّ الطلب أخفق وهذا التنصيب لا يسجّل الطلبات المخفقة. أمّا الرمز 501 فيعني أنّ الاستعلام عن التكلفة معطَّل في هذا التنصيب؛ والطلبات التي سُوِّيت وهو مفعَّل تبقى قابلة للقراءة.
• لا توجد نقطة نهاية للرصيد. تكلفة كل طلب تعود إليك من الواجهة، أما رصيدك الإجمالي فتجده في لوحة التحكم.

أربعة أمور لا نقوم بها

أن تعرف الآن خير من أن تكتشف ذلك في بيئة التشغيل.

• إخبارك بالمزوّد الذي خدم الطلب — من جهتك، OrcaRouter مزوّد واحد. ولا يوجد حقل provider في الاستجابة: هذا قرار مقصود وليس سهوًا.
• السماح لك بتثبيت مزوّد أو استبعاده — الوجه الآخر للقرار نفسه. ويظل بيدك تحديد النماذج التي نجرّبها، عبر التوجيه الاحتياطي أعلاه.
• ضغط موجّهك النصي — لا توجد transforms. لا نحذف رسائلك ولا نختصرها لتلائم نافذة السياق — اختصرها بنفسك إذا لزم الأمر. ما قد يغيّرها هو موجّه مُهيّأ على القناة التي تخدم طلبك: موجّه نظام، أو قالب تُضاف أدواره في المقدّمة — وفي وضع الاستبدال يحلّ ذلك محلّ رسالة النظام الخاصة بك.
• توفير نقطة نهاية للرصيد — تكلفة كل طلب تعود إليك من الواجهة، أما رصيدك الإجمالي فتجده في لوحة التحكم.

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

هل يمكن أن يحل OrcaRouter محل OpenRouter مباشرةً؟

في معظم التكاملات، نعم. غيّر base URL وضع مفتاح OrcaRouter؛ أما SDK وأسماء النماذج والرسائل والبثّ فتبقى كما هي. الاستثناءات هي معرّفات موجِّهات ⁨openrouter/⁩ الخاصة بـ OpenRouter، والتي يُعاد تسميتها، والأمور الأربعة التي لا يقوم بها OrcaRouter عن قصد، والمذكورة أعلاه.

ما base URL الذي يحتاجه كل SDK؟

يتطلب SDK الخاص بـ OpenAI العنوان ⁨https://api.orcarouter.ai/v1⁩، أما الاثنان الآخران فيكفيهما ⁨https://api.orcarouter.ai⁩، إذ يضيف كلٌّ منهما مساره بنفسه.

هل يمكنني الاستمرار في استخدام مفتاح API الخاص بـ OpenRouter؟

القيمة تتغيّر — مفتاح OpenRouter لا يُصادَق عليه هنا — أما الموضع فلا يتغيّر: نقرأ الترويسة نفسها التي ترسلها حزمة التطوير لديك بالفعل.

ما البديل عن ⁨openrouter/auto⁩ و⁨openrouter/free⁩؟

موجِّهات OrcaRouter هي تلك التي تبدأ بـ ⁨orcarouter/⁩. اثنان منها يقابلان موجِّهاتهم مباشرة: استخدم ⁨orcarouter/auto⁩ بدل ⁨openrouter/auto⁩، و ⁨orcarouter/free⁩ بدل ⁨openrouter/free⁩ — الفكرة ذاتها في الحالتين، نختار لك نموذجًا لحظة ورود الطلب، والثاني يبقيك في المستوى المجاني. أما بقية موجِّهاتهم فلا نظير لها هنا، فاذكر نموذجًا بعينه.

هل يعمل التوجيه الاحتياطي بالطريقة نفسها؟

انقل models و route إلى داخل extra_body. وما عدا ذلك فكل شيء كما هو: اذكر نماذجك حسب الأفضلية ونجرّبها واحدًا تلو الآخر. ‏2 نماذج كحد أدنى و5 كحد أقصى. يستحق الأمر أن تضبطه جيدًا. ففي المستوى الأعلى لا نقرؤها، فتتوقف بدائلك عن العمل دون أن تشعر؛ وفي عمليات النشر التي تمرّر متن الطلب كما هو، يستقبل النموذج تلك الحقول الزائدة وقد يرفض الاستدعاء كليًا.

كيف أعرف تكلفة طلب ما؟

اقرأ X-Orca-Request-Id من الاستجابة ثم استدعِ ‎⁨/v1/generation⁩. والرمز 501 يعني أنّ الاستعلام عن التكلفة معطَّل في هذا التنصيب.

هل ما زال X-Title و HTTP-Referer يعرّفان تطبيقي؟

أرسل X-Title ليحتفظ تطبيقك باسمه في تحليلاتك دون أي تغيير؛ ونحن نقرأ كذلك أسماء الترويسات الخاصة بـ OpenRouter. أما ترويسة HTTP-Referer وحدها فلا تسمّي تطبيقك إلا إذا كان نطاقه ضمن النطاقات التي نعرفها سلفًا، لذا أرسل ترويسة العنوان إن أردت التأكد. وُضع هذا البند هنا كي لا تحذفهما سهوًا.

ماذا يحدث لـ provider و transforms في طلباتي؟

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

ما نقاط النهاية التي يوفّرها OrcaRouter؟

كل ما تتوقعه، إضافةً إلى بضع نقاط لا يوفّرها OpenRouter. متاحة هنا وغير متاحة على OpenRouter: ⁨/v1/messages⁩ و⁨/v1beta/models … generateContent⁩ و⁨/v1/rerank⁩ و⁨/v1/realtime⁩. غير متاحة: ⁨/v1/fine-tunes⁩ و⁨GET /v1/files⁩ و⁨/v1/images/variations⁩.

هل تعود الأخطاء بالشكل نفسه؟

تعود الأخطاء بالشكل نفسه الذي تعالجه الآن. تصرَّف بحسب حالة HTTP: أعد محاولة 429 حين نرسل Retry-After، وتمهّل ثم أعد محاولة 5xx باستثناء 501 — فهو يعني أننا لا نخدم ذلك الاستدعاء أصلًا — وعامِل 4xx على استدعاء ترحيل بوصفه شيئًا يُصلَح في طلبك. والاستثناء هو 404 من ⁨/v1/generation⁩: قد يعني فقط أن الطلب لم تُسوَّ حسابيًا بعد، فأعد محاولته لفترة وجيزة. لا تقرأ error.type على أنه المصدر: فـ orcarouter_api_error منّا دائمًا، لكننا نرسل عمدًا مفردات المزوّد لبعض أعطالنا كي يسلك SDK مساره المعتاد — فحدّ المعدّل الذي نفرضه والذي يفرضه النموذج كلاهما يقول rate_limit_error. اذكر X-Orca-Request-Id حين تحتاج منّا البحث عن استدعاء بعينه.