AI エージェント向け：セットアップの手順ガイド — /docs/agents.md、ドキュメントのインデックス — /llms.txt。

APIリファレンス

ゲートウェイへのリクエストに関するすべて：プロトコル、アドレス、キー、パラメータ。以下ではストリーミング、ツール呼び出し、推論、プラグイン、そしてレスポンスに含まれるリクエストのコストを解説します。

ゲートウェイはOpenAIとAnthropicのフォーマットを受け付けます。OpenAI SDKのベースURLはhttps://gate.joingonka.ai/v1コピー、Anthropic SDKはhttps://gate.joingonka.aiコピーです。すべてのプロトコルは1つのキーと1つの残高で動作し、どのフォーマットのリクエストも同じ経路を通ります。

リファレンスアドレス#

キーなしで応答します。コンテキストとステータスを含むモデル表はモデルセクションにあります。

Anthropic Messages#

• ベースURL — https://gate.joingonka.aiコピー：SDKが自動で/v1/messagesを追加します。
• キーはx-api-keyヘッダー（Anthropic SDKが送信する形式）またはAuthorization: Bearerで渡します。
• モデルclaude-*はゲートウェイが推奨モデル（MiniMaxAI/MiniMax-M2.7）に置き換えます。レスポンスのmodelフィールドにはクライアントが送った名前がそのまま残ります。
• max_tokensはAnthropic APIと同様に必須です。モデルの上限を超える場合は切り詰められます。
• ストリームはAnthropicのイベント形式。ポーズ中にゲートウェイはevent: pingを送り、障害はevent: errorイベントで通知されます。
• モデルの推論はレスポンスに含まれません：thinkingブロックはありません。
• 組み込みツールweb_searchはゲートウェイのウェブ検索プラグインが実行します — プラグインセクションを参照。
• トークン数カウント（/v1/messages/count_tokens）はありません — レスポンスは404。

Claude Codeはインストーラーで設定するのが簡単です — ツールの接続。手動の場合は環境変数で。ANTHROPIC_MODELでネットワークのモデルを固定できます。

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#

• ゲートウェイはレスポンスを保存しません：inputに履歴をすべて送ってください。previous_response_idとconversationフィールドはコード付きの400エラーになります。
• storeは受け付けられますが何も変わりません。
• ツール：functionとweb_search — 後者はウェブ検索プラグインが実行します。その他の組み込みツールはゲートウェイがスキップし、リクエストはそれらなしで実行されます。tool_choiceでそのようなツールを要求すると400エラーになります。
• input_imageとinput_fileパートは400エラー：ネットワークのモデルはテキストのみ扱います。
• ステート関連のルート（GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact）はコード付きの404を返します — ゲートウェイはレスポンスを保存しません。
• Codex CLI：model_providerに独自のプロバイダーidを設定してください（openai以外）。そうすればCodexが/v1/responses/compactなしで履歴を自ら圧縮します。

Legacy Completions#

• promptは文字列または1つの文字列の配列。レスポンスはchoices[].textに含まれます。複数のプロンプトやテキストの代わりのトークンは400エラーになります。
• suffixはプロンプト内のヒントとしてモデルに渡されます：ネットワークには本当のmid-fill機能はありません。
• レスポンスにはlogprobs: nullが含まれます。best_ofは無視されます。echoは動作します。

キーはAuthorization: Bearer jg-…またはx-api-key: jg-…ヘッダーで渡します — すべてのアドレスで同じです。キーはgate.joingonka.ai/keysページで登録後に作成します。

• マイページで各キーに日次・月次・累計の支出リミットを設定できます。超過時は402 child_key_limit_exceeded。
• キーごとの1分あたりのリクエスト数には上限があります — 値はレート制限セクションにあります。
• キーなしで動作するのはサイト上のデモチャットのみです：自分のコードからキーなしでリクエストするとis_demo付きの402が返ります。
• キーの管理はマイページでのみ可能です：APIキーを使った/api/keysはアクセスできません。残高とキーごとの消費はアカウントAPIで確認できます。

同じリクエストを4つのSDKで。モデルは推奨のMiniMaxAI/MiniMax-M2.7、キーは環境変数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)

ストリーミング応答#

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のパラメータ — 機能レスポンスのsupported_parametersリスト:

• temperatureがない場合、ゲートウェイは0.7を適用します。
• max_tokensがない場合、ゲートウェイはモデルのデフォルトを適用します。非ストリームでは短め、ストリームではモデルの上限。モデルごとの数値はレート制限を参照。

そのままネットワークに転送#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body。ゲートウェイは検証しません。ネットワークのリスト外の値は400エラー（タイプapi_error）になります。

ネットワークに転送されない#

その他のフィールドはゲートウェイが受け取りますが、ネットワークには転送しません — 例えばuser, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options。ストリームでのusageは常に届きます。

• stream: true — SSEイベントとしての応答。最後のイベントはdata: [DONE]。
• 完了前にusageを含むチャンクが届きます — stream_optionsがなくても常に。
• ポーズ中、ゲートウェイは15秒ごとにコメント: keep-aliveを送信します — SSEクライアントはこれをスキップします。
• ストリームが開く前は、拒否は通常のレスポンスコードで返ります。開いた後はjoingonka-errorチャンクで返ります。
• delta.tool_callsでは1チャンクにつき1回の呼び出し。ネットワークが連結した呼び出しはゲートウェイが分割します。

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]

ゲートウェイの制御チャンク#

idフィールドで識別できます:

他プロトコルでのストリーム#

• Anthropic Messages: message_startからmessage_stopまでのイベント、ポーズ中はevent: ping、障害はevent: error。
• OpenAI Responses: イベントresponse.*、障害はresponse.failed。
• Legacy Completions: 障害時はdata: {"error": …}、その後[DONE]。

• OpenAI形式: toolsとtool_choice。旧形式のfunctionsとfunction_callも受け付けます — 応答も同じ形式で返ります。
• ストリームでは1チャンクにつき1回の呼び出し。最初の要素だけを読むクライアントも呼び出しを失いません。
• ネットワークが400エラーを返すような履歴をゲートウェイが修正します: developerロールはsystemになり、空または重複する呼び出しIDにはユニークなIDが付与され、argumentsがオブジェクトの場合はJSON文字列に変換され、欠落したtypeが補完され、名前のない呼び出しは結果と共に削除されます。
• モデルがテキスト内のマークアップで書いた呼び出しは、ゲートウェイがtool_callsに移します。ツールなしのリクエストへの応答内の偽の呼び出しは削除します。
• 引数の途中で生成が中断された場合、tool_callsではなくfinish_reason: lengthが届きます: 応答の上限を増やしてください。

{
  "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の制約#

ツールスキーマとresponse_formatはネットワークが文法にコンパイルします。正規表現はRE2エンジンです。ゲートウェイはスキーマをネットワークが受け入れる形式に整えます:

• $refはその場で展開され、$defsとdefinitionsセクションは削除されます。再帰参照は制約なしのスキーマになります。
• RE2にない構文（先読み・後読み、後方参照、アトミックグループ、独占的量指定子）を含むpatternは削除されます。1000を超える繰り返しは1000に短縮されます。
• 定数からなるanyOfとoneOfはenumに折りたたまれます。折りたたみ不可能なブランチが16を超える場合、unionは削除されます。

response_format: {"type": "json_object"} — 有効なJSONとして応答、{"type": "json_schema", "json_schema": {"name": …, "schema": …}} — 上記の制約付きのあなたのスキーマに従って。ストリームなしで切り詰められたJSONは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"]
      }
    }
  }
}

• モデルの推論は応答とは別に届きます: message.reasoning_content、ストリームではdelta.reasoning_content。reasoningフィールドはゲートウェイがこの形式にリネームします。
• 推論はmax_tokensを消費します。上限が小さいと、テキストの前で応答が途切れます（finish_reason: length）。
• 応答テキストがなく推論がある場合、ゲートウェイはそれをcontentに移します — ツール呼び出しを含む応答を除く。
• reasoning_effortとreasoning.effortはネットワークに転送されます。モデルに2つのモードしかない場合、ゲートウェイは値をそれらに変換します: noneとminimalはlowへ、それ以上はデフォルトの推論へ。
• ノードが値を拒否した場合、ゲートウェイはそれを下げて（maxとxhigh → high、minimal → low、それ以外はフィールドを削除）、リクエストを再試行します。
• /v1/messagesでは推論は転送されません — thinkingブロックはありません。

プラグインはpluginsフィールドで有効化します — 文字列の配列またはオプション付きオブジェクト。リストはGET /v1/plugins。

ウェブ検索#

• オプション: max_results — 1から10まで、デフォルト5; engine — エンジンのヒント; search_prompt — 結果の前のカスタムテキスト; enabled: false — 検索をオフ。
• ソース — message.annotations[].url_citation内; ストリームでは完了前のjoingonka-citationsチャンク。
• mode: "agent" — モデル自身が検索するかどうかと何を検索するかを決めます; max_searches — 1から5まで、デフォルト3。
• 課金：通常モードではトークンのみ（検索結果は入力トークンに含まれます）。エージェントモードでは全ステップのトークンに加え、実行された検索ごとに1000 nGNK（x_joingonka.web_search_surcharge_ngonka）がかかります。
• Anthropic MessagesとOpenAI Responsesでは、組み込みツールweb_searchが同じプラグインをエージェントモードで実行します。

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

非ストリーミングのレスポンスは、リクエストのコストをusageに含めて返します：

• ストリーミングではusageにトークンのみが含まれ、コストはチャンクjoingonka-metaに入ります。
• ヘッダーx-joingonka-meta: 1を付けると、レスポンスPOST /v1/chat/completionsにブロックx_joingonkaが追加されます：コスト（cost_ngonka）、請求後の残高（balance_ngonka、非ストリーミングのみ）、タイミング（ttft_ms）。他のプロトコルはこのブロックを返しません。
• x-request-idはリクエストIDです。サポートへの問い合わせの際に添付してください。
• Retry-Afterは429とともに返されます。再試行までに待つべき秒数を示します。
• ヘッダーX-TitleとHTTP-Referer（OpenRouterと同様）は、ゲートウェイがお客様のアプリを識別するのに役立ちます。テキストは保存されません。

• 画像：image_urlパートはテキストのプレースホルダーに置き換えられます。モデルは画像を見ることができません（機能のvision: false）。
• ブラウザからのAPIアクセスはJoinGonkaのドメインのみ許可されています（Originチェック）。サーバー側から呼び出し、キーをフロントエンドに置かないでください。
• エンベディング：POST /v1/embeddingsは501を返します。ネットワークにエンベディングモデルがありません。
• エラーコード、制限、タイムアウトはエラーと制限セクションをご覧ください。