# نقاط پایانی و مسیرهای 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 | SDK رسمی OpenAI / LangChain / DeepSeek-TUI / کلاینت‌های عمومی | `/openai/v1/chat/completions` |
| OpenAI Responses | Codex CLI (الزامی برای Codex) | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode (ارائه‌دهنده `google`) / SDK `@google/genai` گوگل | `/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` **پیشوندهای مسیر** هستند، نه نقاط پایانی مستقل. SDKها به‌صورت خودکار `/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 روی هر سه دامنه کار می‌کند — می‌توانید آزادانه بین آن‌ها جابه‌جا شوید.

> **🇨🇳 یادداشت برای کاربران CN**: توصیه می‌کنیم از `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` گوگل `/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` استفاده می‌کنند چون بیشتر 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](https://probe.qcode.cc) گزارش می‌شوند. کلید API خود را آنجا وارد کنید تا فهرست درخواست‌ها، مدل‌ها، توکن‌ها و موارد بیشتر را ببینید.

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

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