Untuk agen AI: panduan pengaturan langkah demi langkah — /docs/agents.md, indeks dokumentasi — /llms.txt.

Referensi API

Segala hal tentang permintaan ke gateway: protokol, alamat, kunci, dan parameter. Di bawah ini — streaming, pemanggilan tool, penalaran, plugin, dan biaya permintaan di dalam respons.

Gateway menerima format OpenAI dan Anthropic. Alamat dasar untuk SDK OpenAI adalah https://gate.joingonka.ai/v1Salin, untuk SDK Anthropic — https://gate.joingonka.aiSalin. Semua protokol berjalan dengan satu kunci dan satu saldo: permintaan dalam format apa pun menempuh jalur yang sama.

Alamat referensi#

Merespons tanpa kunci. Tabel model dengan konteks dan status ada di bagian Model.

Anthropic Messages#

• Alamat dasar — https://gate.joingonka.aiSalin: SDK akan menambahkan /v1/messages sendiri.
• Kunci — di header x-api-key (seperti yang dikirim SDK Anthropic) atau Authorization: Bearer.
• Model claude-* digantikan gateway dengan model yang direkomendasikan (MiniMaxAI/MiniMax-M2.7); di field model respons tetap tersimpan nama yang dikirim klien.
• max_tokens wajib diisi, seperti di API Anthropic; melebihi plafon model — akan dipotong.
• Stream — event Anthropic; saat jeda gateway mengirim event: ping, kegagalan datang sebagai event event: error.
• Penalaran model tidak muncul di respons: tidak ada blok thinking.
• Alat bawaan web_search dijalankan oleh plugin pencarian web gateway — lihat bagian Plugin.
• Tidak ada penghitungan token (/v1/messages/count_tokens) — respons 404.

Claude Code lebih mudah dikonfigurasi dengan installer — koneksi alat. Secara manual — lewat variabel lingkungan; ANTHROPIC_MODEL mengunci model jaringan.

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#

• Gateway tidak menyimpan respons: kirim seluruh riwayat di input. Field previous_response_id dan conversation — error 400 dengan kode.
• store diterima dan tidak mengubah apa pun.
• Alat: function dan web_search — yang terakhir dijalankan oleh plugin pencarian web. Alat bawaan lain dilewati gateway dan permintaan dijalankan tanpanya; meminta alat seperti itu lewat tool_choice — error 400.
• Bagian input_image dan input_file — error 400: model jaringan bekerja dengan teks.
• Alamat state (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) merespons 404 dengan kode — gateway tidak menyimpan respons.
• Codex CLI: tentukan id provider Anda sendiri di model_provider (bukan openai) — maka Codex memadatkan riwayat sendiri, tanpa /v1/responses/compact.

Legacy Completions#

• prompt — string atau array berisi satu string; respons ada di choices[].text. Beberapa prompt atau token alih-alih teks — error 400.
• suffix dikirim ke model sebagai petunjuk dalam prompt: jaringan tidak melakukan pengisian tengah (fill-in-the-middle) yang sebenarnya.
• Respons berisi logprobs: null; best_of diabaikan; echo berfungsi.

Kunci dikirim melalui header Authorization: Bearer jg-… atau x-api-key: jg-… — di semua alamat. Kunci dibuat setelah mendaftar di halaman gate.joingonka.ai/keys.

• Setiap kunci di dashboard dapat diberi batas pengeluaran harian, bulanan, dan total; jika terlampaui — 402 child_key_limit_exceeded.
• Jumlah permintaan per menit per kunci dibatasi — nilainya ada di bagian Batas.
• Tanpa kunci, hanya chat demo di situs yang berfungsi: permintaan tanpa kunci dari kode Anda akan mendapat 402 dengan is_demo.
• Kunci hanya dikelola di dashboard: /api/keys dengan kunci API tidak dapat diakses. Saldo dan pengeluaran per kunci — API akun.

Satu permintaan yang sama di empat SDK. Model — yang direkomendasikan (MiniMaxAI/MiniMax-M2.7), kunci — dari variabel lingkungan JOINGONKA_API_KEY.

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)

Respons streaming#

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)

Parameter POST /v1/chat/completions yang dijamin sendiri oleh gateway — daftar supported_parameters pada respons kapabilitas:

• Tanpa temperature, gateway menyisipkan 0.7.
• Tanpa max_tokens, gateway menyisipkan default model: tanpa stream — lebih pendek, dalam stream — plafon model. Angka per model — di bagian Batas.

Diteruskan ke jaringan apa adanya#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. Gateway tidak memeriksanya: nilai di luar daftar jaringan — error 400 dengan tipe api_error.

Tidak diteruskan ke jaringan#

Kolom lainnya diterima gateway tetapi tidak diteruskan ke jaringan — misalnya user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage dalam stream selalu datang.

• stream: true — respons berupa event SSE; event terakhir — data: [DONE].
• Sebelum selesai, sebuah chunk dengan usage datang — selalu, bahkan tanpa stream_options.
• Saat jeda, gateway setiap 15 dtk mengirim komentar : keep-alive — klien SSE melewatinya.
• Selama stream belum dibuka, penolakan datang lewat kode respons biasa; setelah dibuka — lewat chunk joingonka-error.
• Dalam delta.tool_calls — satu panggilan per chunk: panggilan yang digabung jaringan dipotong oleh gateway.

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]

Chunk layanan gateway#

Bisa dikenali dari kolom id:

Stream di protokol lain#

• Anthropic Messages: event dari message_start hingga message_stop, saat jeda event: ping, gagal — event: error.
• OpenAI Responses: event response.*, gagal — response.failed.
• Legacy Completions: saat gagal — data: {"error": …}, lalu [DONE].

• Format OpenAI: tools dan tool_choice. Format lama functions dan function_call juga diterima — respons akan datang dalam format yang sama.
• Dalam stream — satu panggilan per chunk: klien yang hanya membaca elemen pertama tidak kehilangan panggilan.
• Riwayat yang akan membuat jaringan mengembalikan error 400 diperbaiki gateway: peran developer menjadi system, id panggilan yang kosong dan duplikat mendapat id unik, arguments berupa objek diubah menjadi string JSON, type yang hilang dilengkapi, panggilan tanpa nama dihapus bersama hasilnya.
• Panggilan yang ditulis model sebagai markup dalam teks dipindahkan gateway ke tool_calls; panggilan palsu dalam respons terhadap permintaan tanpa alat akan dihapus.
• Generasi terputus di tengah argumen — yang datang adalah finish_reason: length, bukan tool_calls: tingkatkan batas respons.

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

Batasan JSON-Schema#

Skema alat dan response_format dikompilasi jaringan menjadi tata bahasa; ekspresi reguler — oleh mesin RE2. Gateway menyesuaikan skema ke bentuk yang diterima jaringan:

• $ref dijabarkan di tempat, bagian $defs dan definitions dihapus; referensi rekursif menjadi skema tanpa batasan.
• pattern dengan konstruksi yang tidak ada di RE2 (lookahead dan lookbehind, backreference, grup atomik, kuantifier posesif) dihapus; pengulangan lebih dari 1000 dipangkas menjadi 1000.
• anyOf dan oneOf dari konstanta dilipat menjadi enum; jika cabang yang tidak bisa dilipat lebih dari 16, gabungan dihapus.

response_format: {"type": "json_object"} — respons JSON valid, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} — sesuai skema Anda dengan batasan di atas. JSON terpotong tanpa stream diperbaiki oleh plugin response-healing.

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

• Penalaran model datang terpisah dari respons: message.reasoning_content, dalam stream — delta.reasoning_content. Kolom reasoning diganti nama gateway ke format ini.
• Penalaran menghabiskan max_tokens: dengan batas kecil, respons terputus (finish_reason: length) bahkan sebelum teks.
• Jika tidak ada teks respons tetapi ada penalaran, gateway memindahkannya ke content — kecuali respons dengan pemanggilan alat.
• reasoning_effort dan reasoning.effort diteruskan ke jaringan. Jika model hanya punya dua mode, gateway menyesuaikan nilainya: none dan minimal → low, yang lebih tinggi → penalaran default.
• Jika node menolak nilai, gateway menurunkannya (max dan xhigh → high, minimal → low, jika tidak kolomnya dihapus) dan mengulang permintaan.
• Dalam /v1/messages, penalaran tidak diteruskan — tidak ada blok thinking.

Plugin diaktifkan lewat kolom plugins — array string atau objek dengan opsi. Daftarnya — GET /v1/plugins.

Pencarian web#

• Opsi: max_results — dari 1 hingga 10, default 5; engine — petunjuk mesin; search_prompt — teks sendiri sebelum hasil; enabled: false — matikan pencarian.
• Sumber — di message.annotations[].url_citation; dalam stream — lewat chunk joingonka-citations sebelum selesai.
• mode: "agent" — model sendiri yang memutuskan apakah perlu mencari dan apa; max_searches — dari 1 hingga 5, default 3.
• Penagihan: pada mode biasa — hanya token (hasil pencarian termasuk dalam token input); pada mode agen — token dari semua langkah ditambah 1000 nGNK untuk setiap pencarian yang dilakukan (x_joingonka.web_search_surcharge_ngonka).
• Di Anthropic Messages dan OpenAI Responses, alat bawaan web_search menjalankan plugin yang sama dalam mode agen.

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

Respons non-streaming menyertakan biaya permintaan di usage:

• Dalam streaming, usage hanya berisi token; biaya ada di chunk joingonka-meta.
• Dengan header x-joingonka-meta: 1, respons POST /v1/chat/completions mendapatkan blok x_joingonka: biaya (cost_ngonka), saldo setelah debit (balance_ngonka, hanya non-streaming), dan timing (ttft_ms). Protokol lain tidak mengembalikan blok ini.
• x-request-id — ID permintaan: sertakan ini saat menghubungi dukungan.
• Retry-After disertakan dengan 429: sekian detik untuk menunggu sebelum mencoba lagi.
• Header X-Title dan HTTP-Referer (seperti di OpenRouter) membantu gateway mengenali aplikasi Anda; isinya tidak disimpan.

• Gambar: bagian image_url diganti dengan placeholder teks — model tidak bisa melihat gambarnya (vision: false di kemampuan).
• Dari browser, API hanya dapat diakses dari domain JoinGonka (pemeriksaan Origin): panggil dari server Anda sendiri, jangan taruh kunci di frontend.
• Embedding: POST /v1/embeddings mengembalikan 501 — tidak ada model embedding di jaringan.
• Kode error, batas, dan timeout — di bagian Error dan batas.