Para agentes de IA: guía paso a paso de configuración — /docs/agents.md, índice de documentación — /llms.txt.

Referencia de la API

Todo sobre las solicitudes a la pasarela: protocolos, direcciones, claves y parámetros. A continuación: streaming, llamada a herramientas, razonamiento, plugins y el coste de la solicitud en la respuesta.

El gateway acepta los formatos de OpenAI y Anthropic. La URL base para el SDK de OpenAI es https://gate.joingonka.ai/v1Copiar y para el SDK de Anthropic, https://gate.joingonka.aiCopiar. Todos los protocolos funcionan con una misma clave y un mismo saldo: una solicitud en cualquier formato recorre el mismo camino.

Direcciones de referencia#

Responden sin clave. La tabla de modelos con contexto y estado está en la sección Modelos.

Anthropic Messages#

• URL base: https://gate.joingonka.aiCopiar. El SDK añadirá /v1/messages por su cuenta.
• La clave va en el encabezado x-api-key (así la envía el SDK de Anthropic) o Authorization: Bearer.
• El gateway sustituye los modelos claude-* por el recomendado (MiniMaxAI/MiniMax-M2.7); en el campo model de la respuesta se mantiene el nombre que envió el cliente.
• max_tokens es obligatorio, como en la API de Anthropic; si supera el techo del modelo, se recorta.
• El stream son eventos de Anthropic; en las pausas el gateway envía event: ping y un fallo llega como evento event: error.
• El razonamiento del modelo no aparece en la respuesta: no hay bloques thinking.
• La herramienta integrada web_search la ejecuta el plugin de búsqueda web del gateway; consulta la sección Plugins.
• No hay conteo de tokens (/v1/messages/count_tokens): respuesta 404.

Claude Code se configura más fácilmente con el instalador: conexión de herramientas. De forma manual, con variables de entorno; ANTHROPIC_MODEL fija el modelo de la red.

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#

• El gateway no almacena respuestas: envía todo el historial en input. Los campos previous_response_id y conversation dan un error 400 con código.
• store se acepta y no cambia nada.
• Herramientas: function y web_search, que ejecuta el plugin de búsqueda web. El gateway omite las demás herramientas integradas y la solicitud se ejecuta sin ellas; exigir una de esas herramientas mediante tool_choice da un error 400.
• Las partes input_image y input_file dan un error 400: los modelos de la red trabajan con texto.
• Las direcciones de estado (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) responden 404 con código: el gateway no almacena respuestas.
• Codex CLI: define tu propio id de proveedor en model_provider (que no sea openai); así Codex comprime el historial por su cuenta, sin /v1/responses/compact.

Legacy Completions#

• prompt es una cadena o un array de una sola cadena; la respuesta va en choices[].text. Varios prompts o tokens en lugar de texto dan un error 400.
• suffix se pasa al modelo como sugerencia en el prompt: la red no realiza un verdadero relleno de la parte central.
• En la respuesta, logprobs: null; best_of se ignora; echo funciona.

La clave se envía en el encabezado Authorization: Bearer jg-… o x-api-key: jg-…, en todas las direcciones. La clave se crea tras registrarse en la página gate.joingonka.ai/keys.

• En el panel puedes fijar a cada clave un límite de gasto diario, mensual y total; si se supera, 402 child_key_limit_exceeded.
• El número de solicitudes por minuto por clave está limitado; los valores están en la sección Límites.
• Sin clave solo funciona el chat de demostración del sitio: una solicitud sin clave desde tu propio código recibirá 402 con is_demo.
• Las claves solo se gestionan en el panel: /api/keys no está disponible con una clave API. El saldo y el gasto por clave están en API de la cuenta.

La misma petición en cuatro SDK. El modelo es el recomendado (MiniMaxAI/MiniMax-M2.7), la clave va en la variable de entorno 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)

Respuesta en 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)

Parámetros de POST /v1/chat/completions que el gateway garantiza por su cuenta: la lista supported_parameters en la respuesta de capacidades:

• Sin temperature, el gateway aplica 0.7.
• Sin max_tokens, el gateway aplica el valor por defecto del modelo: sin streaming, más corto; en streaming, el techo del modelo. Los números por modelo están en la sección Límites.

Se transmiten a la red tal cual#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. El gateway no los valida: un valor fuera de la lista de la red produce un error 400 con tipo api_error.

No se transmiten a la red#

El resto de campos el gateway los acepta pero no los transmite a la red, por ejemplo user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage en streaming llega siempre.

• stream: true: respuesta por eventos SSE; el último evento es data: [DONE].
• Antes del cierre llega un chunk con usage, siempre, incluso sin stream_options.
• En las pausas el gateway envía cada 15 s un comentario : keep-alive; los clientes SSE lo ignoran.
• Mientras el stream no está abierto, el rechazo llega con un código de respuesta normal; una vez abierto, llega como chunk joingonka-error.
• En delta.tool_calls hay una sola llamada por chunk: las llamadas que la red une las separa el 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]

Chunks internos del gateway#

Se reconocen por el campo id:

Streaming en otros protocolos#

• Anthropic Messages: eventos desde message_start hasta message_stop, con event: ping en las pausas y event: error en caso de fallo.
• OpenAI Responses: eventos response.*, fallo response.failed.
• Legacy Completions: en caso de fallo, data: {"error": …} y luego [DONE].

• Formato OpenAI: tools y tool_choice. El formato antiguo functions y function_call también se acepta, y la respuesta llega en ese mismo formato.
• En streaming, una llamada por chunk: los clientes que solo leen el primer elemento no pierden llamadas.
• El historial con el que la red devolvería un error 400 el gateway lo corrige: el rol developer pasa a system, los id de llamada vacíos y repetidos reciben valores únicos, arguments como objeto se convierte en cadena JSON, el type ausente se completa, y una llamada sin nombre se elimina junto con su resultado.
• La llamada que el modelo escribió como marcado en el texto el gateway la traslada a tool_calls; las llamadas falsas en una respuesta a una petición sin herramientas las elimina.
• La generación se interrumpió en medio de los argumentos: llegará finish_reason: length y no tool_calls; aumenta el límite de respuesta.

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

Restricciones de JSON-Schema#

Los esquemas de las herramientas y response_format la red los compila a una gramática; las expresiones regulares usan el motor RE2. El gateway adapta el esquema a la forma que la red acepta:

• Los $ref se expanden en su lugar, las secciones $defs y definitions se eliminan; una referencia recursiva se convierte en un esquema sin restricciones.
• El pattern con construcciones que no existen en RE2 (lookahead y lookbehind, retrorreferencias, grupos atómicos, cuantificadores posesivos) se retira; las repeticiones mayores que 1000 se reducen a 1000.
• anyOf y oneOf de constantes se colapsan en enum; si hay más de 16 ramas no colapsables, la unión se retira.

response_format: {"type": "json_object"} para una respuesta JSON válida, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} según tu esquema con las restricciones anteriores. El JSON truncado sin streaming lo corrige el 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"]
      }
    }
  }
}

• El razonamiento del modelo llega aparte de la respuesta: message.reasoning_content, y en streaming delta.reasoning_content. El campo reasoning el gateway lo renombra a este formato.
• El razonamiento consume max_tokens: con un límite pequeño la respuesta se corta (finish_reason: length) antes incluso del texto.
• Si no hay texto de respuesta pero sí razonamiento, el gateway lo traslada a content, salvo en respuestas con llamada a herramienta.
• reasoning_effort y reasoning.effort se transmiten a la red. Si el modelo solo tiene dos modos, el gateway adapta el valor a ellos: none y minimal a low, los más altos al razonamiento por defecto.
• Si el nodo rechaza el valor, el gateway lo rebaja (max y xhigh → high, minimal → low, o de lo contrario elimina el campo) y repite la petición.
• En /v1/messages no se transmite el razonamiento: no hay bloques thinking.

Los plugins se activan con el campo plugins: un array de cadenas o de objetos con opciones. La lista está en GET /v1/plugins.

Búsqueda web#

• Opciones: max_results, de 1 a 10, por defecto 5; engine, sugerencia de motor; search_prompt, texto propio antes de los resultados; enabled: false, desactivar la búsqueda.
• Las fuentes están en message.annotations[].url_citation; en streaming, en el chunk joingonka-citations antes del cierre.
• mode: "agent": el modelo decide por sí mismo si buscar y qué buscar; max_searches, de 1 a 5, por defecto 3.
• Pago: en modo normal, solo tokens (los resultados de búsqueda se incluyen en los tokens de entrada); en modo agente, los tokens de todos los pasos más 1000 nGNK por cada búsqueda realizada (x_joingonka.web_search_surcharge_ngonka).
• En Anthropic Messages y OpenAI Responses, la herramienta integrada web_search ejecuta este mismo plugin en modo agente.

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

La respuesta sin streaming incluye el costo de la solicitud en usage:

• En streaming, usage contiene solo tokens; el costo está en el chunk joingonka-meta.
• Con la cabecera x-joingonka-meta: 1, la respuesta POST /v1/chat/completions recibe el bloque x_joingonka: costo (cost_ngonka), saldo tras el débito (balance_ngonka, solo sin streaming) y tiempos (ttft_ms). Otros protocolos no devuelven este bloque.
• x-request-id: identificador de la solicitud; inclúyelo en tu contacto con soporte.
• Retry-After llega con 429: los segundos que hay que esperar antes de reintentar.
• Las cabeceras X-Title y HTTP-Referer (como en OpenRouter) ayudan a la pasarela a identificar tu aplicación; su texto no se almacena.

• Imágenes: las partes image_url se sustituyen por un marcador de texto; el modelo no ve la imagen (vision: false en las capacidades).
• Desde el navegador, la API solo es accesible desde dominios de JoinGonka (verificación Origin): llámala desde tu propio servidor y no pongas la clave en el frontend.
• Embeddings: POST /v1/embeddings responde 501; no hay modelos de embeddings en la red.
• Códigos de error, límites y timeouts en la sección Errores y límites.