AI 에이전트용: 단계별 설정 안내 — /docs/agents.md, 문서 인덱스 — /llms.txt.

API 레퍼런스

게이트웨이 요청에 관한 모든 것: 프로토콜, 주소, 키, 파라미터. 아래에서는 스트리밍, 도구 호출, 추론, 플러그인, 그리고 응답에 포함된 요청 비용을 다룹니다.

게이트웨이는 OpenAI와 Anthropic 형식을 모두 허용합니다. OpenAI SDK의 기본 URL은 https://gate.joingonka.ai/v1복사, Anthropic SDK는 https://gate.joingonka.ai복사입니다. 모든 프로토콜이 하나의 키와 하나의 잔액으로 작동하며, 어떤 형식의 요청이든 동일한 경로를 거칩니다.

레퍼런스 주소#

키 없이 응답합니다. 컨텍스트와 상태를 포함한 모델 표는 모델 섹션에 있습니다.

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에 자체 provider id를 설정하세요(openai 아님) — 그러면 Codex가 /v1/responses/compact 없이 스스로 기록을 압축합니다.

Legacy Completions#

• prompt는 문자열 또는 하나의 문자열 배열입니다; 응답은 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.
• 키당 분당 요청 수에 제한이 있습니다 — 값은 한도 섹션에 있습니다.
• 키 없이 작동하는 것은 사이트의 데모 채팅뿐입니다: 자체 코드에서 키 없이 요청하면 is_demo와 함께 402가 반환됩니다.
• 키 관리는 마이페이지에서만 가능합니다: 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. 게이트웨이는 이를 검증하지 않습니다. 네트워크 목록 밖의 값은 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에서는 청크당 한 번의 호출. 네트워크가 합친 호출은 게이트웨이가 분리합니다.

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도 허용됩니다 — 응답도 같은 형식으로 옵니다.
• 스트림에서는 청크당 한 번의 호출. 첫 번째 요소만 읽는 클라이언트도 호출을 잃지 않습니다.
• 네트워크가 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는 네트워크로 전달됩니다. 모델에 두 가지 모드만 있으면 게이트웨이가 값을 그에 맞춥니다: 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는 요청 식별자입니다. 지원팀에 문의할 때 첨부해 주세요.
• Retry-After는 429와 함께 반환됩니다. 재시도 전에 대기해야 할 초를 나타냅니다.
• 헤더 X-Title와 HTTP-Referer(OpenRouter와 동일)는 게이트웨이가 고객님의 앱을 식별하는 데 도움이 됩니다. 텍스트는 저장되지 않습니다.

• 이미지: image_url 파트는 텍스트 자리표시자로 대체됩니다 — 모델이 이미지를 볼 수 없습니다(기능의 vision: false).
• 브라우저에서 API는 JoinGonka 도메인에서만 접근 가능합니다(Origin 검사). 서버에서 호출하고, 키를 프론트엔드에 두지 마세요.
• 임베딩: POST /v1/embeddings는 501를 반환합니다 — 네트워크에 임베딩 모델이 없습니다.
• 에러 코드, 제한, 타임아웃은 오류 및 한도 섹션을 참고하세요.