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

> ما العنوان الأساسي، وما العنوان الرسمي لمكتبات OpenAI وAnthropic وGemini، وكيف تضبطه في الكود أو Claude Code، وكيف تصلح أخطاء 404 و401.

آخر تحديث: 2026-11-01

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

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

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

```text
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 | `https://api.openai.com/v1` | `/chat/completions` و`/responses` | `Authorization: Bearer` |
| Anthropic | `https://api.anthropic.com` | `/v1/messages` | `Authorization: Bearer` أو `x-api-key`، ومعها `anthropic-version` |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta` | `/models/{model}:generateContent` | `x-goog-api-key` |

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

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

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

```python
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 بهذه الصيغة أيضًا. وتعرض صفحة كل نموذج في [قائمة النماذج](https://5abeer.ai/ar/models) الصيغ التي يدعمها. والإعداد نفسه بمتغيرات البيئة على macOS وLinux وWindows في [مكتبة OpenAI](https://5abeer.ai/ar/docs/start/base-urls.md#openai).

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

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

```python
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](https://5abeer.ai/ar/docs/start/base-urls.md#anthropic)، وحقول الطلب في [Anthropic Messages](https://5abeer.ai/ar/docs/api/messages.md).

## العنوان الأساسي في 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](https://5abeer.ai/ar/docs/apps/claude-code.md#configure) مفتاحك من خبير في `ANTHROPIC_AUTH_TOKEN`. وللتحقق من الإعداد، شغّل الأمر `/status` داخل Claude Code، فهو يعرض سطر `Anthropic base URL` فقط حين يكون عنوان بوابة مضبوطًا. وتحذّر Anthropic من وضع المفتاح في الملف `.claude/settings.json` داخل المشروع، لأن هذا الملف يُرفع مع الكود ويُشارك مع غيرك، فاستخدم `~/.claude/settings.json` بدلًا منه.

وإذا كان لديك اشتراك في خبير يشمل Claude Code، فإن تطبيق 5abeer AI يضبطه لك دون مفتاح API ودون تعديل أي ملف، كما في [Claude Code](https://5abeer.ai/ar/docs/apps/claude-code.md#easy). أما Codex CLI فيأخذ عنوانه الأساسي من `~/.codex/config.toml`، والخطوات في [تشغيل Codex CLI بمفتاح API](https://5abeer.ai/ar/guides/codex-cli-api-key).

## العنوان الأساسي في 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](https://5abeer.ai/ar/docs/apps/gemini-cli.md#configure)، وأشكال الطلب في [مرجع صيغة Gemini](https://5abeer.ai/ar/docs/api/gemini.md).

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

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

| ما تراه | السبب المحتمل | الحل |
| --- | --- | --- |
| `404` Not Found | تكرّر `/v1` أو سقط، فالمسار غير موجود | مكتبة OpenAI: أبقِ `/v1`. مكتبة Anthropic وClaude Code: احذفه |
| `401` مع `API_KEY_REQUIRED` أو `INVALID_API_KEY` | المفتاح غير موجود أو به خطأ أو في ترويسة لا تقرؤها الخدمة | انسخ المفتاح من جديد، وتأكد من المتغير أو الترويسة التي تحمله |
| `403` مع `MODEL_PLATFORM_NOT_ALLOWED` | المفتاح لمزوّد والنموذج لمزوّد آخر | استخدم مفتاحًا لمزوّد هذا النموذج، كما في [مفتاح لكل مزوّد](https://5abeer.ai/ar/docs/start/keys.md#per-provider) |
| `ENOTFOUND` أو اتصال مرفوض | اسم الخادم به خطأ أو لا يمكن الوصول إليه | انسخ العنوان الأساسي من جديد من جدول عناوين خبير أدناه |
| صفحة HTML بدل JSON، أو خطأ يقول إن الرد فارغ أو لا يمكن قراءته | العنوان يشير إلى موقع ويب لا إلى الواجهة | استخدم عنوان الـ API لا عنوان الموقع |

ولا تزول أخطاء `400` و`401` و`403` بإعادة المحاولة، فأصلح الطلب أولًا. وكل رمز وحلّه في [رموز الأخطاء](https://5abeer.ai/ar/docs/help/errors.md#codes)، ومنها [`INVALID_API_KEY`](https://5abeer.ai/ar/docs/help/errors.md#INVALID_API_KEY).

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

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

```bash
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":"اكتب فكرة منتج في سطر واحد"}]}'
```

```python
import os
import requests

response = requests.post(
    "https://api.5abeer.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['KHABEER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
    "model": "claude-sonnet-5.5",
    "messages": [
        {
            "role": "user",
            "content": "اكتب فكرة منتج في سطر واحد"
        }
    ]
},
    stream=False,
    timeout=60,
)

response.raise_for_status()
print(response.json())
```

وبصيغة Anthropic:

```bash
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":"اكتب فكرة منتج في سطر واحد"}]}'
```

```python
import os
import requests

response = requests.post(
    "https://api.5abeer.ai/v1/messages",
    headers={
        "x-api-key": os.environ['KHABEER_API_KEY'],
        "Content-Type": "application/json",
        "anthropic-version": "2023-06-01",
    },
    json={
    "model": "claude-sonnet-5.5",
    "max_tokens": 512,
    "messages": [
        {
            "role": "user",
            "content": "اكتب فكرة منتج في سطر واحد"
        }
    ]
},
    stream=False,
    timeout=60,
)

response.raise_for_status()
print(response.json())
```

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

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

يستقبل خبير الطلبات بثلاث صيغ. استخدم العنوان الأساسي الذي يناسب مكتبتك، وأرسل المفتاح في ترويسة هذه الصيغة، كما في [أين تضع المفتاح في الطلب](https://5abeer.ai/ar/docs/start/keys.md#headers):

| الصيغة | العنوان الأساسي | ترويسة المفتاح |
| --- | --- | --- |
| OpenAI | `https://api.5abeer.ai/v1` | `Authorization: Bearer <KEY>` |
| Anthropic | `https://api.5abeer.ai` | `x-api-key: <KEY>` |
| Gemini | `https://api.5abeer.ai/v1beta` | `x-goog-api-key: <KEY>` |

يدفع مفتاح API من خبير ثمن التوكنات من رصيدك، وكل نموذج مسعّر بالتوكن أقل من سعره الرسمي. قارن النماذج في [صفحة الـ API](https://5abeer.ai/ar/api)، أو بحسب المزوّد في [Claude API](https://5abeer.ai/ar/api/claude) و[OpenAI API](https://5abeer.ai/ar/api/openai) و[Gemini API](https://5abeer.ai/ar/api/gemini). ولكل مفتاح حد للإنفاق وتاريخ انتهاء وقائمة عناوين IP المسموح بها، كما في [تحكّم في كل مفتاح](https://5abeer.ai/ar/docs/start/keys.md#controls).

والباقات مخصصة للتطبيقات المدعومة، ولاستخدام النماذج من الكود الخاص بك أنشئ مفتاح API. والتطبيقات في [التطبيقات المدعومة](https://5abeer.ai/ar/apps)، والباقات في [صفحة الأسعار](https://5abeer.ai/ar/pricing). وإن كنت جديدًا على المفاتيح فابدأ من [ما هو مفتاح API وكيف تحصل على واحد](https://5abeer.ai/ar/guides/ai-api-key-guide)، واقرأ [ما هو التوكن](https://5abeer.ai/ar/guides/what-is-a-token) لتعرف كيف يُحاسب كل طلب.

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

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

لا. العنوان الأساسي هو البداية المشتركة، مثل `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](https://5abeer.ai/ar/docs/apps/claude-code.md#configure)، ثم تحقق من سطر `Anthropic base URL` في نتيجة `/status`.

## المصادر

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

- OpenAI: [API overview](https://developers.openai.com/api/reference/overview) و[openai-python](https://github.com/openai/openai-python)
- Anthropic: [API overview](https://platform.claude.com/docs/en/api/overview) و[Python SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python) و[anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Claude Code: [Connect Claude Code to an LLM gateway](https://code.claude.com/docs/en/llm-gateway-connect) و[Other LLM gateways](https://code.claude.com/docs/en/llm-gateway)
- Google AI for Developers: [Generating content](https://ai.google.dev/api/generate-content) و[Getting started](https://ai.google.dev/gemini-api/docs/quickstart) و[OpenAI compatibility](https://ai.google.dev/gemini-api/docs/openai)

> خبير خدمة مستقلة، ولا تتبع OpenAI أو Anthropic أو Google.

## ابدأ

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