Documentazione

Avvio rapido

JoinGonka Gateway supporta le API OpenAI e Anthropic per accedere ai modelli Gonka. Sostituisci base_url nel tuo client — e tutto funziona.

URL di base: https://gate.joingonka.ai/v1

Modello: MiniMaxAI/MiniMax-M2.7

Autorizzazione: 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 supporta nativamente l'API Anthropic Messages (/v1/messages). Claude Code, Anthropic SDK e qualsiasi strumento che utilizzi il formato Anthropic funzionano direttamente, senza 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?"}]
  }'

Entrambi i formati (OpenAI e Anthropic) utilizzano la stessa chiave API e lo stesso saldo.

Endpoint API

Inference

POST/v1/chat/completions

Generazione risposta - formato OpenAI (streaming supportato)

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

Generazione risposta - formato 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

Elenco modelli disponibili

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
    }
  }]
}

Plugin

I plugin migliorano le capacità dell'API. Passa un array di plugin nella richiesta per attivarli.

GET/v1/plugins

Elenco dei plugin disponibili

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

Utilizzo nella richiesta

json

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

web

Ricerca web direttamente all'interno dei modelli Gonka. I modelli stessi (Kimi, MiniMax, DeepSeek) non dispongono di ricerca; il gateway inserisce risultati freschi da Internet nel contesto e restituisce le citazioni delle fonti. Funziona in modalità stream e non-stream. Il backend è self-hosted: le richieste non vengono inviate ad API di ricerca di terze parti utilizzando il tuo account.

Metodo 1 – l'oggetto web nell'array plugins (iniezione di risultati con opzioni):

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:"
  }]
}

Metodo 2 – modalità agente (mode: "agent"): il modello chiama web_search solo quando è necessaria una ricerca:

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 }]
}

Opzioni: max_results — numero di risultati (default 5, max 10); search_prompt — il prompt di grounding preferito che anticipa i risultati.

La risposta è arricchita con annotations[].url_citation (url, title) — standard di OpenRouter:

json

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

Tariffazione: modalità plugins:[{ "id": "web" }] — solo per token (i risultati inclusi contano come normali prompt-token). Modalità agente (mode: "agent") — token di tutti i passaggi del ciclo più un supplemento di 1000 nGNK per ogni chiamata web_search (≈ $0.0001 per 1000 ricerche al tasso di ~$0.15 per GNK).

Non compatibile con privacy-sanitization: una richiesta congiunta restituirà 400.

response-healing

Riparazione automatica di JSON/output strutturato troncato. Funziona solo per richieste non in streaming con contenuto JSON.

privacy-sanitization

Mascheramento di dati sensibili (chiavi API, email, indirizzi IP, JWT, numeri di carta) nei messaggi prima dell'invio al modello.

Modalità: redact (sostituzione con [REDACTED]) o tokenize (sostituzione con [TOKEN_001]). Passa privacy_mode nel body.

file-parser

Estrazione di testo da documenti PDF. Supporta data:application/pdf;base64,... e raw base64.

Management Keys

Chiavi API gerarchiche per integrazioni SaaS. La Management Key (gm-) crea Child Keys (gc-) con limiti e TTL.

POST/api/management/keys

Crea una Management Key (prefisso gm-). Utilizzata solo per la gestione delle Child Keys.

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

Crea una Child Key (prefisso gc-) con limiti opzionali. La fatturazione viene addebitata al saldo del proprietario della Management Key.

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

Elenco delle Child Keys con statistiche di utilizzo.

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

Aggiorna limiti, RPM o stato della Child Key.

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

Disattiva una Child Key (soft delete).

Account

GET/api/balance

Saldo attuale

json

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

GET/api/keys

Elenco chiavi API

POST/api/keys

Crea chiave API

DELETE/api/keys/:id

Elimina chiave API

Billing

GET/api/usage

Statistiche di utilizzo

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

json

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

GET/api/deposits

Storico depositi

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

Storico transazioni

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

Tariffe e commissioni (pubblico, senza autorizzazione)

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

Per stream: true la risposta arriva a blocchi tramite 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"}

Errori

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"}}

Modelli

La rete Gonka serve diversi modelli tramite un'unica API; l'elenco aggiornato può sempre essere ottenuto tramite una richiesta GET /v1/models. Per selezionare un modello, passa il suo ID nel campo model del corpo della richiesta.

Modello	Fornitore	Contesto	Output massimo	VRAM	Stato
MiniMax M2.7	MiniMax	195K	8K	320 GB	Disponibile
Kimi K2.6	Moonshot AI	195K	8K	720 GB	Disponibile
DeepSeek V4 Flash	DeepSeek	371K	32K	280 GB	Disponibile

Per impostazione predefinita (se il model non è specificato) viene utilizzato il modello di punta della rete. L'elenco attuale con i metadati — GET /v1/models.

L'elenco attuale dei modelli con tutti i metadati - GET /v1/models. Vision e input multimodale (image_url) non sono ancora supportati dalla rete Gonka a monte.

Tariffe e commissioni

Massima trasparenza: di seguito sono riportate tutte le commissioni del gateway. I valori effettivi vengono caricati in tempo reale dall'API — l'endpoint pubblico GET /api/pricing è disponibile senza autorizzazione.

Operazione	Commissione	Nota
Markup sull'inference	10%	Markup della piattaforma in aggiunta al prezzo di rete di Gonka — la principale fonte di guadagno del gateway. Viene addebitato su ogni richiesta insieme al costo dei token.
Ricarica tramite USDT	5%	Trattenuto dal fornitore di servizi di pagamento in caso di pagamento in criptovaluta (USDT).
Ricarica tramite GNK	gratuito	Il trasferimento diretto di GNK on-chain viene accreditato senza commissioni del gateway.
Prelievo	5%	Trattenuto al momento del prelievo di GNK su un indirizzo esterno. Il prelievo viene elaborato manualmente entro 24-48 ore.
Prezzo corrente di GNK	$0.147	Tasso di cambio GNK/USD con cui vengono calcolati depositi e saldi. Si aggiorna automaticamente.

GET /api/pricing

Limiti

Modelli: Tutti i modelli della rete Gonka (architettura multi-modello DevShards)

Limite richieste: con la chiave API, il numero di richieste non è limitato in modo fisso (limitato dalla concorrenza della rete); senza chiave — 20 al giorno per IP (antispam)

Max token: fino a 32.768 token per richiesta per DeepSeek V4 Flash e fino a 8.192 per altri modelli (i valori che superano il limite vengono tagliati dal gateway). Per risposte lunghe, utilizzare stream:true per evitare timeout.

Streaming: supportato (SSE, stream: true)

Timeout di rete: Se la rete Gonka ha accettato la richiesta ma non ha risposto entro 300 secondi, la richiesta termina con un errore 504 e l'elaborazione del prompt viene addebitata in base alla stima: una richiesta accettata dalla rete non può essere annullata, il nodo la elabora comunque. Completion non viene addebitato in caso di timeout. Per generazioni lunghe, usa stream:true.