Yapay zeka ajanları için: adım adım kurulum kılavuzu — /docs/agents.md, dokümantasyon dizini — /llms.txt.

API referansı

Gateway'e yapılan isteklerle ilgili her şey: protokoller, adresler, anahtarlar ve parametreler. Aşağıda — streaming, araç çağırma, akıl yürütme, eklentiler ve yanıttaki istek maliyeti.

Ağ geçidi OpenAI ve Anthropic formatlarını kabul eder. OpenAI SDK için temel adres https://gate.joingonka.ai/v1Kopyala, Anthropic SDK için https://gate.joingonka.aiKopyala. Tüm protokoller tek anahtar ve tek bakiyeyle çalışır: herhangi bir formattaki istek aynı yoldan gider.

Referans adresler#

Anahtar olmadan yanıt verir. Bağlam ve durum içeren model tablosu Modeller bölümünde.

Anthropic Messages#

• Temel adres – https://gate.joingonka.aiKopyala: SDK /v1/messages yolunu kendisi ekler.
• Anahtar x-api-key başlığında (Anthropic SDK böyle gönderir) veya Authorization: Bearer başlığında.
• claude-* modellerini ağ geçidi önerilenle (MiniMaxAI/MiniMax-M2.7) değiştirir; yanıttaki model alanında istemcinin gönderdiği ad kalır.
• max_tokens Anthropic API'sinde olduğu gibi zorunludur; modelin tavanını aşan kısım kesilir.
• Akış – Anthropic olayları; duraklamalarda ağ geçidi event: ping gönderir, hata event: error olayı olarak gelir.
• Modelin düşünceleri yanıta girmez: thinking blokları yok.
• Yerleşik web_search aracını ağ geçidinin web arama eklentisi çalıştırır – bkz. Eklentiler bölümü.
• Token sayımı (/v1/messages/count_tokens) yok – yanıt 404.

Claude Code'u kurulum betiğiyle yapılandırmak daha kolay – araçları bağlama. Elle ortam değişkenleriyle; ANTHROPIC_MODEL ağ modelini sabitler.

export ANTHROPIC_BASE_URL=https://gate.joingonka.ai
export ANTHROPIC_AUTH_TOKEN=$JOINGONKA_API_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: $JOINGONKA_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?"}]
  }'

OpenAI Responses#

• Ağ geçidi yanıtları saklamaz: tüm geçmişi input içinde gönder. previous_response_id ve conversation alanları – kodlu 400 hatası.
• store kabul edilir ve hiçbir şeyi değiştirmez.
• Araçlar: function ve web_search – ikincisini web arama eklentisi çalıştırır. Diğer yerleşik araçları ağ geçidi atlar ve istek onlarsız yürütülür; tool_choice ile böyle bir aracı zorunlu kılmak – 400 hatası.
• input_image ve input_file parçaları – 400 hatası: ağdaki modeller metinle çalışır.
• Durum adresleri (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) kodlu 404 ile yanıt verir – ağ geçidi yanıtları saklamaz.
• Codex CLI: model_provider içinde kendi sağlayıcı id'ni belirle (openai değil) – o zaman Codex geçmişi /v1/responses/compact olmadan kendisi sıkıştırır.

Legacy Completions#

• prompt – bir dize veya tek dizeden oluşan dizi; yanıt choices[].text içinde. Birden çok prompt veya metin yerine token – 400 hatası.
• suffix modele prompt içinde ipucu olarak iletilir: ağda gerçek bir orta doldurma (mid-fill) yok.
• Yanıtta logprobs: null; best_of yok sayılır; echo çalışır.

Anahtar Authorization: Bearer jg-… veya x-api-key: jg-… başlığında iletilir – tüm adreslerde. Anahtar gate.joingonka.ai/keys sayfasında kaydolduktan sonra oluşturulur.

• Hesaptaki her anahtara günlük, aylık ve toplam harcama limiti tanımlanabilir; aşım – 402 child_key_limit_exceeded.
• Anahtar başına dakikadaki istek sayısı sınırlıdır – değerler Limitler bölümünde.
• Anahtar olmadan yalnızca sitedeki demo sohbet çalışır: kendi kodundan anahtarsız bir istek is_demo içeren 402 alır.
• Anahtarlar yalnızca hesaptan yönetilir: API anahtarıyla /api/keys erişilemez. Anahtar bazında bakiye ve harcama – API hesabı.

Aynı istek dört SDK'da. Model önerilen model (MiniMaxAI/MiniMax-M2.7), anahtar ise JOINGONKA_API_KEY ortam değişkeninden alınır.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gate.joingonka.ai/v1",
  apiKey: process.env.JOINGONKA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
});
console.log(response.choices[0].message.content);

curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key=os.environ["JOINGONKA_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)

Akış yanıtı#

import os
from openai import OpenAI

client = OpenAI(base_url="https://gate.joingonka.ai/v1", api_key=os.environ["JOINGONKA_API_KEY"])

stream = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gate.joingonka.ai/v1", apiKey: process.env.JOINGONKA_API_KEY });

const stream = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

curl -N https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}],
    "stream": true
  }'

import os
import anthropic

client = anthropic.Anthropic(base_url="https://gate.joingonka.ai", api_key=os.environ["JOINGONKA_API_KEY"])

with client.messages.stream(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

POST /v1/chat/completions parametrelerinden ağ geçidinin kendisinin garanti ettiği alanlar – yetenekler yanıtındaki supported_parameters listesi:

• temperature olmadan ağ geçidi 0.7 değerini koyar.
• max_tokens olmadan ağ geçidi modelin varsayılanını koyar: akış yoksa daha kısa, akışta modelin tavanı. Modellere göre sayılar Limitler bölümünde.

Ağa olduğu gibi iletilir#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. Ağ geçidi bunları denetlemez: ağın listesinde olmayan bir değer api_error tipinde 400 hatasına yol açar.

Ağa iletilmez#

Diğer alanları ağ geçidi kabul eder ama ağa iletmez – örneğin user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. Akışta usage her zaman gelir.

• stream: true – yanıt SSE olayları olarak; son olay data: [DONE].
• Tamamlanmadan önce usage içeren bir chunk gelir – her zaman, stream_options olmasa bile.
• Duraklamalarda ağ geçidi her 15 sn'de : keep-alive yorumunu gönderir – SSE istemcileri bunu atlar.
• Akış açılana kadar ret normal yanıt koduyla gelir; açıldıktan sonra joingonka-error chunk'ı olarak.
• delta.tool_calls içinde – chunk başına bir çağrı: ağın birleştirdiği çağrıları ağ geçidi yeniden ayırır.

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2,"total_tokens":14}}

data: [DONE]

Ağ geçidinin servis chunk'ları#

Bunlar id alanından tanınır:

Diğer protokollerde akış#

• Anthropic Messages: message_start ile message_stop arası olaylar, duraklamalarda event: ping, arıza – event: error.
• OpenAI Responses: response.* olayları, arıza – response.failed.
• Legacy Completions: arızada – data: {"error": …}, ardından [DONE].

• OpenAI formatı: tools ve tool_choice. Eski format functions ve function_call de kabul edilir – yanıt da aynı formatta gelir.
• Akışta – chunk başına bir çağrı: yalnızca ilk öğeyi okuyan istemciler çağrıları kaybetmez.
• Ağın 400 hatası vereceği geçmişleri ağ geçidi onarır: developer rolü system olur, boş ve yinelenen çağrı id'leri benzersiz değer alır, nesne olarak arguments JSON dizesine dönüşür, eksik type tamamlanır, adı olmayan çağrı sonucuyla birlikte kaldırılır.
• Modelin metin içinde biçimlendirme olarak yazdığı çağrıyı ağ geçidi tool_calls içine taşır; araçsız bir isteğin yanıtındaki sahte çağrıları kaldırır.
• Üretim argümanların ortasında koptu – tool_calls değil finish_reason: length gelir: yanıt limitini artırın.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

JSON-Schema kısıtlamaları#

Araç şemalarını ve response_format ağ bir dilbilgisine derler; düzenli ifadeleri RE2 motoruyla. Ağ geçidi şemayı ağın kabul edeceği biçime getirir:

• $ref yerinde açılır, $defs ve definitions bölümleri kaldırılır; özyinelemeli referans kısıtlamasız bir şemaya dönüşür.
• RE2'de bulunmayan yapılar içeren pattern (ileri ve geri bakış, geri referanslar, atomik gruplar, sahiplenici niceleyiciler) kaldırılır; 1000 üzeri tekrarlar 1000 değerine indirilir.
• Sabitlerden oluşan anyOf ve oneOf enum içine katlanır; katlanamayan dal sayısı 16 aşarsa birleşim kaldırılır.

response_format: {"type": "json_object"} – yanıt geçerli JSON olarak, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} – yukarıdaki kısıtlamalarla kendi şemanıza göre. Akışsız kırpılmış JSON'u response-healing eklentisi onarır.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "Name three planets."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "planets",
      "schema": {
        "type": "object",
        "properties": {"planets": {"type": "array", "items": {"type": "string"}}},
        "required": ["planets"]
      }
    }
  }
}

• Modelin akıl yürütmesi yanıttan ayrı gelir: message.reasoning_content, akışta – delta.reasoning_content. reasoning alanını ağ geçidi bu formata yeniden adlandırır.
• Akıl yürütme max_tokens harcar: küçük limitte yanıt daha metne geçmeden kopar (finish_reason: length).
• Yanıt metni yoksa ama akıl yürütme varsa ağ geçidi bunları content içine taşır – araç çağrısı olan yanıtlar hariç.
• reasoning_effort ve reasoning.effort ağa iletilir. Modelin yalnızca iki modu varsa ağ geçidi değeri bunlara uyarlar: none ve minimal → low, daha yüksekleri → varsayılan akıl yürütme.
• Bir düğüm değeri reddederse ağ geçidi onu düşürür (max ve xhigh → high, minimal → low, aksi halde alanı kaldırır) ve isteği yineler.
• /v1/messages içinde akıl yürütme iletilmez – thinking blokları yoktur.

Eklentiler plugins alanıyla etkinleştirilir – dize dizisi ya da seçenekli nesneler olarak. Liste – GET /v1/plugins.

Web araması#

• Seçenekler: max_results – 1 ile 10 arası, varsayılan 5; engine – arama motoru ipucu; search_prompt – sonuçlardan önce kendi metniniz; enabled: false – aramayı kapat.
• Kaynaklar – message.annotations[].url_citation içinde; akışta – tamamlanmadan önce joingonka-citations chunk'ı olarak.
• mode: "agent" – model arayıp aramayacağına ve neyi arayacağına kendisi karar verir; max_searches – 1 ile 5 arası, varsayılan 3.
• Ücretlendirme: normal modda yalnızca token'lar (arama sonuçları giriş token'larına dahildir); ajan modunda tüm adımların token'ları artı yapılan her arama için 1000 nGNK (x_joingonka.web_search_surcharge_ngonka).
• Anthropic Messages ve OpenAI Responses'ta yerleşik web_search aracı, aynı eklentiyi ajan modunda çalıştırır.

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "max_results": 5}]
}

{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "mode": "agent", "max_searches": 3}]
}

Stream'siz yanıt, isteğin maliyetini usage içinde taşır:

• Stream'de usage yalnızca token'ları içerir; maliyet joingonka-meta chunk'ında bulunur.
• x-joingonka-meta: 1 başlığıyla birlikte POST /v1/chat/completions yanıtı bir x_joingonka bloğu alır: maliyet (cost_ngonka), tahsilat sonrası bakiye (balance_ngonka, yalnızca stream'siz) ve zamanlamalar (ttft_ms). Diğer protokoller bu bloğu vermez.
• x-request-id — istek kimliği: destek talebinize ekleyin.
• Retry-After, 429 ile birlikte gelir: yeniden denemeden önce bu kadar saniye bekleyin.
• X-Title ve HTTP-Referer başlıkları (OpenRouter'daki gibi) ağ geçidinin uygulamanızı tanımasına yardımcı olur; içerikleri saklanmaz.

• Görseller: image_url parçaları bir metin yer tutucusuyla değiştirilir — model görseli görmez (yeteneklerde vision: false).
• API'ye tarayıcıdan yalnızca JoinGonka alan adlarından erişilebilir (Origin kontrolü): kendi sunucunuzdan çağırın, anahtarı ön uca koymayın.
• Embedding'ler: POST /v1/embeddings 501 yanıtı verir — ağda embedding modeli yok.
• Hata kodları, limitler ve zaman aşımları Hatalar ve Limitler bölümünde.