Dokumentacja

Szybki start

JoinGonka Gateway obsługuje OpenAI i Anthropic API dla dostępu do modeli Gonka. Zastąp base_url w swoim kliencie — i wszystko działa.

Podstawowy URL: https://gate.joingonka.ai/v1

Model: MiniMaxAI/MiniMax-M2.7

Autoryzacja: Bearer YOUR_API_KEY

Python (OpenAI SDK)

python

from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Gonka?"},
    ],
    temperature=0.7,
    max_tokens=1024,
)

print(response.choices[0].message.content)

TypeScript (OpenAI SDK)

typescript

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is Gonka?" },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(response.choices[0].message.content);

cURL

bash

curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is Gonka?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Anthropic API (Claude Code)

JoinGonka Gateway natywnie obsługuje Anthropic Messages API (/v1/messages). Claude Code, Anthropic SDK i wszelkie narzędzia wykorzystujące format Anthropic działają bezpośrednio — bez proxy.

Claude Code

Recommended — set it up with one command (also configures OpenClaw and Cline):

bash

npx @joingonka/setup

Or configure it manually:

bash

export ANTHROPIC_BASE_URL=https://gate.joingonka.ai
export ANTHROPIC_API_KEY=YOUR_API_KEY
claude

Python (Anthropic SDK)

python

import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key="YOUR_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)

cURL (Anthropic format)

bash

curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: YOUR_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?"}
    ]
  }'

Streaming (Python)

python

import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key="YOUR_API_KEY",
)

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

Tool Use (cURL)

bash

curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get current weather",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }],
    "messages": [{"role": "user", "content": "Weather in Moscow?"}]
  }'

Oba formaty (OpenAI i Anthropic) używają jednego klucza API i jednego salda.

Punkty końcowe API

Inference

POST/v1/chat/completions

Generowanie odpowiedzi — format OpenAI (obsługiwane streaming)

json

{
  "id": "chatcmpl-abc123...",
  "object": "chat.completion",
  "model": "MiniMaxAI/MiniMax-M2.7",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?",
      "tool_calls": []
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  },
  "x_joingonka": {
    "cost_ngonka": "24",
    "balance_ngonka": "11999976"
  }
}

POST/v1/messages

Generowanie odpowiedzi — format Anthropic (streaming, tool_use)

json

{
  "id": "msg_abc123...",
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "Hello!"}],
  "model": "MiniMaxAI/MiniMax-M2.7",
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 8}
}

GET/v1/models

Lista dostępnych modeli

json

{
  "object": "list",
  "data": [{
    "id": "MiniMaxAI/MiniMax-M2.7",
    "object": "model",
    "owned_by": "gonka-network",
    "context_length": 200000,
    "pricing": {
      "prompt": "0.00000007",
      "completion": "0.0000001"
    },
    "architecture": {
      "modality": "text->text"
    },
    "top_provider": {
      "context_length": 200000,
      "max_completion_tokens": 8192,
      "is_moderated": false
    },
    "supported_parameters": [
      "temperature", "top_p", "tools",
      "tool_choice", "max_tokens", "stop"
    ],
    "x_gonka": {
      "v_ram": 320,
      "context_window": 200000,
      "max_output": 8192,
      "actual_cost_ngonka": 1.2
    }
  }]
}

Wtyczki

Wtyczki rozszerzają możliwości API. Przekaż tablicę plugins w żądaniu, aby aktywować.

GET/v1/plugins

Lista dostępnych wtyczek

json

{
  "plugins": [
    {"id": "web", "description": "Web search — inject fresh results with citations"},
    {"id": "response-healing", "description": "Auto-fix truncated JSON"},
    {"id": "privacy-sanitization", "description": "Mask sensitive data"},
    {"id": "file-parser", "description": "Extract text from PDF"}
  ]
}

Użycie w żądaniu

json

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "..."}],
  "plugins": ["response-healing", "privacy-sanitization"]
}

web

Wyszukiwanie w sieci bezpośrednio w modelach Gonka. Same modele (Kimi, MiniMax, DeepSeek) nie posiadają funkcji wyszukiwania; gateway wstrzykuje świeże wyniki z internetu do kontekstu i zwraca cytaty źródeł. Działa w trybach stream i non-stream. Backend jest self-hosted: zapytania nie są wysyłane do zewnętrznych API wyszukiwania przy użyciu Twojego konta.

Metoda 1 – obiekt web w tablicy plugins (wstrzykiwanie wyników z opcjami):

json

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

Metoda 2 – tryb agentowy (mode: "agent"): model sam wywołuje web_search tylko, gdy potrzebne jest wyszukiwanie:

json

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

Opcje: max_results — liczba wyników (domyślnie 5, maks 10); search_prompt — własny prompt uziemiający (grounding) poprzedzający wyniki.

Odpowiedź jest wzbogacana o annotations[].url_citation (url, title) — standard OpenRouter:

json

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "...",
      "annotations": [{
        "type": "url_citation",
        "url_citation": {
          "url": "https://gonka.ai/...",
          "title": "Gonka Network"
        }
      }]
    }
  }]
}

Taryfikacja: tryb plugins:[{ "id": "web" }] — tylko za tokeny (dołączone wyniki liczone są jako zwykłe prompt-tokeny). Tryb agentowy (mode: "agent") — tokeny wszystkich kroków cyklu plus dodatkowa opłata 1000 nGNK za każde wywołanie web_search (≈ $0.0001 za 1000 wyszukiwań przy kursie ~$0.15 za GNK).

Niezgodne z privacy-sanitization: jednoczesne żądanie zwróci błąd 400.

response-healing

Automatyczna naprawa obciętego JSON/strukturalnych danych wyjściowych. Działa tylko dla zapytań nie-streamujących z zawartością JSON.

privacy-sanitization

Maskowanie wrażliwych danych (klucze API, adresy e-mail, adresy IP, JWT, numery kart) w wiadomościach przed wysłaniem do modelu.

Tryby: redact (zastąpienie przez [REDACTED]) lub tokenize (zastąpienie przez [TOKEN_001]). Przekaż privacy_mode w body.

file-parser

Wyodrębnianie tekstu z dokumentów PDF. Obsługa data:application/pdf;base64,... i czystego base64.

Klucze Zarządzające

Hierarchiczne klucze API do integracji SaaS. Klucz zarządzający (gm-) tworzy klucze podrzędne (gc-) z limitami i TTL.

POST/api/management/keys

Utwórz klucz zarządzający (prefiks gm-). Używany tylko do zarządzania kluczami podrzędnymi.

POST/api/management/keys/:id/children

Utwórz klucz podrzędny (prefiks gc-) z opcjonalnymi limitami. Opłaty są pobierane z salda właściciela klucza zarządzającego.

json

{
  "name": "Client A",
  "limit_daily_ngonka": "1000000000",
  "limit_monthly_ngonka": "10000000000",
  "expires_at": "2026-04-01T00:00:00Z",
  "rate_limit_rpm": 30
}

GET/api/management/keys/:id/children

Lista kluczy podrzędnych ze statystykami użycia.

PUT/api/management/keys/:id/children/:childId

Aktualizuj limity, RPM lub status klucza podrzędnego.

DELETE/api/management/keys/:id/children/:childId

Dezaktywuj klucz podrzędny (usuwanie miękkie).

Account

GET/api/balance

Bieżące saldo

json

{
  "balance_ngonka": "11999976",
  "balance_usd": 0.008,
  "cost_per_token_ngonka": 1,
  "tokens_remaining": 11999976
}

GET/api/keys

Lista kluczy API

POST/api/keys

Utwórz klucz API

DELETE/api/keys/:id

Usuń klucz API

Billing

GET/api/usage

Statystyki wykorzystania

Query: period=day|week|month&tz=-180

json

{
  "period": "month",
  "usage": [{
    "date": "2026-03-20",
    "requests": 42,
    "tokens": 18500,
    "costNgonka": "22200"
  }]
}

GET/api/deposits

Historia depozytów

Query: limit=50&offset=0&from=2026-03-01&to=2026-03-21

json

{
  "deposits": [{
    "id": "abc-123",
    "type": "DEPOSIT_GNK",
    "amountNgonka": "10000000",
    "description": "GNK deposit via memo",
    "createdAt": "2026-03-20T12:00:00Z"
  }],
  "total": 3
}

GET/api/transactions

Historia transakcji

Query: limit=50&offset=0&type=INFERENCE&from=2026-03-01&to=2026-03-21

json

{
  "transactions": [{
    "id": "def-456",
    "type": "INFERENCE",
    "amountNgonka": "-1200",
    "feeNgonka": "120",
    "description": null,
    "createdAt": "2026-03-20T14:30:00Z"
  }],
  "total": 128
}

GET/api/pricing

Taryfy i prowizje (publiczny, bez autoryzacji)

json

{
  "deposit_usdt_fee_percent": 5,
  "deposit_gnk_fee_percent": 0,
  "usage_fee_percent": 10,
  "withdrawal_fee_percent": 5,
  "gnk_usd_price": 0.3465
}

Streaming & Errors

Jeśli stream: true, odpowiedź przychodzi w częściach poprzez SSE (Server-Sent Events).

OpenAI (stream: true)

text

data: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":"!"}}]}

data: {"choices":[],"x_joingonka":{"cost_ngonka":"24"}}

data: [DONE]

Anthropic (stream: true)

text

event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}

event: message_stop
data: {"type":"message_stop"}

Błędy

json

// 400 — неверный запрос
{"error": {"message": "...", "type": "invalid_request_error"}}

// 401 — не авторизован
{"error": {"message": "...", "type": "authentication_error"}}

// 402 — недостаточный баланс
{"error": {"message": "...", "type": "insufficient_funds", "balance_ngonka": "0"}}

// 429 — rate limit
{"error": {"message": "...", "type": "rate_limit_error"}}

// 502 — ошибка сети Gonka
{"error": {"message": "...", "type": "api_error"}}

Modele

Sieć Gonka obsługuje wiele modeli za pośrednictwem jednego API – aktualną listę zawsze można uzyskać za pomocą zapytania GET /v1/models. Aby wybrać model, prześlij jego ID w polu model w treści zapytania.

Model	Dostawca	Kontekst	Maks. wyjście	VRAM	Status
MiniMax M2.7	MiniMax	195K	8K	320 GB	Dostępny
Kimi K2.6	Moonshot AI	195K	8K	720 GB	Dostępny
DeepSeek V4 Flash	DeepSeek	371K	32K	280 GB	Dostępny

Domyślnie (jeśli model nie jest określony) używany jest flagowy model sieci. Aktualna lista z metadanymi — GET /v1/models.

Aktualna lista modeli ze wszystkimi metadanymi – GET /v1/models. Wejścia Vision i multimodalne (image_url) nie są jeszcze obsługiwane przez sieć Gonka upstream.

Taryfy i prowizje

Pełna przejrzystość: poniżej znajdują się wszystkie prowizje bramki. Aktualne wartości są ładowane na żywo z API – publiczny endpoint GET /api/pricing jest dostępny bez autoryzacji.

Operacja	Prowizja	Uwaga
Narzut na inferencję	10%	Narzut platformy powyżej ceny sieciowej Gonka — główne źródło dochodu bramki. Potrącany z każdego zapytania wraz z kosztem tokenów.
Doładowanie przez USDT	5%	Pobierane przez dostawcę płatności przy płatności kryptowalutą (USDT).
Doładowanie przez GNK	bezpłatnie	Bezpośredni transfer GNK on-chain jest księgowany bez prowizji bramki.
Wypłata środków	5%	Pobierane przy wypłacie GNK na zewnętrzny adres. Wypłata jest przetwarzana ręcznie w ciągu 24–48 godzin.
Aktualna cena GNK	$0.147	Kurs GNK/USD, według którego obliczane są depozyty i saldo. Aktualizowany automatycznie.

GET /api/pricing

Limity

Modele: Wszystkie modele sieci Gonka (architektura multi-modelowa DevShards)

Limit żądań: z kluczem API liczba żądań nie jest ściśle limitowana (limitowana przez współbieżność sieci); bez klucza — 20/dobę na IP (ochrona przed spamem)

Maks. tokenów: do 32 768 tokenów na żądanie dla DeepSeek V4 Flash i do 8 192 dla pozostałych modeli (wartości przekraczające limit są przycinane przez gateway). W przypadku długich odpowiedzi użyj stream:true, aby uniknąć przekroczenia limitu czasu.

Streaming: obsługiwane (SSE, stream: true)

Limit czasu sieci: Jeśli sieć Gonka zaakceptowała żądanie, ale nie odpowiedziała w ciągu 300 sekund, żądanie kończy się błędem 504, a przetwarzanie prompta jest odliczane według szacunków: żądanie zaakceptowane przez sieć nie może zostać anulowane, węzeł przetwarza je w każdym przypadku. Completion przy przekroczeniu limitu czasu nie jest obciążane kosztami. W przypadku długich generacji użyj stream:true.