# Endpunkte & API-Pfade

Diese Seite fasst zusammen, wie QCode.cc drei API-Protokolle und drei Zugriffsdomänen bereitstellt, und wie Sie `BASE_URL` korrekt einrichten. **Ein einzelner API-Key funktioniert über alle drei Protokolle hinweg** — die Protokollauswahl erfolgt über den Request-Pfad, und unser Backend routet automatisch.

## 1. Drei API-Protokolle

QCode.cc ist mit den Protokollen **Anthropic Messages**, **OpenAI** und **Google Gemini** kompatibel:

| Protokoll | Typische Clients | Pfad |
|----------|-----------------|------|
| Anthropic Messages | Claude Code / Claude Agent SDK / Cline / Aider | `/api/v1/messages` oder gleichbedeutend `/claude/v1/messages` |
| OpenAI Chat Completions | Offizielles OpenAI SDK / LangChain / DeepSeek-TUI / generische Clients | `/openai/v1/chat/completions` |
| OpenAI Responses | Codex CLI (für Codex erforderlich) | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode (`google` provider) / Google `@google/genai` SDK | `/gemini/v1beta/models/{model}:generateContent` |

Request-Bodies folgen dem jeweiligen offiziellen Schema (Anthropic `POST /v1/messages`, OpenAI `POST /v1/chat/completions`, OpenAI `POST /v1/responses`, Google `POST /v1beta/models/{model}:generateContent`).

> **Hinweis**: `/api`, `/claude` und `/openai/v1` sind **Pfadpräfixe**, keine eigenständigen Endpunkte. SDKs hängen automatisch `/v1/messages`, `/chat/completions` oder `/responses` an. Ein direkter Aufruf von `curl https://api.qcode.cc/api` liefert eine HTML-Landingpage zurück (HTTP 200) — das ist kein Fehler und belegt **nicht**, dass der Pfad funktioniert; verwenden Sie den POST-Selbsttest in Abschnitt 5 unten.

## 2. Welche Modelle funktionieren über welches Protokoll

**Das Protokoll wird durch den Request-Pfad bestimmt, aber nicht jede Modellfamilie funktioniert über jedes
Protokoll.** Die folgende Tabelle ist die einzige maßgebliche Quelle; andere Seiten verweisen darauf.

| Modellfamilie | 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-sol` / `gpt-6-luna` / `gpt-5.6-terra`) | ❌ | ✅ | ✅ von Codex genutzt | — |
| GLM / Kimi / DeepSeek / Qwen | ✅ | ✅ | ❌ | — |
| Gemini | ❌ | ❌ | — | ✅ |

🔴 **Claude-Modelle funktionieren ausschließlich über das Anthropic-Protokoll.** Setzt man `claude-…` in
`/openai/v1/chat/completions` ein, lautet die Antwort:

```json
{"error":{"code":"model_not_available_on_endpoint",
          "message":"Model 'claude-sonnet-5' is not available on this endpoint.",
          "type":"invalid_request_error"}}
```

**Diese Prüfung erfolgt vor der Authentifizierung** — Sie erhalten diesen Fehler auch bei ungültigem Key. `model_not_available_on_endpoint` bedeutet also, dass **Sie das falsche Protokoll gewählt haben, nicht dass Ihr Key ungültig ist**; ein ungültiger Key liefert stattdessen `Invalid API key`. Verwechseln Sie die beiden nicht.

**Die Einschränkung betrifft ausschließlich Claude**, es ist keine pauschale „kein Protokollwechsel“-Regel:

- Die vier chinesischen Familien (GLM / Kimi / DeepSeek / Qwen) funktionieren über **beide** Stränge: den Anthropic- und den OpenAI-Chat-Strang
- GPT-Modelle nutzen die beiden OpenAI-Stränge; über den Anthropic-Strang funktionieren sie ebenfalls nicht

**Was das bei der Tool-Auswahl bedeutet**: Clients, die nur das OpenAI-Protokoll sprechen und keinen eigenen Anthropic-Endpunkt bieten (zum Beispiel DeepSeek-TUI und WorkBuddy), **können Claude-Modelle über QCode nicht nutzen**, GPT und die chinesischen Modelle funktionieren hingegen einwandfrei. Wählen Sie für Claude einen Client, der das Anthropic-Protokoll spricht (Claude Code, Cline, Zed oder den Anthropic-Pfad von Cursor).
## 3. Drei Zugriffsbereiche

Alle drei Bereiche bieten identische Funktionalitäten; sie unterscheiden sich nur im **Netzwerk-Routing**:

| Bereich | Zielgruppe | Protokoll | Hinweise |
|--------|--------------|--------|-------|
| `api.qcode.cc` | Global (Route 53 latenzbasiert) | HTTPS | Primär für Nutzer außerhalb Chinas, wählt den nächsten Knoten |
| `us.qcode.cc` | Nordamerika / Europa (Backup) | HTTPS | US-RY2-Knoten (Los Angeles) |
| `asia.qcode.cc` | Asien (Backup) | HTTPS | Asien-Knoten (Korea / Taiwan / Hong Kong) |

Ein einzelner API-Key funktioniert auf allen drei Bereichen – Sie können frei wechseln.

> **🇨🇳 Hinweis für Nutzer in China**: Wir empfehlen `asia.qcode.cc` (Asien-Knoten: Korea / Taiwan / Hong Kong, niedrigste Latenz); wechseln Sie zu `api.qcode.cc` (global Route 53), falls instabil. Alle Bereiche berichten an [probe.qcode.cc](https://probe.qcode.cc) – geben Sie auf dieser Seite Ihren API-Key ein, um Request-Details, Kontextlänge, Nutzung und mehr zu prüfen.

## 4. BASE_URL-Spickzettel

Tragen Sie das Folgende je nach Ihrem Tool ein:

| Tool | Umgebungsvariable / Konfigurationsschlüssel | Wert | SDK sendet an |
|------|---------------------|-------|------------------|
| Claude Code | `ANTHROPIC_BASE_URL` | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Claude Agent SDK | `base_url=` Konstruktorargument | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Cline / Aider | Anthropic-Modus Basis-URL | `https://api.qcode.cc/api` | `/api/v1/messages` |
| OpenAI Python/JS SDK | `base_url=` Konstruktorargument | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| DeepSeek-TUI (`openai` provider) | TOML `base_url =` oder `OPENAI_BASE_URL` | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| Codex CLI | TOML `base_url =` | `https://api.qcode.cc/openai` | `/openai/v1/responses` |
| OpenCode (`google` provider) | `baseURL` | `https://api.qcode.cc/gemini/v1beta` | `/gemini/v1beta/models/{model}:generateContent` |
| Gemini CLI / Google `@google/genai` SDK | Basis-URL | `https://api.qcode.cc/gemini` | `/gemini/v1beta/models/{model}:generateContent` |


> **Warum zwei Formen für Gemini?** Der `google`-Provider von OpenCode fügt `/v1beta/` **nicht** automatisch an, daher muss die `baseURL` diesen Pfad enthalten (`/gemini/v1beta`). Gemini CLI und Googles offizielles `@google/genai` SDK fügen `/v1beta/` **automatisch** an, daher endet die Basis-URL nur bei `/gemini` – wenn Sie `/v1beta` selbst anhängen, ergibt das `/gemini/v1beta/v1beta/...` und liefert 404 zurück.

> **⚠️ Gemini CLI Umstellung**: Gemini CLI ist am 2026-06-18 eingestellt worden (Pro- / Gratis-Tier) – verwenden Sie künftig die **Google Antigravity CLI**; Enterprise-Bezahlschlüssel sind nicht betroffen. QCode.cc bedient weiterhin Gemini-Modelle, und die oben genannten Gemini-Basis-URL und API-Key bleiben unverändert – Antigravity CLI nutzt denselben `/gemini`-Endpunkt.

> **Desktop-Clients**: Cherry Studio ermöglicht es Ihnen, alle vier oben genannten Protokollzweige als eigene Anbieter einzutragen – siehe [Cherry Studio Integration](/docs/ide/cherry-studio). Für die Protokollunterstützung je Tool und ob Claude funktioniert, siehe [Tool-Kompatibilitätsübersicht](/docs/ide/tool-compatibility); für Abos vs. API-Keys, siehe [Abos vs. API-Keys vs. QCode-Keys](/docs/reference/subscription-vs-api-key).

## 5. Selbsttest mit curl

Bevor Sie ein vollständiges SDK einbinden, können Sie den Pfad und die Netzwerkkonnektivität mit einem einfachen POST testen:

```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
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
```

**Interpretation**: Mit einem angegebenen Key bedeuten `400` (fehlender Body) oder `401` (Key-Problem), dass die Pfadzuordnung und das Netzwerk einwandfrei funktionieren; `404` bedeutet einen falschen Pfad-Präfix – korrigieren Sie ihn anhand der Tabelle in Abschnitt 4. Hinweis: Wird einer dieser Pfade **ohne Key** aufgerufen, erhalten Sie eine HTML-Einführungsseite (HTTP 200) und keine Fehlermeldung – sehen Sie diese, wurde Ihr Key nicht übermittelt.

End-to-End-Test mit einem echten API-Key:

```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"}]}'
```

Wenn Sie die Domain auf `us.qcode.cc` / `asia.qcode.cc` ändern und denselben Pfad beibehalten, sollte das gleiche Ergebnis erzeugt werden – dies bestätigt, dass der alternative Bereich für Sie nutzbar ist.
## 6. FAQ

**F: Warum liefert `curl https://api.qcode.cc/api` eine HTML-Seite zurück?**

A: `/api` ist ein Pfadpräfix und kein Endpunkt; Anfragen, die zu keiner API-Route passen, werden auf eine Landingpage umgeleitet (HTTP 200). Der vollständige Pfad lautet `/api/v1/messages` – prüfen Sie ihn mit dem POST-Selbsttest in Abschnitt 5 (ein `401` bedeutet, dass die Anfrage die Authentifizierung erreicht hat).

**F: Gibt es einen Unterschied zwischen `/api/v1/messages` und `/claude/v1/messages`?**

A: Nein. Beide Präfixe werden auf das Anthropic-Messages-Protokoll geroutet – verwenden Sie das Präfix, das Ihr SDK standardmäßig nutzt. Unsere Dokumentation verwendet standardmäßig `/api`, da die meisten SDKs aus dem Claude-Umfeld dieses Präfix erwarten.

**F: Kann ich mit einem API-Key Claude, Codex und Gemini gleichzeitig nutzen?**

A: Ja. Keys sind protokollunabhängig; **das Protokoll wird über den Anfragepfad bestimmt**. `/api/v1/messages` steht für Anthropic, `/openai/v1/responses` für OpenAI Responses und `/gemini/v1beta/models/...` für Google Gemini.

**F: Sollte die `baseURL` für Gemini auf `/v1beta` enden oder nicht?**

A: Das hängt vom Tool ab. **Der `google`-Provider von OpenCode benötigt es** (setzen Sie `baseURL` auf `/gemini/v1beta`), da er `/v1beta/` nicht automatisch anhängt. **Gemini CLI und das `@google/genai`-SDK von Google benötigen es nicht** (setzen Sie die Base-URL auf `/gemini`) – das SDK hängt `/v1beta/` selbst an, und ein manuelles Hinzufügen würde `/gemini/v1beta/v1beta/...` ergeben und einen 404-Fehler zurückliefern.

**F: Welche Domain soll ich wählen?**

A: Festlandchina → `asia.qcode.cc` (Asien-Knoten: Korea / Taiwan / Hongkong, geringste Latenz) oder `api.qcode.cc` (globales Route 53); Nordamerika / Europa → `us.qcode.cc`. Wechseln Sie bei Bedarf frei zwischen den Ausweichdomains, falls Ihre primäre Domain hängt.

**F: Kann ich meinen eigenen Anfrageverlauf einsehen?**

A: Ja. Anfragen, die über eine beliebige Domain (`api.qcode.cc` / `asia.qcode.cc` / `us.qcode.cc`) gesendet werden, werden an [probe.qcode.cc](https://probe.qcode.cc) gemeldet. Geben Sie dort Ihren API-Key ein, um die Anfrageliste, Modelle, Tokens und mehr einzusehen.

**F: Soll ich in der BASE_URL einen abschließenden Schrägstrich angeben?**

A: **Nein**. Die meisten SDKs hängen Pfade wie `/v1/messages` automatisch an; ein abschließender Schrägstrich würde `//v1/messages` ergeben und einen 404-Fehler verursachen.