# نقاط النهاية ومسارات API

تجمع هذه الصفحة طريقة عرض QCode.cc لثلاثة بروتوكولات API، وثلاثة نطاقات وصول، وكيفية ضبط `BASE_URL` بشكل صحيح. **مفتاح API واحد يعمل عبر البروتوكولات الثلاثة كلها** — يُختار البروتوكول بحسب مسار الطلب، ويتولى الخادم الخلفي لدينا التوجيه تلقائيًا.

> يعمل المفتاح بالطريقة نفسها أيًّا كان الخيار الذي تختاره. لم تختر بعد؟ راجع [كيفية اختيار خطة](/docs/getting-started/choose-a-plan)، ثم احصل على مفتاحك من لوحة التحكم.

## 1. بروتوكولات API

QCode.cc متوافق مع بروتوكولي **Anthropic Messages** و**OpenAI**. يوجد أيضًا مسار بروتوكول **Google Gemini**، لكن QCode أوقف مؤقتًا جميع نماذج Gemini عن العمل، لذا فإن ذلك المسار غير متاح حاليًا، ومادة Gemini أدناه مخصصة لمرجعية البروتوكول فقط:

| البروتوكول | العملاء المعتادون | المسار |
|----------|-----------------|------|
| Anthropic Messages | Claude Code / Claude Agent SDK / Cline / Aider | `/api/v1/messages` أو ما يعادله `/claude/v1/messages` |
| OpenAI Chat Completions | OpenAI SDK الرسمي / LangChain / DeepSeek-TUI / عملاء عامّون | `/openai/v1/chat/completions` |
| OpenAI Responses | Codex CLI (مطلوب لـ Codex) | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode (مزوّد `google`) / Google `@google/genai` SDK | `/gemini/v1beta/models/{model}:generateContent` (غير متاح حاليًا) |

تتبع أجسام الطلبات المخطط الرسمي الموافق (Anthropic `POST /v1/messages`، OpenAI `POST /v1/chat/completions`، OpenAI `POST /v1/responses`، Google `POST /v1beta/models/{model}:generateContent`).

> **ملاحظة**: `/api` و`/claude` و`/openai/v1` هي **بادئات مسارات**، وليست نقاط نهاية مستقلة. تُضيف SDKs تلقائيًا `/v1/messages` أو `/chat/completions` أو `/responses`. تشغيل `curl https://api.qcode.cc/api` مباشرةً يعيد صفحة هبوط HTML (HTTP 200) — هذا ليس خطأ ولا **يُثبت** أن المسار يعمل؛ استخدم الاختبار الذاتي عبر POST في القسم 5 أدناه.

## 2. أي النماذج تعمل على أي بروتوكول

**يُحدَّد البروتوكول بحسب مسار الطلب، لكن لا تعمل كل عائلة نماذج على كل بروتوكول.** الجدول أدناه هو المصدر الوحيد للحقيقة؛ وتعتمد عليه الصفحات الأخرى.

| عائلة النماذج | Anthropic<br>`/api/v1/messages` | OpenAI Chat<br>`/openai/v1/chat/completions` | OpenAI Responses<br>`/openai/v1/responses` | Gemini<br>`/gemini/v1beta/…` |
|---|:--:|:--:|:--:|:--:|
| Claude (`claude-opus-*` / `-sonnet-*` / `-haiku-*` / `-fable-*`) | ✅ | ❌ | ❌ | — |
| GPT (`gpt-6.1-sol` / `gpt-6-sol` / `gpt-5.6-terra`) | ❌ | ✅ | ✅ يستخدمه Codex | — |
| GLM / Kimi / DeepSeek / Qwen | ✅ | ✅ | ❌ | — |
| Gemini (لا يقدمه QCode في الوقت الحالي) | — | — | — | غير متاح |

🔴 **تعمل نماذج Claude على بروتوكول Anthropic فقط.** وضع `claude-…` في `/openai/v1/chat/completions` يعيد:

```json
{"error":{"code":"model_not_available_on_endpoint",
          "message":"Model 'claude-sonnet-5' is not available on this endpoint. Claude models are served only through the Anthropic Messages API: use a base URL ending in /api (or /claude) and send POST /v1/messages. OpenAI-compatible endpoints do not serve Claude models. / Claude 模型只能走 Anthropic Messages 接口：BASE_URL 以 /api（或 /claude）结尾，请求 POST /v1/messages；OpenAI 兼容接口不提供 Claude 模型。",
          "param":"model",
          "type":"invalid_request_error"}}
```

**يجري هذا الفحص قبل المصادقة** — فتحصل على هذا الخطأ حتى مع مفتاح غير صالح. لذا يعني `model_not_available_on_endpoint` أنك **اخترت البروتوكول الخطأ، وليس أن مفتاحك غير صالح**؛ فالمفتاح غير الصالح يعيد `Invalid API key` بدلًا من ذلك. لا تخلط بين الاثنين.

**القيد خاص بـ Claude**، وليس قاعدة شاملة من نوع «لا عبور بين البروتوكولات»:

- تعمل العائلات الصينية الأربع (GLM / Kimi / DeepSeek / Qwen) على **كلتا** نقطتَي النهاية: Anthropic وOpenAI Chat
- تستخدم نماذج GPT نقطتَي نهاية OpenAI؛ ولا تعمل على نقطة نهاية Anthropic كذلك

**ماذا يعني هذا عند اختيار أداة**: العملاء الذين يتحدثون بروتوكول OpenAI فقط ولا يوفرون نقطة نهاية Anthropic مخصصة (على سبيل المثال DeepSeek-TUI وWorkBuddy) **لا يمكنهم استخدام نماذج Claude** عبر QCode، رغم أن GPT والنماذج الصينية تعمل جيدًا. أما من أجل Claude، فاختر عميلًا يتحدث بروتوكول Anthropic (Claude Code أو Cline أو Zed أو مسار Anthropic في Cursor).
## 3. نطاقات الوصول الثلاثة

تؤدي النطاقات الثلاثة جميعها القدرات التجارية نفسها؛ وهي تختلف فقط في **توجيه الشبكة**:

| النطاق | المستخدمون المستهدفون | المخطط | ملاحظات |
|--------|--------------|--------|-------|
| `api.qcode.cc` | عالمي (عبر Route 53 حسب زمن الاستجابة) | HTTPS | الخيار الأساسي خارج الصين، ويختار أقرب عقدة |
| `us.qcode.cc` | أمريكا الشمالية / أوروبا | HTTPS | عقدة لوس أنجلوس |
| `asia.qcode.cc` | آسيا | HTTPS | عقدة آسيا (كوريا / تايوان / هونغ كونغ) |

يعمل مفتاح API واحد على النطاقات الثلاثة — يمكنك التبديل بحرية.

> **🇨🇳 ملاحظة لمستخدمي الصين**: نوصي بـ `asia.qcode.cc` (عقدة آسيا: كوريا / تايوان / هونغ كونغ)؛ وانتقل إلى `api.qcode.cc` (Route 53 العالمي) إذا كان الاتصال غير مستقر. تُرسل جميع النطاقات تقاريرها إلى [probe.qcode.cc](https://probe.qcode.cc) — أدخل مفتاح API الخاص بك في تلك الصفحة لفحص تفاصيل الطلب وطول السياق والاستخدام والمزيد.

## 4. ورقة مرجعية سريعة لـ BASE_URL

املأ ما يلي بحسب أداتك:

| الأداة | متغير البيئة / مفتاح الإعداد | القيمة | ما سيرسله SDK إلى |
|------|---------------------|-------|------------------|
| Claude Code | `ANTHROPIC_BASE_URL` | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Claude Agent SDK | وسيط الباني `base_url=` | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Cline / Aider | Base URL لوضع Anthropic | `https://api.qcode.cc/api` | `/api/v1/messages` |
| OpenAI Python/JS SDK | وسيط الباني `base_url=` | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| DeepSeek-TUI (مزوّد `openai`) | TOML `base_url =` أو `OPENAI_BASE_URL` | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| Codex CLI | TOML `base_url =` | `https://api.qcode.cc/openai` | `/openai/responses` |
| OpenCode (مزوّد `google`) | `baseURL` | `https://api.qcode.cc/gemini/v1beta` | `/gemini/v1beta/models/{model}:generateContent` |
| Gemini CLI / Google `@google/genai` SDK | Base URL | `https://api.qcode.cc/gemini` | `/gemini/v1beta/models/{model}:generateContent` |

> **مسار طلب Codex**: يُلحق Codex المسار `/responses` مباشرةً بـ `base_url`، لذا يذهب الطلب الفعلي إلى `/openai/responses`؛ ويُعدّ المساران `/openai/responses` و`/openai/v1/responses` متكافئين على QCode (اختُبر في 2026-10-27).

> **لماذا توجد صيغتان لـ Gemini؟** مزوّد `google` في OpenCode **لا** يُلحق `/v1beta/` تلقائيًا، لذا يجب أن يتضمن `baseURL` ذلك (`/gemini/v1beta`). ويقوم Gemini CLI وSDK `@google/genai` الرسمي من Google **بإلحاق** `/v1beta/` تلقائيًا، لذا لا يتجاوز Base URL المسار `/gemini` — وإضافة `/v1beta` بنفسك ستُنتج `/gemini/v1beta/v1beta/...` وتُرجع 404.

> **⚠️ Gemini غير متاح حاليًا**: أوقف QCode جميع نماذج Gemini مؤقتًا، لذا فإن صفّي Base URL الخاصين بـ Gemini أعلاه للمرجعية البروتوكولية فقط؛ يُرجى استخدام Claude أو GPT أو النماذج الصينية بدلًا من ذلك. وبشكل منفصل، وصل Gemini CLI إلى نهاية دورة حياته في 2026-06-18 (فئات حسابات المستهلكين)؛ والتوصية الرسمية هي Google Antigravity CLI.

> **عملاء سطح المكتب**: يتيح لك Cherry Studio إدخال جميع نقاط النهاية البروتوكولية الأربع أعلاه كمزوّدين مخصصين — راجع [تكامل Cherry Studio](/docs/ide/cherry-studio). للاطلاع على دعم البروتوكول لكل أداة وما إذا كان Claude يعمل، راجع [نظرة عامة على توافق الأدوات](/docs/ide/tool-compatibility)؛ وللاطلاع على الاشتراكات مقابل مفاتيح API، راجع [الاشتراكات مقابل مفاتيح API مقابل مفاتيح QCode](/docs/reference/subscription-vs-api-key).

## 5. الاختبار الذاتي باستخدام curl

قبل ربط SDK كامل، يمكنك التحقق من المسار واتصال الشبكة عبر طلب POST عادي:

```bash
KEY="cr_your_key"

# Anthropic protocol path test
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "Authorization: Bearer $KEY"
# → 400 = path & key both OK (missing body is expected); 401 = invalid key

# OpenAI Chat Completions path test
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# → 400 / 401 as above

# OpenAI Responses (used by Codex)
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/responses \
  -H "Authorization: Bearer $KEY"
# → 400 / 401 as above

# Google Gemini protocol path test (QCode does not offer Gemini for now; this path is unavailable, reference only)
curl -s -o /dev/null -w '%{http_code}\n' -X POST "https://api.qcode.cc/gemini/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $KEY"
# → 400 / 401 = path OK
```

**التفسير**: عند إرفاق مفتاح، فإن `400` (جسم مفقود) أو `401` (مشكلة في المفتاح) يعنيان أن تعيين المسار والشبكة سليمان؛ ويعني `404` أن بادئة المسار خاطئة — صحّحها وفق الجدول في القسم 4. إذا أعاد طلب مرفق بمفتاح الرمز `402` مع `code` بقيمة `*_cost_limit_exceeded`، فالمسار والمفتاح سليمان أيضًا — لكن حصة ذلك المفتاح استُهلكت ببساطة (راجع [رموز الخطأ](/docs/reference/errors#402-quota-exhausted)). ملاحظة: طلب هذه المسارات **دون مفتاح** يعيد صفحة تعريف HTML (HTTP 200) بدلًا من خطأ — ورؤية هذه الصفحة تعني أن مفتاحك لم يكن مُرفقًا.

اختبار من طرف إلى طرف باستخدام مفتاح API حقيقي:

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'
```

ينبغي أن يعطي تبديل النطاق إلى `us.qcode.cc` / `asia.qcode.cc` مع المسار نفسه النتيجة نفسها — وهذا يؤكد أن النطاق البديل قابل للاستخدام لديك.

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

**س: لماذا يعيد `curl https://api.qcode.cc/api` صفحة HTML؟**

ج: `/api` بادئة مسار وليس نقطة نهاية؛ الطلبات التي لا تطابق أي مسار API تُرسل إلى صفحة تعريف (HTTP 200). المسار الكامل هو `/api/v1/messages` — تحقق منه عبر اختبار POST الذاتي في القسم 5 (يعني `401` أن الطلب بلغ مرحلة المصادقة).

**س: هل هناك أي فرق بين `/api/v1/messages` و`/claude/v1/messages`؟**

ج: لا. كلتا البادئتين توجّهان إلى بروتوكول Anthropic Messages — استخدم ما يعتمده SDK الخاص بك افتراضيًا. تستخدم وثائقنا `/api` افتراضيًا لأن معظم SDKs في منظومة Claude تتوقعه.

**س: هل يمكن لمفتاح API واحد استدعاء كل من Claude وCodex (GPT)؟**

ج: نعم. المفاتيح مستقلة عن البروتوكول؛ **يُختار البروتوكول حسب مسار الطلب**. يعني `/api/v1/messages` بروتوكول Anthropic، ويعني `/openai/v1/responses` بروتوكول OpenAI Responses. لا توفر QCode نماذج Gemini في الوقت الحالي.

**س: هل يجب أن ينتهي `baseURL` الخاص بـ Gemini بـ `/v1beta` أم لا؟**

ج: (لا توفر QCode Gemini في الوقت الحالي؛ ما يلي مرجع للبروتوكول فقط.) يعتمد ذلك على الأداة. **مزوّد `google` في OpenCode يحتاج إليها** (اضبط `baseURL` على `/gemini/v1beta`) لأنه لا يضيف `/v1beta/` تلقائيًا. **لا تحتاج إليها Gemini CLI وSDK `@google/genai` من Google** (اضبط Base URL على `/gemini`) — يضيف SDK `/v1beta/` بنفسه، وإضافتها يدويًا ستنتج `/gemini/v1beta/v1beta/...` وتعيد 404.

**س: أي نطاق ينبغي أن أختار؟**

ج: البر الرئيسي للصين → `asia.qcode.cc` (عقدة آسيا: كوريا / تايوان / هونغ كونغ) أو `api.qcode.cc` (Route 53 العالمي)؛ أمريكا الشمالية / أوروبا → `us.qcode.cc`. إذا توقف نطاقك الأساسي عن الاستجابة، فبدّل إلى أحد النطاقات الأخرى.

**س: هل يمكنني رؤية سجل طلباتي؟**

ج: نعم. الطلبات المرسلة عبر أي نطاق (`api.qcode.cc` / `asia.qcode.cc` / `us.qcode.cc`) تُرسل إلى [probe.qcode.cc](https://probe.qcode.cc). أدخل مفتاح API الخاص بك هناك لعرض قائمة الطلبات والنماذج وtokens والمزيد.

**س: هل ينبغي تضمين شرطة مائلة لاحقة في BASE_URL؟**

ج: **لا**. تضيف معظم SDKs مسارات مثل `/v1/messages` تلقائيًا؛ وستنتج الشرطة المائلة اللاحقة `//v1/messages` وتؤدي إلى 404.