文档

快速入门

JoinGonka Gateway 支持 OpenAI 和 Anthropic API 访问 Gonka 模型。替换 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 功能。在请求中传递插件数组以激活。

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 — 插件数组中的 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 prompt。

响应中富含 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" }] — 仅收取 token 费用（附加的结果计入常规 prompt-tokens）。代理模式 (mode: "agent") — 所有循环步骤的 token 加上每次 web_search 调用 1000 nGNK 的附加费 (≈ $0.0001 每 1000 次搜索，汇率为 ~$0.15 每 GNK)。

与 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。上游 Gonka 网络尚不支持 Vision 和多模态输入 (image_url)。

资费与手续费

完全透明：以下为所有网关手续费。当前数值从 API 实时加载 — 公开端点 GET /api/pricing 无需授权即可访问。

操作	手续费	备注
推理加价	10%	在 Gonka 网络价格之上的平台加价 — 网关的主要收入来源。与 token 成本一起在每个请求中扣除。
通过 USDT 充值	5%	使用加密货币 (USDT) 支付时由支付服务商收取。
通过 GNK 充值	免费	直接 on-chain GNK 转账无网关手续费入账。
提现	5%	提现 GNK 至外部地址时收取。提现将在 24–48 小时内手动处理。
当前 GNK 价格	$0.147	用于计算充值和余额的 GNK/USD 汇率。自动更新。

GET /api/pricing

限制

模型： 所有 Gonka 网络模型 (DevShards 多模型架构)

请求限制: 使用 API 密钥时，请求次数没有固定限制（受网络并发性限制）；无密钥时 — 每个 IP 每天 20 次（防垃圾邮件）

最大令牌: DeepSeek V4 Flash 每个请求最多 32,768 个 token，其他模型最多 8,192 个（超过限制的值会被 gateway 截断）。对于长响应，请使用 stream:true 以避免超时。

流式传输: 支持 (SSE, stream: true)

网络超时： 如果 Gonka 网络已接受请求但在 300 秒内未响应，则请求将终止并返回 504 错误，Prompt 处理费用将按预估值扣除：网络已接受的请求无法取消，节点无论如何都会处理该请求。超时时的 Completion 不收费。对于长生成，请使用 stream:true。