الوثائق

بدء سريع

تدعم بوابة Gonka AI واجهة برمجة تطبيقات OpenAI و Anthropic للوصول إلى نماذج Gonka. استبدل base_url في عميلك — وكل شيء يعمل.

عنوان URL الأساسي: https://gate.joingonka.ai/v1

النموذج: MiniMaxAI/MiniMax-M2.7

المصادقة: Bearer YOUR_API_KEY

بايثون (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)

تايب سكريبت (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 بشكل طبيعي 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

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 (تدفق، استخدام الأدوات)

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. الخلفية (backend) هي self-hosted: لا يتم إرسال الطلبات إلى واجهات برمجة تطبيقات بحث تابعة لجهات خارجية باستخدام حسابك.

الطريقة 1 — كائن الويب في مصفوفة المكونات الإضافية (حقن النتائج مع الخيارات):

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" }] — للرموز فقط (تُحتسب النتائج المضافة كرموز مطالبة عادية). وضع الوكيل (mode: "agent") — رموز جميع خطوات الدورة بالإضافة إلى رسوم إضافية قدرها 1000 nGNK لكل استدعاء web_search (≈ $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,... و raw base64.

مفاتيح الإدارة

مفاتيح API هرمية لعمليات تكامل SaaS. يقوم مفتاح الإدارة (gm-) بإنشاء مفاتيح فرعية (gc-) بحدود و TTL.

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. لاختيار نموذج، مرر معرفه (ID) في حقل model في متن الطلب.

النموذج	المورد	السياق	الحد الأقصى للإخراج	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. لا يتم دعم الرؤية والإدخال المتعدد الوسائط (image_url) بعد بواسطة شبكة Gonka الأولية.

الأسعار والرسوم

شفافية كاملة: فيما يلي جميع رسوم gateway. يتم تحميل القيم الحالية مباشرة من الـ API — نقطة النهاية العامة GET /api/pricing متاحة دون مصادقة.

العملية	الرسوم	ملاحظة
هامش إضافي على inference	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، لا يتم تحديد عدد الطلبات بشكل ثابت (الأمر يعتمد على تزامنية الشبكة)؛ وبدون مفتاح — 20 طلبًا يوميًا لكل عنوان IP (لمكافحة البريد العشوائي)

الحد الأقصى للتوكنات: ما يصل إلى 32,768 توكن لكل طلب لنموذج DeepSeek V4 Flash وما يصل إلى 8,192 للنماذج الأخرى (يتم اقتطاع القيم التي تتجاوز الحد بواسطة gateway). للاستجابات الطويلة، استخدم stream:true لتجنب انقضاء مهلة الطلب.

البث: مدعوم (SSE, stream: true)

مهلة الشبكة: إذا قبلت شبكة Gonka الطلب ولكنها لم تستجب خلال 300 ثانية، فسينتهي الطلب بخطأ 504، ويتم خصم معالجة المطالبة (prompt) بناءً على التقدير: لا يمكن إلغاء الطلب الذي قبلته الشبكة، حيث يقوم العقد (node) بمعالجته في كل الأحوال. لا تتم محاسبة Completion عند حدوث انتهاء المهلة. بالنسبة للتوليدات الطويلة، استخدم stream:true.