Für KI-Agenten: Schritt-für-Schritt-Anleitung zur Einrichtung — /docs/agents.md, Dokumentationsindex — /llms.txt.

API-Referenz

Alles zu Anfragen an das Gateway: Protokolle, Adressen, Schlüssel und Parameter. Unten — Streaming, Tool-Aufrufe, Reasoning, Plugins und die Kosten einer Anfrage in der Antwort.

Das Gateway akzeptiert die Formate von OpenAI und Anthropic. Die Basis-URL für das OpenAI SDK ist https://gate.joingonka.ai/v1Kopieren, für das Anthropic SDK https://gate.joingonka.aiKopieren. Alle Protokolle nutzen denselben Schlüssel und dasselbe Guthaben: Eine Anfrage in jedem Format nimmt denselben Weg.

Referenzadressen#

Antworten ohne Schlüssel. Die Modelltabelle mit Kontext und Status findest du im Abschnitt Modelle.

Anthropic Messages#

• Basis-URL – https://gate.joingonka.aiKopieren: Das SDK fügt /v1/messages selbst hinzu.
• Der Schlüssel steht im Header x-api-key (so sendet das Anthropic SDK) oder Authorization: Bearer.
• Die Modelle claude-* ersetzt das Gateway durch das empfohlene (MiniMaxAI/MiniMax-M2.7); im Feld model der Antwort bleibt der Name, den der Client gesendet hat.
• max_tokens ist Pflicht, wie in der Anthropic API; mehr als das Limit des Modells wird abgeschnitten.
• Stream – Anthropic-Events; in Pausen sendet das Gateway event: ping, ein Fehler kommt als Event event: error.
• Die Überlegungen des Modells erscheinen nicht in der Antwort: thinking-Blöcke gibt es nicht.
• Das integrierte Tool web_search führt das Websuche-Plugin des Gateways aus – siehe Abschnitt Plugins.
• Eine Token-Zählung (/v1/messages/count_tokens) gibt es nicht – Antwort 404.

Claude Code lässt sich am einfachsten mit dem Installer einrichten – Tools verbinden. Manuell über Umgebungsvariablen; ANTHROPIC_MODEL legt das Netzwerk-Modell fest.

export ANTHROPIC_BASE_URL=https://gate.joingonka.ai
export ANTHROPIC_AUTH_TOKEN=$JOINGONKA_API_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: $JOINGONKA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'

OpenAI Responses#

• Das Gateway speichert keine Antworten: Sende den gesamten Verlauf in input mit. Die Felder previous_response_id und conversation – Fehler 400 mit Code.
• store wird akzeptiert und ändert nichts.
• Tools: function und web_search – letzteres führt das Websuche-Plugin aus. Andere integrierte Tools überspringt das Gateway, und die Anfrage wird ohne sie ausgeführt; ein solches Tool über tool_choice zu verlangen – Fehler 400.
• Die Teile input_image und input_file – Fehler 400: Die Netzwerk-Modelle arbeiten mit Text.
• Die Zustands-Adressen (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) antworten mit 404 und Code – Antworten speichert das Gateway nicht.
• Codex CLI: Lege deine eigene Provider-id in model_provider fest (nicht openai) – dann komprimiert Codex den Verlauf selbst, ohne /v1/responses/compact.

Legacy Completions#

• prompt – ein String oder ein Array aus einem String; die Antwort steht in choices[].text. Mehrere Prompts oder Tokens statt Text – Fehler 400.
• suffix wird dem Modell als Hinweis im Prompt übergeben: Eine echte Mid-Fill-Funktion hat das Netzwerk nicht.
• In der Antwort steht logprobs: null; best_of wird ignoriert; echo funktioniert.

Der Schlüssel wird im Header Authorization: Bearer jg-… oder x-api-key: jg-… übergeben – an allen Adressen. Der Schlüssel wird nach der Registrierung auf der Seite gate.joingonka.ai/keys erstellt.

• Jedem Schlüssel im Konto kann ein Ausgabenlimit pro Tag, pro Monat und insgesamt zugewiesen werden; Überschreitung – 402 child_key_limit_exceeded.
• Die Anzahl der Anfragen pro Minute pro Schlüssel ist begrenzt – die Werte findest du im Abschnitt Limits.
• Ohne Schlüssel funktioniert nur der Demo-Chat auf der Website: Eine Anfrage ohne Schlüssel aus deinem eigenen Code erhält 402 mit is_demo.
• Schlüssel lassen sich nur im Konto verwalten: /api/keys mit API-Schlüssel ist nicht verfügbar. Guthaben und Verbrauch pro Schlüssel – API-Konto.

Dieselbe Anfrage in vier SDKs. Das Modell ist das empfohlene (MiniMaxAI/MiniMax-M2.7), der Schlüssel stammt aus der Umgebungsvariable JOINGONKA_API_KEY.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gate.joingonka.ai/v1",
  apiKey: process.env.JOINGONKA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
});
console.log(response.choices[0].message.content);

curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

message = client.messages.create(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(message.content[0].text)

Streaming-Antwort#

import os
from openai import OpenAI

client = OpenAI(base_url="https://gate.joingonka.ai/v1", api_key=os.environ["JOINGONKA_API_KEY"])

stream = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gate.joingonka.ai/v1", apiKey: process.env.JOINGONKA_API_KEY });

const stream = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

curl -N https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}],
    "stream": true
  }'

import os
import anthropic

client = anthropic.Anthropic(base_url="https://gate.joingonka.ai", api_key=os.environ["JOINGONKA_API_KEY"])

with client.messages.stream(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Parameter von POST /v1/chat/completions, die das Gateway selbst garantiert – die Liste supported_parameters in der Antwort der Fähigkeiten:

• Ohne temperature setzt das Gateway 0.7 ein.
• Ohne max_tokens setzt das Gateway den Standard des Modells ein: ohne Stream kürzer, im Stream die Obergrenze des Modells. Zahlen je Modell finden Sie im Abschnitt Limits.

Werden unverändert ans Netz übergeben#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. Das Gateway prüft sie nicht: Ein Wert außerhalb der Liste des Netzes führt zu Fehler 400 mit Typ api_error.

Werden nicht ans Netz übergeben#

Die übrigen Felder nimmt das Gateway an, übergibt sie aber nicht ans Netz – zum Beispiel user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage kommt im Stream immer mit.

• stream: true – Antwort als SSE-Events; das letzte Event ist data: [DONE].
• Vor dem Abschluss kommt ein Chunk mit usage – immer, auch ohne stream_options.
• In Pausen sendet das Gateway alle 15 s den Kommentar : keep-alive – SSE-Clients überspringen ihn.
• Solange der Stream nicht geöffnet ist, kommt die Ablehnung als normaler Antwortcode; danach als Chunk joingonka-error.
• Bei delta.tool_calls – ein Aufruf pro Chunk: Vom Netz zusammengeklebte Aufrufe trennt das Gateway wieder.

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2,"total_tokens":14}}

data: [DONE]

Service-Chunks des Gateways#

Sie sind am Feld id zu erkennen:

Stream in anderen Protokollen#

• Anthropic Messages: Events von message_start bis message_stop, in Pausen event: ping, Fehler – event: error.
• OpenAI Responses: Events response.*, Fehler – response.failed.
• Legacy Completions: bei Fehler – data: {"error": …}, danach [DONE].

• OpenAI-Format: tools und tool_choice. Das alte Format functions und function_call wird ebenfalls akzeptiert – die Antwort kommt im selben Format.
• Im Stream – ein Aufruf pro Chunk: Clients, die nur das erste Element lesen, verlieren keine Aufrufe.
• Verläufe, auf die das Netz mit Fehler 400 antworten würde, repariert das Gateway: Die Rolle developer wird zu system, leere und doppelte Aufruf-IDs erhalten eindeutige, arguments als Objekt wird in einen JSON-String umgewandelt, ein fehlender type wird ergänzt, ein Aufruf ohne Namen wird samt Ergebnis entfernt.
• Einen Aufruf, den das Modell als Markup im Text geschrieben hat, überführt das Gateway in tool_calls; falsche Aufrufe in einer Antwort auf eine Anfrage ohne Tools entfernt es.
• Die Generierung brach mitten in den Argumenten ab – es kommt finish_reason: length, nicht tool_calls: Erhöhen Sie das Antwortlimit.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

Einschränkungen von JSON-Schema#

Tool-Schemas und response_format kompiliert das Netz zu einer Grammatik; reguläre Ausdrücke – mit der RE2-Engine. Das Gateway bringt das Schema in eine Form, die das Netz akzeptiert:

• $ref werden an Ort und Stelle aufgelöst, die Abschnitte $defs und definitions entfernt; eine rekursive Referenz wird zu einem Schema ohne Einschränkungen.
• pattern mit Konstrukten, die es in RE2 nicht gibt (Lookahead und Lookbehind, Backreferences, atomare Gruppen, possessive Quantifizierer), wird entfernt; Wiederholungen über 1000 werden auf 1000 gekürzt.
• anyOf und oneOf aus Konstanten werden zu enum zusammengeführt; gibt es mehr nicht zusammenführbare Zweige als 16, wird die Vereinigung entfernt.

response_format: {"type": "json_object"} – Antwort als valides JSON, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} – nach Ihrem Schema mit den oben genannten Einschränkungen. Abgeschnittenes JSON ohne Stream repariert das Plugin response-healing.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "Name three planets."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "planets",
      "schema": {
        "type": "object",
        "properties": {"planets": {"type": "array", "items": {"type": "string"}}},
        "required": ["planets"]
      }
    }
  }
}

• Die Überlegungen des Modells kommen getrennt von der Antwort: message.reasoning_content, im Stream – delta.reasoning_content. Das Feld reasoning benennt das Gateway in dieses Format um.
• Überlegungen verbrauchen max_tokens: Bei einem kleinen Limit bricht die Antwort (finish_reason: length) noch vor dem Text ab.
• Gibt es keinen Antworttext, aber Überlegungen, überführt das Gateway sie in content – außer bei Antworten mit Tool-Aufruf.
• reasoning_effort und reasoning.effort werden ans Netz übergeben. Hat das Modell nur zwei Modi, passt das Gateway den Wert daran an: none und minimal → low, höhere → Reasoning nach Standard.
• Lehnt eine Node den Wert ab, stuft das Gateway ihn herab (max und xhigh → high, minimal → low, andernfalls wird das Feld entfernt) und wiederholt die Anfrage.
• In /v1/messages werden Überlegungen nicht übergeben – es gibt keine thinking-Blöcke.

Plugins werden über das Feld plugins aktiviert – als Array von Strings oder Objekten mit Optionen. Die Liste – GET /v1/plugins.

Websuche#

• Optionen: max_results – von 1 bis 10, Standard 5; engine – Hinweis auf die Suchmaschine; search_prompt – eigener Text vor den Ergebnissen; enabled: false – Suche deaktivieren.
• Quellen – in message.annotations[].url_citation; im Stream – als Chunk joingonka-citations vor dem Abschluss.
• mode: "agent" – das Modell entscheidet selbst, ob und wonach es sucht; max_searches – von 1 bis 5, Standard 3.
• Abrechnung: im Standardmodus nur Tokens (Suchergebnisse zählen zu den Eingabe-Tokens); im Agentenmodus die Tokens aller Schritte plus 1000 nGNK pro durchgeführter Suche (x_joingonka.web_search_surcharge_ngonka).
• In Anthropic Messages und OpenAI Responses führt das integrierte Tool web_search dasselbe Plugin im Agentenmodus aus.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "max_results": 5}]
}

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "mode": "agent", "max_searches": 3}]
}

Eine Antwort ohne Streaming liefert die Kosten der Anfrage in usage:

• Im Stream enthält usage nur Tokens; die Kosten stehen im Chunk joingonka-meta.
• Mit dem Header x-joingonka-meta: 1 erhält die Antwort POST /v1/chat/completions einen Block x_joingonka: Kosten (cost_ngonka), Kontostand nach Abbuchung (balance_ngonka, nur ohne Streaming) und Timings (ttft_ms). Andere Protokolle geben diesen Block nicht zurück.
• x-request-id — die Anfrage-ID: fügen Sie sie Ihrem Support-Ticket bei.
• Retry-After kommt mit 429: so viele Sekunden vor dem erneuten Versuch warten.
• Die Header X-Title und HTTP-Referer (wie bei OpenRouter) helfen dem Gateway, Ihre Anwendung zu erkennen; ihr Inhalt wird nicht gespeichert.

• Bilder: image_url-Teile werden durch einen Text-Platzhalter ersetzt — das Modell sieht das Bild nicht (vision: false in den Fähigkeiten).
• Aus dem Browser ist die API nur von JoinGonka-Domains aus erreichbar (Prüfung Origin): rufen Sie sie von Ihrem Server auf und legen Sie den Schlüssel nicht ins Frontend.
• Embeddings: POST /v1/embeddings antwortet mit 501 — es gibt keine Embedding-Modelle im Netzwerk.
• Fehlercodes, Limits und Timeouts finden Sie im Abschnitt Fehler und Limits.