نقاط پایانی و مسیرهای 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 پیشوندهای مسیر هستند، نه نقاط پایانی مستقل. SDKها به‌صورت خودکار /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 روی هر سه دامنه کار می‌کند — می‌توانید آزادانه بین آن‌ها جابه‌جا شوید.

🇨🇳 یادداشت برای کاربران CN: توصیه می‌کنیم از 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 گوگل /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 استفاده می‌کنند چون بیشتر SDKهای اکوسیستم 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 گوگل به آن نیاز ندارند (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 خود را آنجا وارد کنید تا فهرست درخواست‌ها، مدل‌ها، توکن‌ها و موارد بیشتر را ببینید.

پرسش: آیا باید در BASE_URL یک اسلش انتهایی قرار دهم؟

پاسخ: خیر. بیشتر SDKها مسیرهایی مانند /v1/messages را به‌صورت خودکار اضافه می‌کنند؛ اسلش انتهایی //v1/messages تولید می‌کند و باعث 404 می‌شود.

سازمانی ←