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

بروتوكولا API لكل من Anthropic وOpenAI في QCode.cc (مسار Gemini غير متاح حاليًا)، وثلاثة نطاقات وصول، وكيفية تعبئة BASE_URL

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

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

يعمل المفتاح بالطريقة نفسها أيًّا كان الخيار الذي تختاره. لم تختر بعد؟ راجع كيفية اختيار خطة، ثم احصل على مفتاحك من لوحة التحكم.

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

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

تتبع أجسام الطلبات المخطط الرسمي الموافق (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. أي النماذج تعمل على أي بروتوكول¶

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

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

{"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 واحد على النطاقات الثلاثة — يمكنك التبديل بحرية.

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

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

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

مسار طلب 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. للاطلاع على دعم البروتوكول لكل أداة وما إذا كان Claude يعمل، راجع نظرة عامة على توافق الأدوات؛ وللاطلاع على الاشتراكات مقابل مفاتيح API، راجع الاشتراكات مقابل مفاتيح API مقابل مفاتيح QCode.

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

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

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، فالمسار والمفتاح سليمان أيضًا — لكن حصة ذلك المفتاح استُهلكت ببساطة (راجع رموز الخطأ). ملاحظة: طلب هذه المسارات دون مفتاح يعيد صفحة تعريف HTML (HTTP 200) بدلًا من خطأ — ورؤية هذه الصفحة تعني أن مفتاحك لم يكن مُرفقًا.

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

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. أدخل مفتاح API الخاص بك هناك لعرض قائمة الطلبات والنماذج وtokens والمزيد.

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

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

المؤسسات ←