Tài liệu

Bắt đầu nhanh

Gonka AI Gateway hỗ trợ OpenAI và Anthropic API để truy cập các mô hình Gonka. Thay thế base_url trong ứng dụng khách của bạn - và mọi thứ hoạt động.

URL cơ sở: https://gate.joingonka.ai/v1

Mô hình: MiniMaxAI/MiniMax-M2.7

Xác thực: 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)

Gonka Gateway hỗ trợ nguyên bản Anthropic Messages API (/v1/messages). Claude Code, Anthropic SDK và bất kỳ công cụ nào sử dụng định dạng Anthropic đều hoạt động trực tiếp - không cần 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)

Sử dụng công cụ (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?"}]
  }'

Cả hai định dạng (OpenAI và Anthropic) đều sử dụng một khóa API và một số dư.

Điểm cuối API

Inference

POST/v1/chat/completions

Tạo phản hồi - định dạng OpenAI (hỗ trợ 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

Tạo phản hồi - định dạng 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

Danh sách các mô hình có sẵn

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 mở rộng khả năng của API. Truyền một mảng plugin trong yêu cầu để kích hoạt.

GET/v1/plugins

Danh sách các plugin có sẵn

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

Sử dụng trong yêu cầu

json

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

web

Tìm kiếm web trực tiếp trong các mô hình Gonka. Bản thân các mô hình (Kimi, MiniMax, DeepSeek) không có tính năng tìm kiếm; gateway sẽ chèn các kết quả mới nhất từ internet vào ngữ cảnh và trả về các trích dẫn nguồn. Hoạt động ở cả chế độ stream và non-stream. Backend là self-hosted: các yêu cầu không gửi tới các API tìm kiếm bên thứ ba bằng tài khoản của bạn.

Phương pháp 1 — đối tượng web trong mảng plugins (tiêm kết quả với các tùy chọn):

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

Phương pháp 2 — Chế độ Agent (mode: "agent"): mô hình tự gọi web_search chỉ khi cần tìm kiếm:

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

Tùy chọn: max_results — số lượng kết quả (mặc định là 5, tối đa 10); search_prompt — lời nhắc định hướng (grounding prompt) của riêng bạn trước các kết quả nhận được.

Phản hồi được làm phong phú nhờ annotations[].url_citation (url, title) — chuẩn định dạng của OpenRouter:

json

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

Phí: chế độ plugins:[{ "id": "web" }] — chỉ tính phí token (các kết quả được trộn vào được tính là prompt-tokens thông thường). Chế độ đại lý (mode: "agent") — token của tất cả các bước vòng lặp cộng thêm phí phụ thu 1000 nGNK cho mỗi lần gọi web_search (≈ $0.0001 cho 1000 lượt tìm kiếm với tỷ giá ~$0.15 mỗi GNK).

Không tương thích với privacy-sanitization: liên kết yêu cầu đồng thời sẽ trả về lỗi 400.

response-healing

Tự động sửa chữa JSON/đầu ra có cấu trúc bị cắt. Chỉ hoạt động cho các yêu cầu không streaming với nội dung JSON.

privacy-sanitization

Che giấu dữ liệu nhạy cảm (khóa API, email, địa chỉ IP, JWT, số thẻ) trong thông báo trước khi gửi đến mô hình.

Chế độ: redact (thay thế bằng [REDACTED]) hoặc tokenize (thay thế bằng [TOKEN_001]). Truyền privacy_mode trong body.

file-parser

Trích xuất văn bản từ tài liệu PDF. Hỗ trợ data:application/pdf;base64,... và raw base64.

Management Keys

Khóa API phân cấp cho tích hợp SaaS. Khóa quản lý (gm-) tạo khóa con (gc-) với giới hạn và TTL.

POST/api/management/keys

Tạo khóa quản lý (tiền tố gm-). Chỉ được sử dụng để quản lý khóa con.

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

Tạo khóa con (tiền tố gc-) với các giới hạn tùy chọn. Thanh toán được ghi nợ từ số dư của chủ sở hữu khóa quản lý.

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

Danh sách khóa con với thống kê sử dụng.

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

Cập nhật giới hạn, RPM hoặc trạng thái của khóa con.

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

Hủy kích hoạt khóa con (xóa mềm).

Account

GET/api/balance

Số dư hiện tại

json

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

GET/api/keys

Danh sách khóa API

POST/api/keys

Tạo khóa API

DELETE/api/keys/:id

Xóa khóa API

Billing

GET/api/usage

Thống kê sử dụng

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

json

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

GET/api/deposits

Lịch sử nạp tiền

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

Lịch sử giao dịch

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

Giá cả và phí (công khai, không cần xác thực)

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

Khi stream: true, phản hồi được gửi theo từng phần qua 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"}

Lỗi

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

Mô hình

Mạng Gonka hỗ trợ nhiều mô hình thông qua một API duy nhất — danh sách hiện tại luôn có thể được truy xuất bằng yêu cầu GET /v1/models. Để chọn một mô hình, hãy truyền ID của nó vào trường model trong phần thân yêu cầu.

Mô hình	Nhà cung cấp	Ngữ cảnh	Đầu ra tối đa	VRAM	Trạng thái
MiniMax M2.7	MiniMax	195K	8K	320 GB	Có sẵn
Kimi K2.6	Moonshot AI	195K	8K	720 GB	Có sẵn
DeepSeek V4 Flash	DeepSeek	371K	32K	280 GB	Có sẵn

Theo mặc định (nếu model không được chỉ định), mô hình hàng đầu của mạng được sử dụng. Danh sách hiện tại với siêu dữ liệu — GET /v1/models.

Danh sách các mô hình hiện tại với tất cả siêu dữ liệu - GET /v1/models. Vision và đầu vào đa phương tiện (image_url) chưa được mạng Gonka thượng nguồn hỗ trợ.

Giá cả và phí

Hoàn toàn minh bạch: dưới đây là tất cả các loại phí của gateway. Các giá trị thực tế được tải trực tiếp từ API — điểm cuối công khai GET /api/pricing có sẵn mà không cần xác thực.

Thao tác	Phí	Ghi chú
Mức phí chênh lệch cho inference	10%	Mức phí chênh lệch của nền tảng vượt quá giá mạng Gonka — nguồn doanh thu chính của gateway. Được khấu trừ cho mỗi yêu cầu cùng với chi phí của các token.
Nạp tiền qua USDT	5%	Được khấu trừ bởi nhà cung cấp thanh toán khi thanh toán bằng tiền mã hóa (USDT).
Nạp tiền qua GNK	miễn phí	Chuyển khoản GNK trực tiếp on-chain được ghi nhận mà không mất phí gateway.
Rút tiền	5%	Được khấu trừ khi rút GNK về địa chỉ bên ngoài. Việc rút tiền được xử lý thủ công trong vòng 24–48 giờ.
Giá GNK hiện tại	$0.147	Tỷ giá GNK/USD được sử dụng để tính toán các khoản nạp và số dư. Được cập nhật tự động.

GET /api/pricing

Giới hạn

Mô hình: Tất cả các mô hình mạng Gonka (kiến trúc đa mô hình DevShards)

Giới hạn yêu cầu: với khóa API, số lượng yêu cầu không bị giới hạn cố định (bị giới hạn bởi sự đồng thời của mạng); không có khóa — 20/ngày trên mỗi IP (chống spam)

Tối đa token: lên đến 32.768 token mỗi yêu cầu cho DeepSeek V4 Flash và tối đa 8.192 cho các mô hình khác (các giá trị vượt quá giới hạn sẽ bị gateway cắt bớt). Đối với phản hồi dài, hãy sử dụng stream:true để tránh hết thời gian chờ.

Streaming: được hỗ trợ (SSE, stream: true)

Thời gian chờ mạng: Nếu mạng Gonka đã chấp nhận yêu cầu nhưng không phản hồi trong vòng 300 giây, yêu cầu sẽ kết thúc với lỗi 504 và quá trình xử lý prompt sẽ bị trừ theo ước tính: yêu cầu đã được mạng chấp nhận không thể hủy bỏ, node vẫn xử lý nó trong mọi trường hợp. Completion không bị tính phí khi xảy ra timeout. Đối với các thế hệ dài, hãy sử dụng stream:true.