Documentação

Início Rápido

JoinGonka Gateway suporta OpenAI e Anthropic API para acesso aos modelos Gonka. Substitua base_url no seu cliente e tudo funcionará.

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

Modelo: MiniMaxAI/MiniMax-M2.7

Autenticação: 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 suporta nativamente a API de Mensagens da Anthropic (/v1/messages). Claude Code, Anthropic SDK e quaisquer ferramentas que usem o formato Anthropic funcionam diretamente - sem 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)

Uso de ferramentas (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?"}]
  }'

Ambos os formatos (OpenAI e Anthropic) usam uma única chave API e um único saldo.

Endpoints da API

Inference

POST/v1/chat/completions

Geração de resposta - formato OpenAI (streaming suportado)

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

Geração de resposta - 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

Lista de modelos disponíveis

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

Plugins

Plugins estendem as capacidades da API. Passe um array de plugins na requisição para ativá-los.

GET/v1/plugins

Lista de plugins disponíveis

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

Uso na requisição

json

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

web

Pesquisa web diretamente nos modelos Gonka. Os modelos em si (Kimi, MiniMax, DeepSeek) não possuem pesquisa; o gateway injeta resultados recentes da internet no contexto e retorna citações de fontes. Funciona em modo stream e non-stream. O backend é self-hosted: as solicitações não são enviadas para APIs de pesquisa de terceiros usando sua conta.

Método 1 — objeto web no array de plugins (injeção de resultados com opções):

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

Método 2 — Modo Agente (mode: "agent"): o próprio modelo chama web_search apenas quando a pesquisa é necessária:

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

Opções: max_results — número de resultados (padrão 5, máximo 10); search_prompt — seu próprio prompt de grounding que antecede os resultados.

A resposta é enriquecida com annotations[].url_citation (url, title) — padrão OpenRouter:

json

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

Tarifas: modo plugins:[{ "id": "web" }] — apenas por tokens (resultados agregados contam como prompt-tokens normais). Modo agente (mode: "agent") — tokens de todos os passos do ciclo mais uma sobretaxa de 1000 nGNK por cada chamada de web_search (≈ $0.0001 por 1000 pesquisas a uma taxa de ~$0.15 por GNK).

Incompatível com privacy-sanitization: uma solicitação conjunta retornará 400.

response-healing

Correção automática de JSON/saída estruturada truncada. Funciona apenas para requisições não-streaming com conteúdo JSON.

privacy-sanitization

Mascaramento de dados sensíveis (chaves API, e-mails, endereços IP, JWT, números de cartão) em mensagens antes de enviar para o modelo.

Modos: redact (substituir por [REDACTED]) ou tokenize (substituir por [TOKEN_001]). Passe privacy_mode no corpo.

file-parser

Extração de texto de documentos PDF. Suporte para data:application/pdf;base64,... e base64 bruto.

Chaves de Gerenciamento

Chaves API hierárquicas para integrações SaaS. A chave de gerenciamento (gm-) cria chaves filhas (gc-) com limites e TTL.

POST/api/management/keys

Crie uma chave de gerenciamento (prefixo gm-). Usada apenas para gerenciar chaves filhas.

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

Crie uma chave filha (prefixo gc-) com limites opcionais. A cobrança é feita no saldo do proprietário da chave de gerenciamento.

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 de chaves filhas com estatísticas de uso.

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

Atualize os limites, RPM ou status de uma chave filha.

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

Desative uma chave filha (exclusão lógica).

Account

GET/api/balance

Saldo atual

json

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

GET/api/keys

Lista de chaves API

POST/api/keys

Criar chave API

DELETE/api/keys/:id

Excluir chave API

Billing

GET/api/usage

Estatísticas de uso

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

json

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

GET/api/deposits

Histórico de depósitos

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

Histórico de transações

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

Tarifas e comissões (público, sem autorização)

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

Com stream: true, a resposta chega em chunks via 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"}

Erros

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

Modelos

A rede Gonka suporta vários modelos através de uma API única — a lista atual pode ser sempre obtida através de uma solicitação GET /v1/models. Para selecionar um modelo, passe o seu ID no campo model do corpo da solicitação.

Modelo	Fornecedor	Contexto	Saída máxima	VRAM	Status
MiniMax M2.7	MiniMax	195K	8K	320 GB	Disponível
Kimi K2.6	Moonshot AI	195K	8K	720 GB	Disponível
DeepSeek V4 Flash	DeepSeek	371K	32K	280 GB	Disponível

Por padrão (se o model não for especificado) é usado o modelo carro-chefe da rede. A lista atual com metadados — GET /v1/models.

A lista atual de modelos com todos os metadados - GET /v1/models. Visão e entrada multimodal (image_url) ainda não são suportadas pela rede Gonka upstream.

Tarifas e comissões

Transparência total: abaixo estão todas as comissões do gateway. Os valores atuais são carregados em tempo real da API — o endpoint público GET /api/pricing está disponível sem autorização.

Operação	Comissão	Observação
Margem de inferência	10%	Margem da plataforma acima do preço da rede Gonka — principal fonte de receita do gateway. Cobrada a cada requisição junto com o custo dos tokens.
Depósito via USDT	5%	Cobrado pelo provedor de pagamento ao pagar com cripto (USDT).
Depósito via GNK	grátis	A transferência direta de GNK on-chain é creditada sem comissão de gateway.
Saque de fundos	5%	Cobrado ao retirar GNK para um endereço externo. O saque é processado manualmente em até 24–48 horas.
Preço atual do GNK	$0.147	A taxa GNK/USD usada para calcular depósitos e saldo. Atualizada automaticamente.

GET /api/pricing

Limites

Modelos: Todos os modelos da rede Gonka (arquitetura multi-modelo DevShards)

Limite de solicitações: com chave API o número de requisições não é limitado de forma fixa (limitado pela concorrência da rede); sem chave — 20/dia por IP (anti-spam)

Máx. tokens: até 32.768 tokens por solicitação para DeepSeek V4 Flash e até 8.192 para outros modelos (valores que excedem o limite são cortados pelo gateway). Para respostas longas, use stream:true para evitar timeouts.

Streaming: suportado (SSE, stream: true)

Timeout de rede: Se a rede Gonka aceitou a requisição mas não respondeu em 300 segundos, a requisição termina com um erro 504 e o processamento do prompt é debitado com base na estimativa: uma requisição aceita pela rede não pode ser cancelada, o nó a processa de qualquer maneira. Completion não é cobrado em caso de timeout. Para gerações longas, use stream:true.