面向 AI 智能体：配置分步指南 — /docs/agents.md，文档索引 — /llms.txt。

API 参考

关于网关请求的一切：协议、地址、密钥和参数。下文涵盖流式传输、工具调用、推理、插件以及响应中的请求费用。

网关接受 OpenAI 和 Anthropic 格式。OpenAI SDK 的基地址为 https://gate.joingonka.ai/v1复制，Anthropic SDK 为 https://gate.joingonka.ai复制。所有协议共用同一密钥和同一余额：任何格式的请求都走同一条路径。

发现地址#

无需密钥即可访问。带上下文和状态的模型表见 模型 章节。

Anthropic Messages#

• 基地址——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 由网关的网络搜索插件执行——参见 插件 章节。
• 不支持 token 计数（/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 为字符串或包含单个字符串的数组；响应在 choices[].text 中。多个提示词或用 token 代替文本会返回错误 400。
• suffix 会作为提示词中的提示传给模型：网络并不真正支持中间填充。
• 响应中包含 logprobs: null；best_of 被忽略；echo 可用。

密钥通过 Authorization: Bearer jg-… 或 x-api-key: jg-… 请求头传递——适用于所有地址。密钥需在 gate.joingonka.ai/keys 页面注册后创建。

• 在控制台中可以为每个密钥设置日、月和总消费限额；超出后返回 402 child_key_limit_exceeded。
• 每个密钥每分钟的请求数有限制——具体数值见 限制 章节。
• 只有网站上的演示聊天无需密钥即可使用：从你自己的代码发起的无密钥请求将返回 402 及 is_demo。
• 密钥只能在控制台中管理：带 API 密钥访问 /api/keys 不可用。密钥的余额和消费——账户 API。

同一个请求在四种 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。网关不校验这些参数：值不在网络支持的列表中，会返回类型为 api_error 的 400 错误。

不传给网络#

其余字段网关会接收但不传给网络——例如 user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options。流式响应中 usage 始终会返回。

• stream: true 表示以 SSE 事件形式返回的响应；最后一个事件是 data: [DONE]。
• 结束前会先返回一个包含 usage 的 chunk——始终如此，即使没有 stream_options。
• 在暂停期间，网关每 15 秒发送一条注释 : keep-alive——SSE 客户端会忽略它。
• 在流打开之前，失败会以普通响应码返回；流打开之后，则以包含 joingonka-error 的 chunk 返回。
• 在 delta.tool_calls 中，每个 chunk 只含一个调用：网络粘连在一起的调用，网关会将其拆开。

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#

可通过 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 格式同样受支持——响应也会以该格式返回。
• 在流式中，每个 chunk 只含一个调用：只读取第一个元素的客户端不会丢失调用。
• 网络会以 400 错误拒绝的历史记录，网关会进行修复：developer 角色变为 system，空的和重复的调用 id 会被赋予唯一值，对象形式的 arguments 会转换为 JSON 字符串，缺失的 type 会被补全，没有名称的调用会连同其结果一起被移除。
• 模型以文本标记形式写出的调用，网关会将其移入 tool_calls；在未提供工具的请求响应中出现的虚假调用会被移除。
• 生成在参数中途中断——会返回 finish_reason: length，而不是 tool_calls：请提高回答上限。

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

工具 schema 和 response_format 由网络编译为语法；正则表达式使用 RE2 引擎。网关会将 schema 规范化为网络可接受的形式：

• $ref 会就地展开，$defs 和 definitions 部分会被删除；递归引用会变为一个无约束的 schema。
• 含有 RE2 不支持结构（前后瞻、反向引用、原子组、占有量词）的 pattern 会被移除；超过 1000 的重复次数会被缩减为 1000。
• 由常量组成的 anyOf 和 oneOf 会被折叠为 enum；如果不可折叠的分支超过 16 个，则整个联合会被移除。

response_format：{"type": "json_object"} 返回合法 JSON，{"type": "json_schema", "json_schema": {"name": …, "schema": …}} 按你的 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 会传给网络。如果模型只有两种模式，网关会把值映射到这两种：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 chunk 中。
• mode: "agent" —— 由模型自行决定是否搜索以及搜索什么；max_searches —— 从 1 到 5，默认 3。
• 计费：标准模式下仅计 token（搜索结果计入输入 token）；Agent 模式下按所有步骤的 token 计费，另加每次执行的搜索 1000 nGNK（x_joingonka.web_search_surcharge_ngonka）。
• 在 Anthropic Messages 和 OpenAI Responses 中，内置工具 web_search 以 Agent 模式运行同一插件。

{
  "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 只包含 token；费用在 joingonka-meta 数据块中。
• 带 x-joingonka-meta: 1 请求头时，POST /v1/chat/completions 响应会附带 x_joingonka 数据块：费用（cost_ngonka）、扣费后余额（balance_ngonka，仅非流式）以及耗时（ttft_ms）。其他协议不返回该数据块。
• x-request-id 是请求标识：联系技术支持时请附上它。
• Retry-After 随 429 返回：需等待这么多秒后再重试。
• X-Title 和 HTTP-Referer 请求头（与 OpenRouter 相同）可帮助网关识别你的应用；其内容不会被保存。

• 图像：image_url 部分会被替换为文本占位符——模型看不到图片（能力中的 vision: false）。
• 浏览器中仅可从 JoinGonka 域名访问 API（校验 Origin）：请从你自己的服务器调用，切勿把密钥放进前端。
• 嵌入：POST /v1/embeddings 返回 501——网络中暂无嵌入模型。
• 错误码、限流与超时详见 错误与速率限制 章节。