문서

빠른 시작

JoinGonka Gateway는 Gonka 모델에 액세스하기 위해 OpenAI 및 Anthropic API를 지원합니다. base_url 를 클라이언트에서 대체하면 모든 것이 작동합니다.

기본 URL: https://gate.joingonka.ai/v1

모델: MiniMaxAI/MiniMax-M2.7

인증: 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는 Anthropic Messages API(/v1/messages)를 네이티브로 지원합니다. Claude Code, Anthropic SDK 및 Anthropic 형식을 사용하는 모든 도구는 프록시 없이 직접 작동합니다.

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

스트리밍 (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)

도구 사용 (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?"}]
  }'

두 가지 형식(OpenAI 및 Anthropic) 모두 하나의 API 키와 하나의 잔액을 사용합니다.

API 엔드포인트

Inference

POST/v1/chat/completions

응답 생성 — OpenAI 형식 (스트리밍 지원)

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

응답 생성 — Anthropic 형식 (스트리밍, 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

사용 가능한 모델 목록

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

플러그인

플러그인은 API 기능을 확장합니다. 활성화하려면 요청에 plugins 배열을 전달하세요.

GET/v1/plugins

사용 가능한 플러그인 목록

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

요청에서 사용

json

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

web

Gonka 모델 내에서 직접 웹 검색. 모델 자체(Kimi, MiniMax, DeepSeek)에는 검색 기능이 없지만, gateway가 인터넷의 최신 결과를 컨텍스트에 주입하고 출처 인용을 반환합니다. stream 및 non-stream 모드에서 모두 작동합니다. 백엔드는 self-hosted이며, 귀하의 계정을 사용하여 타사 검색 API로 요청이 전송되지 않습니다.

방법 1 — plugins 배열의 web 객체 (옵션이 있는 결과 주입):

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

방법 2 — 에이전트 모드 (mode: "agent"): 검색이 필요할 때만 모델 자체가 web_search를 호출합니다:

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

옵션: max_results — 결과 개수 (기본값 5, 최대 10), search_prompt — 결과를 시작하기 전에 입력되는 자체 grounding 프롬프트.

응답에는 annotations[].url_citation(url, title)이 정보 제공 형식(OpenRouter 표준)으로 보완됩니다.

json

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

요금 안내: plugins 모드:[{ "id": "web" }] — 토큰 비용만 발생 (결과 포함 시 일반 prompt-tokens로 계산). 에이전트 모드 (mode: "agent") — 모든 루프 단계의 토큰과 web_search 호출 시마다 1000 nGNK 추가 요금 (1000회 검색당 ≈ $0.0001, 환율 1 GNK당 ~$0.15 기준).

privacy-sanitization과 함께 사용할 수 없습니다. 혼합 요청 시 400 오류를 반환합니다.

response-healing

잘린 JSON/구조화된 출력을 자동으로 복구합니다. JSON 콘텐츠가 있는 비스트리밍 요청에서만 작동합니다.

privacy-sanitization

모델에 전송하기 전에 메시지의 민감한 데이터(API 키, 이메일 주소, IP 주소, JWT, 카드 번호)를 마스킹합니다.

모드: redact([REDACTED]로 대체) 또는 tokenize([TOKEN_001]로 대체). 본문에 privacy_mode를 전달합니다.

file-parser

PDF 문서에서 텍스트를 추출합니다. data:application/pdf;base64,... 및 원시 base64를 지원합니다.

관리 키

SaaS 통합을 위한 계층적 API 키. 관리 키 (gm-)는 제한 및 TTL이 있는 하위 키 (gc-)를 생성합니다.

POST/api/management/keys

관리 키 (접두사 gm-)를 생성합니다. 하위 키 관리에만 사용됩니다.

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

선택 사항인 제한이 있는 하위 키 (접두사 gc-)를 생성합니다. 청구는 관리 키 소유자의 잔액에서 차감됩니다.

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

사용량 통계가 있는 하위 키 목록.

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

하위 키의 제한, RPM 또는 상태를 업데이트합니다.

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

하위 키를 비활성화합니다 (소프트 삭제).

Account

GET/api/balance

현재 잔액

json

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

GET/api/keys

API 키 목록

POST/api/keys

API 키 생성

DELETE/api/keys/:id

API 키 삭제

Billing

GET/api/usage

사용 통계

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

json

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

GET/api/deposits

입금 내역

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

거래 내역

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

요금 및 수수료 (공개, 인증 불필요)

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

stream: true인 경우, 응답은 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"}

오류

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

모델

Gonka 네트워크는 단일 API를 통해 여러 모델을 지원하며, 현재 목록은 언제든지 GET /v1/models 요청으로 확인할 수 있습니다. 모델을 선택하려면 요청 본문의 model 필드에 해당 ID를 전달하십시오.

모델	공급업체	컨텍스트	최대 출력	VRAM	상태
MiniMax M2.7	MiniMax	195K	8K	320 GB	사용 가능
Kimi K2.6	Moonshot AI	195K	8K	720 GB	사용 가능
DeepSeek V4 Flash	DeepSeek	371K	32K	280 GB	사용 가능

기본적으로 (model이 지정되지 않은 경우) 네트워크의 플래그십 모델이 사용됩니다. 메타데이터가 있는 현재 목록 — GET /v1/models.

모든 메타데이터를 포함한 현재 모델 목록 - GET /v1/models. Vision 및 멀티모달 입력 (image_url)은 업스트림 Gonka 네트워크에서 아직 지원되지 않습니다.

요금 및 수수료

완벽한 투명성: 아래에 모든 gateway 수수료가 나와 있습니다. 최신 값은 API에서 실시간으로 로드됩니다. 공개 엔드포인트 GET /api/pricing은 인증 없이 사용할 수 있습니다.

작업	수수료	참고
인퍼런스 마크업	10%	Gonka 네트워크 가격을 초과하는 플랫폼의 마크업으로, gateway의 주요 수입원입니다. 토큰 비용과 함께 매 요청 시 차감됩니다.
USDT를 통한 충전	5%	암호화폐(USDT)로 결제 시 결제 서비스 제공업체에서 차감합니다.
GNK를 통한 충전	무료	직접적인 GNK on-chain 송금은 gateway 수수료 없이 적립됩니다.
출금	5%	외부 주소로 GNK를 출금할 때 차감됩니다. 출금은 24-48시간 이내에 수동으로 처리됩니다.
현재 GNK 가격	$0.147	충전 및 잔액 계산에 기준이 되는 GNK/USD 환율입니다. 자동으로 업데이트됩니다.

GET /api/pricing

제한

모델: 모든 Gonka 네트워크 모델 (DevShards 다중 모델 아키텍처)

요청 제한: API 키 보유 시 요청 수에 고정된 제한이 없습니다 (네트워크 동시성으로 제한됨); 키 미보유 시에는 IP당 하루 20회 요청 가능 (스팸 방지)

최대 토큰: DeepSeek V4 Flash는 요청당 최대 32,768 토큰, 기타 모델은 최대 8,192 토큰까지 가능합니다(제한을 초과하는 값은 gateway에서 클리핑됩니다). 긴 응답의 경우 타임아웃을 방지하기 위해 stream:true를 사용하세요.

스트리밍: 지원됨 (SSE, stream: true)

네트워크 타임아웃: Gonka 네트워크가 요청을 수락했으나 300초 이내에 응답하지 않으면 요청이 504 오류로 종료되며, 프롬프트 처리는 추정치에 따라 차감됩니다. 네트워크가 수락한 요청은 취소할 수 없으며 노드는 이를 어떻게든 처리합니다. 타임아웃 시 Completion은 과금되지 않습니다. 긴 생성 작업에는 stream:true를 사용하십시오.