ما هو العنوان الأساسي base URL؟ ومكانه في مكتبات الـ API

العنوان الأساسي (base URL) هو البداية الثابتة لكل عنوان تستقبل عليه واجهة الـ API الطلبات، مثل https://api.openai.com/v1. وتضيف المكتبة إليه مسار كل طلب، مثل /chat/completions. وإذا غيّرت العنوان الأساسي، يرسل الكود نفسه طلباته إلى خدمة أخرى تفهم الصيغة نفسها، بشرط أن يناسبها المفتاح ومعرّف النموذج.

ما هو العنوان الأساسي؟#

يذهب كل طلب إلى واجهة API للذكاء الاصطناعي إلى عنوان كامل من جزأين. العنوان الأساسي هو الجزء الثابت في كل الطلبات: البروتوكول واسم الخادم وغالبًا رقم الإصدار، كما في https://api.openai.com/v1. والمسار هو الجزء الذي يحدد العملية، مثل /chat/completions لرد المحادثة و/models لقائمة النماذج.

base URL   https://api.openai.com/v1
+ path     /chat/completions
= request  https://api.openai.com/v1/chat/completions

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

الفرق بين العنوان الأساسي ونقطة النهاية#

نقطة النهاية (endpoint) عنوان كامل لعملية واحدة مع طريقة طلب HTTP، مثل POST /v1/messages لرد من Claude. أما العنوان الأساسي فهو البداية المشتركة لكل نقاط النهاية. وحين تطلب منك أداة «base URL» أو «API base» أو «custom endpoint»، فهي تقصد غالبًا هذه البداية المشتركة، لا عنوان طلب واحد.

لماذا تغيّر العنوان الأساسي؟#

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

وفي مكتبتي Python الرسميتين اللتين راجعناهما، يُختار العنوان الأساسي بالترتيب نفسه: القيمة المكتوبة في الكود تتقدم على متغير البيئة، والمتغير يتقدم على القيمة الافتراضية في المكتبة. والمتغير هو OPENAI_BASE_URL في مكتبة OpenAI، وANTHROPIC_BASE_URL في مكتبة Anthropic.

العناوين الأساسية الرسمية#

راجعناها في 2026-11-01 في توثيق كل مزوّد والكود المصدري لمكتبته:

ويختلف موضع رقم الإصدار من مزوّد إلى آخر: ينتهي عنوان OpenAI بـ /v1، ولا يحمل عنوان Anthropic رقم إصدار لأن المكتبة تضيف /v1/messages بنفسها، وينتهي عنوان Gemini بـ /v1beta. وكثير من أخطاء الإعداد سببها هذا الفرق وحده.

العنوان الأساسي في مكتبة OpenAI#

تأخذ مكتبة OpenAI العنوان الأساسي من الوسيط base_url في الكود أو من OPENAI_BASE_URL، والمفتاح من OPENAI_API_KEY. أبقِ /v1 في نهاية العنوان، فالمكتبة تضيف اسم العملية فقط، مثل /chat/completions أو /responses.

import os
from openai import OpenAI

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

وصيغة OpenAI في خبير متوافقة مع OpenAI: غيّر العنوان الأساسي واحتفظ بالكود نفسه. وتدعم Chat Completions وResponses، ويمكنك أن تستدعي نماذج Claude بهذه الصيغة أيضًا. وتعرض صفحة كل نموذج في قائمة النماذج الصيغ التي يدعمها. والإعداد نفسه بمتغيرات البيئة على macOS وLinux وWindows في مكتبة OpenAI.

العنوان الأساسي في مكتبة Anthropic#

تأخذ مكتبة Anthropic العنوان من base_url في الكود أو من ANTHROPIC_BASE_URL، والمفتاح من ANTHROPIC_API_KEY. لا تضف /v1، فالمكتبة تضيف /v1/messages بنفسها، وترسل الترويسة anthropic-version نيابة عنك.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.5abeer.ai",
    api_key=os.environ["KHABEER_API_KEY"],
)

وصيغة Anthropic في خبير متوافقة مع واجهة Anthropic Messages، فيبقى الكود المبني على مكتبة Anthropic كما هو. والخطوات في مكتبة Anthropic، وحقول الطلب في Anthropic Messages.

العنوان الأساسي في Claude Code#

يقرأ Claude Code المتغير ANTHROPIC_BASE_URL أيضًا، فالقاعدة نفسها: لا /v1 في النهاية. ويضيف دليل البوابات من Anthropic، الذي راجعناه في 2026-11-01، نقطتين:

• للمفتاح متغير خاص به. يرسل ANTHROPIC_AUTH_TOKEN المفتاح في الترويسة Authorization: Bearer، ويرسله ANTHROPIC_API_KEY في x-api-key. وإذا وضعت المفتاح في المتغير الخطأ، يصل إلى البوابة في ترويسة لا تقرؤها، فيفشل الطلب بالرمز 401.
• العنوان الأساسي وحده لا يغيّر حسابك. ضبط ANTHROPIC_BASE_URL وحده لا يلغي دخولك المحفوظ إلى claude.ai، فيبقى هذا الدخول هو المستخدم ما لم تضع مفتاحًا للبوابة.

ويضع دليل Claude Code مفتاحك من خبير في ANTHROPIC_AUTH_TOKEN. وللتحقق من الإعداد، شغّل الأمر /status داخل Claude Code، فهو يعرض سطر Anthropic base URL فقط حين يكون عنوان بوابة مضبوطًا. وتحذّر Anthropic من وضع المفتاح في الملف .claude/settings.json داخل المشروع، لأن هذا الملف يُرفع مع الكود ويُشارك مع غيرك، فاستخدم ~/.claude/settings.json بدلًا منه.

وإذا كان لديك اشتراك في خبير يشمل Claude Code، فإن تطبيق 5abeer AI يضبطه لك دون مفتاح API ودون تعديل أي ملف، كما في Claude Code. أما Codex CLI فيأخذ عنوانه الأساسي من ~/.codex/config.toml، والخطوات في تشغيل Codex CLI بمفتاح API.

العنوان الأساسي في Gemini#

تضع صيغة Gemini الأصلية النموذج في المسار. فالعنوان الأساسي https://generativelanguage.googleapis.com/v1beta، ويذهب الطلب إلى /models/{model}:generateContent، ويوضع المفتاح في الترويسة x-goog-api-key. وتوفر Google أيضًا عنوانًا متوافقًا مع مكتبات OpenAI هو https://generativelanguage.googleapis.com/v1beta/openai/، وتقول إن هذا الدعم ما زال تجريبيًا (beta) بينما توسّع الميزات المدعومة.

وفي خبير تقع صيغة Gemini تحت /v1beta، وتحتاج إلى مفتاح لنماذج Gemini، فمفاتيح Claude وGPT لا تعمل عليها. ويقرأ Gemini CLI عنوانه الأساسي من GOOGLE_GEMINI_BASE_URL. والإعداد الكامل في Gemini CLI، وأشكال الطلب في مرجع صيغة Gemini.

أخطاء العنوان الأساسي الشائعة#

يشير الخطأ غالبًا إلى الجزء الخطأ في الطلب:

ولا تزول أخطاء 400 و401 و403 بإعادة المحاولة، فأصلح الطلب أولًا. وكل رمز وحلّه في رموز الأخطاء، ومنها INVALID_API_KEY.

اختبر العنوان الأساسي بطلب واحد#

قبل أن تغيّر مشروعًا كبيرًا، أرسل طلبًا واحدًا إلى العنوان الكامل. فإذا وصل رد، فالعنوان الأساسي والمفتاح صحيحان. بصيغة OpenAI:

curl --request POST "https://api.5abeer.ai/v1/chat/completions" \
  --header "Authorization: Bearer $KHABEER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"claude-sonnet-5.5","messages":[{"role":"user","content":"اكتب فكرة منتج في سطر واحد"}]}'

{
  "id": "chatcmpl-9f2",
  "object": "chat.completion",
  "model": "claude-sonnet-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "مرحبًا! كيف أساعدك اليوم؟"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 12,
    "total_tokens": 33
  }
}

وبصيغة Anthropic:

curl --request POST "https://api.5abeer.ai/v1/messages" \
  --header "x-api-key: $KHABEER_API_KEY" \
  --header "Content-Type: application/json" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"model":"claude-sonnet-5.5","max_tokens":512,"messages":[{"role":"user","content":"اكتب فكرة منتج في سطر واحد"}]}'

{
  "id": "msg_01Xh7",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5.5",
  "content": [
    {
      "type": "text",
      "text": "مرحبًا! كيف أساعدك اليوم؟"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 21,
    "output_tokens": 12
  }
}

تقرأ هذه الأمثلة المفتاح من KHABEER_API_KEY، وتكتب العنوان كاملًا، فترى العنوان الأساسي والمسار متصلين.

العناوين الأساسية في خبير#

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

يدفع مفتاح API من خبير ثمن التوكنات من رصيدك، وكل نموذج مسعّر بالتوكن أقل من سعره الرسمي. قارن النماذج في صفحة الـ API، أو بحسب المزوّد في Claude API وOpenAI API وGemini API. ولكل مفتاح حد للإنفاق وتاريخ انتهاء وقائمة عناوين IP المسموح بها، كما في تحكّم في كل مفتاح.

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

أسئلة شائعة#

هل العنوان الأساسي هو نقطة النهاية نفسها؟#

لا. العنوان الأساسي هو البداية المشتركة، مثل https://api.anthropic.com. ونقطة النهاية عملية كاملة واحدة، مثل POST /v1/messages. وتجمع المكتبة بينهما في كل طلب.

هل أضيف v1 في نهاية العنوان الأساسي؟#

يعتمد ذلك على المكتبة. تتوقع مكتبة OpenAI وجود /v1 في العنوان الأساسي. أما مكتبة Anthropic وClaude Code فيتوقعان عنوانًا بلا رقم إصدار، لأنهما يضيفان /v1/messages بنفسيهما. وينتهي عنوان Gemini الأصلي بـ /v1beta.

أين أضبط العنوان الأساسي؟#

في الكود بالوسيط base_url، أو في متغير بيئة: OPENAI_BASE_URL لمكتبة OpenAI، وANTHROPIC_BASE_URL لمكتبة Anthropic وClaude Code. وفي مكتبتي Python تتقدم القيمة المكتوبة في الكود على المتغير.

هل أحتاج إلى كود جديد لأغيّر العنوان الأساسي؟#

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

أين يوضع مفتاح الـ API؟#

في ترويسة الطلب، لا في العنوان الأساسي. وفي خبير تكون الترويسة Authorization: Bearer لصيغة OpenAI، وx-api-key مع anthropic-version لصيغة Anthropic، وx-goog-api-key لصيغة Gemini. واحفظ المفتاح في متغير بيئة، لا في الكود ولا في ملف مشترك.

لماذا يستخدم Claude Code حسابي في claude.ai؟#

لأن ضبط ANTHROPIC_BASE_URL وحده لا يلغي الدخول المحفوظ. ضع مفتاحك في ANTHROPIC_AUTH_TOKEN كما في دليل Claude Code، ثم تحقق من سطر Anthropic base URL في نتيجة /status.

المصادر#

راجعناها في 2026-11-01:

• OpenAI: API overview وopenai-python
• Anthropic: API overview وPython SDK وanthropic-sdk-python
• Claude Code: Connect Claude Code to an LLM gateway وOther LLM gateways
• Google AI for Developers: Generating content وGetting started وOpenAI compatibility

ابدأ#

انسخ العنوان الأساسي لمكتبتك من الجدول السابق، وأنشئ مفتاحًا، وأرسل أول طلب.