Para agentes de IA: guia passo a passo de configuração — /docs/agents.md, índice da documentação — /llms.txt.

Referência da API

Tudo sobre requisições ao gateway: protocolos, endereços, chaves e parâmetros. Abaixo — streaming, chamada de ferramentas, raciocínio, plugins e o custo da requisição na resposta.

O gateway aceita os formatos da OpenAI e da Anthropic. A URL base para o SDK da OpenAI é https://gate.joingonka.ai/v1Copiar e para o SDK da Anthropic, https://gate.joingonka.aiCopiar. Todos os protocolos funcionam com a mesma chave e o mesmo saldo: uma requisição em qualquer formato percorre o mesmo caminho.

Endereços de referência#

Respondem sem chave. A tabela de modelos com contexto e status está na seção Modelos.

Anthropic Messages#

• URL base: https://gate.joingonka.aiCopiar. O SDK adiciona /v1/messages sozinho.
• A chave vai no cabeçalho x-api-key (é assim que o SDK da Anthropic envia) ou Authorization: Bearer.
• O gateway substitui os modelos claude-* pelo recomendado (MiniMaxAI/MiniMax-M2.7); no campo model da resposta permanece o nome enviado pelo cliente.
• max_tokens é obrigatório, como na API da Anthropic; se ultrapassar o teto do modelo, é cortado.
• O stream são eventos da Anthropic; nas pausas o gateway envia event: ping e uma falha chega como evento event: error.
• O raciocínio do modelo não aparece na resposta: não há blocos thinking.
• A ferramenta integrada web_search é executada pelo plugin de busca na web do gateway; consulte a seção Plugins.
• Não há contagem de tokens (/v1/messages/count_tokens): resposta 404.

O Claude Code é configurado mais facilmente com o instalador: conexão de ferramentas. Manualmente, use variáveis de ambiente; ANTHROPIC_MODEL fixa o modelo da rede.

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#

• O gateway não armazena respostas: envie todo o histórico em input. Os campos previous_response_id e conversation geram um erro 400 com código.
• store é aceito e não muda nada.
• Ferramentas: function e web_search, executada pelo plugin de busca na web. O gateway ignora as outras ferramentas integradas e a requisição é executada sem elas; exigir uma dessas ferramentas via tool_choice gera um erro 400.
• As partes input_image e input_file geram um erro 400: os modelos da rede trabalham com texto.
• Os endereços 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) respondem 404 com código: o gateway não armazena respostas.
• Codex CLI: defina seu próprio id de provedor em model_provider (diferente de openai); assim o Codex compacta o histórico sozinho, sem /v1/responses/compact.

Legacy Completions#

• prompt é uma string ou um array de uma única string; a resposta vai em choices[].text. Vários prompts ou tokens no lugar de texto geram um erro 400.
• suffix é passado ao modelo como dica no prompt: a rede não faz um preenchimento real do meio.
• Na resposta, logprobs: null; best_of é ignorado; echo funciona.

A chave é enviada no cabeçalho Authorization: Bearer jg-… ou x-api-key: jg-…, em todos os endereços. A chave é criada após o cadastro na página gate.joingonka.ai/keys.

• No painel, você pode definir para cada chave um limite de gastos diário, mensal e total; se ultrapassar, 402 child_key_limit_exceeded.
• O número de requisições por minuto por chave é limitado; os valores estão na seção Limites.
• Sem chave, só funciona o chat de demonstração do site: uma requisição sem chave feita do seu próprio código receberá 402 com is_demo.
• As chaves são gerenciadas apenas no painel: /api/keys não está disponível com uma chave de API. O saldo e o gasto por chave estão em API da conta.

A mesma requisição em quatro SDKs. O modelo é o recomendado (MiniMaxAI/MiniMax-M2.7), a chave vem da variável de ambiente 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)

Resposta em 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 o gateway garante por conta própria: a lista supported_parameters na resposta de capacidades:

• Sem temperature, o gateway aplica 0.7.
• Sem max_tokens, o gateway aplica o padrão do modelo: sem streaming, mais curto; no streaming, o teto do modelo. Os números por modelo estão na seção Limites.

São repassados à rede como estão#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. O gateway não os valida: um valor fora da lista da rede gera um erro 400 com tipo api_error.

Não são repassados à rede#

Os demais campos o gateway aceita e não repassa à rede, por exemplo user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. O usage no streaming chega sempre.

• stream: true: resposta por eventos SSE; o último evento é data: [DONE].
• Antes do encerramento chega um chunk com usage, sempre, mesmo sem stream_options.
• Nas pausas o gateway envia a cada 15 s um comentário : keep-alive; os clientes SSE o ignoram.
• Enquanto o stream não está aberto, a recusa chega com um código de resposta comum; depois de aberto, chega como chunk joingonka-error.
• Em delta.tool_calls há uma chamada por chunk: as chamadas que a rede junta o gateway separa.

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 do gateway#

Dá para reconhecê-los pelo campo id:

Streaming em outros protocolos#

• Anthropic Messages: eventos de message_start até message_stop, com event: ping nas pausas e event: error em caso de falha.
• OpenAI Responses: eventos response.*, falha response.failed.
• Legacy Completions: em caso de falha, data: {"error": …} e depois [DONE].

• Formato OpenAI: tools e tool_choice. O formato antigo functions e function_call também é aceito, e a resposta vem nele mesmo.
• No streaming, uma chamada por chunk: clientes que leem apenas o primeiro elemento não perdem chamadas.
• O histórico com o qual a rede retornaria um erro 400 o gateway corrige: o papel developer vira system, ids de chamada vazios e repetidos recebem valores únicos, arguments como objeto vira string JSON, o type ausente é preenchido, e uma chamada sem nome é removida junto com o resultado.
• A chamada que o modelo escreveu como marcação no texto o gateway move para tool_calls; chamadas falsas na resposta a uma requisição sem ferramentas ele remove.
• A geração foi interrompida no meio dos argumentos: virá finish_reason: length, e não tool_calls; aumente o limite da resposta.

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

Restrições de JSON-Schema#

Os esquemas das ferramentas e response_format a rede compila em uma gramática; as expressões regulares usam o motor RE2. O gateway ajusta o esquema à forma que a rede aceita:

• Os $ref são expandidos no lugar, as seções $defs e definitions são removidas; uma referência recursiva vira um esquema sem restrições.
• O pattern com construções que não existem no RE2 (lookahead e lookbehind, referências anteriores, grupos atômicos, quantificadores possessivos) é removido; repetições maiores que 1000 são reduzidas a 1000.
• anyOf e oneOf de constantes são colapsados em enum; se houver mais de 16 ramos não colapsáveis, a união é removida.

response_format: {"type": "json_object"} para uma resposta JSON válida, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} conforme o seu esquema com as restrições acima. O JSON truncado sem streaming é corrigido pelo 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"]
      }
    }
  }
}

• O raciocínio do modelo chega separado da resposta: message.reasoning_content, e no streaming delta.reasoning_content. O campo reasoning o gateway renomeia para esse formato.
• O raciocínio consome max_tokens: com um limite pequeno a resposta é cortada (finish_reason: length) antes mesmo do texto.
• Se não há texto de resposta mas há raciocínio, o gateway o move para content, exceto em respostas com chamada de ferramenta.
• reasoning_effort e reasoning.effort são repassados à rede. Se o modelo tem apenas dois modos, o gateway ajusta o valor a eles: none e minimal para low, os mais altos para o raciocínio padrão.
• Se o nó rejeitar o valor, o gateway o rebaixa (max e xhigh → high, minimal → low, ou então remove o campo) e repete a requisição.
• Em /v1/messages o raciocínio não é repassado: não há blocos thinking.

Os plugins são ativados pelo campo plugins: um array de strings ou de objetos com opções. A lista está em GET /v1/plugins.

Busca na web#

• Opções: max_results, de 1 a 10, padrão 5; engine, dica de mecanismo; search_prompt, texto próprio antes dos resultados; enabled: false, desativar a busca.
• As fontes estão em message.annotations[].url_citation; no streaming, no chunk joingonka-citations antes do encerramento.
• mode: "agent": o modelo decide por conta própria se deve buscar e o quê; max_searches, de 1 a 5, padrão 3.
• Pagamento: no modo normal, apenas tokens (os resultados de busca entram nos tokens de entrada); no modo agente, os tokens de todas as etapas mais 1000 nGNK por cada busca realizada (x_joingonka.web_search_surcharge_ngonka).
• No Anthropic Messages e no OpenAI Responses, a ferramenta integrada web_search executa esse mesmo plugin no 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}]
}

A resposta sem streaming traz o custo da requisição em usage:

• No streaming, usage contém apenas tokens; o custo está no chunk joingonka-meta.
• Com o cabeçalho x-joingonka-meta: 1, a resposta POST /v1/chat/completions recebe o bloco x_joingonka: custo (cost_ngonka), saldo após o débito (balance_ngonka, somente sem streaming) e timings (ttft_ms). Outros protocolos não retornam esse bloco.
• x-request-id — identificador da requisição: inclua-o ao falar com o suporte.
• Retry-After vem com 429: quantos segundos esperar antes de tentar de novo.
• Os cabeçalhos X-Title e HTTP-Referer (como no OpenRouter) ajudam o gateway a identificar seu aplicativo; o texto deles não é armazenado.

• Imagens: as partes image_url são substituídas por um marcador de texto — o modelo não vê a imagem (vision: false nas capacidades).
• Do navegador, a API só é acessível a partir de domínios da JoinGonka (verificação Origin): chame-a do seu próprio servidor e não coloque a chave no frontend.
• Embeddings: POST /v1/embeddings responde 501 — não há modelos de embeddings na rede.
• Códigos de erro, limites e timeouts estão na seção Erros e limites.