Per gli agenti AI: guida passo passo alla configurazione — /docs/agents.md, indice della documentazione — /llms.txt.

Riferimento API

Tutto sulle richieste al gateway: protocolli, indirizzi, chiavi e parametri. Di seguito — streaming, chiamata di strumenti, ragionamento, plugin e costo della richiesta nella risposta.

Il gateway accetta i formati OpenAI e Anthropic. Il Base URL per gli SDK OpenAI è https://gate.joingonka.ai/v1Copia, per gli SDK Anthropic è https://gate.joingonka.aiCopia. Tutti i protocolli funzionano con la stessa chiave e lo stesso saldo: una richiesta in qualsiasi formato segue lo stesso percorso.

Indirizzi di riferimento#

Rispondono senza chiave. La tabella dei modelli con contesto e stato è nella sezione Modelli.

Anthropic Messages#

• Base URL — https://gate.joingonka.aiCopia: l'SDK aggiunge /v1/messages da solo.
• Chiave — nell'header x-api-key (così la invia l'SDK Anthropic) oppure Authorization: Bearer.
• I modelli claude-* vengono sostituiti dal gateway con quello consigliato (MiniMaxAI/MiniMax-M2.7); nel campo model della risposta resta il nome inviato dal client.
• max_tokens è obbligatorio, come nell'API Anthropic; se supera il tetto del modello viene tagliato.
• Stream — eventi Anthropic; nelle pause il gateway invia event: ping, un errore arriva come evento event: error.
• Il ragionamento del modello non compare nella risposta: non ci sono blocchi thinking.
• Lo strumento integrato web_search viene eseguito dal plugin di ricerca web del gateway — vedi la sezione Plugin.
• Non c'è il conteggio dei token (/v1/messages/count_tokens) — risposta 404.

Configurare Claude Code è più semplice con l'installer — connessione degli strumenti. Manualmente, tramite variabili d'ambiente; ANTHROPIC_MODEL fissa il modello della rete.

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#

• Il gateway non conserva le risposte: invia tutta la cronologia in input. I campi previous_response_id e conversation — errore 400 con codice.
• store viene accettato senza alcun effetto.
• Strumenti: function e web_search — quest'ultimo viene eseguito dal plugin di ricerca web. Gli altri strumenti integrati vengono ignorati dal gateway e la richiesta va a buon fine senza di essi; richiedere uno di questi strumenti tramite tool_choice — errore 400.
• Le parti input_image e input_file — errore 400: i modelli della rete lavorano con il testo.
• Gli indirizzi di stato (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) rispondono 404 con codice — il gateway non conserva le risposte.
• Codex CLI: imposta il tuo id di provider in model_provider (non openai) — così Codex comprime la cronologia da solo, senza /v1/responses/compact.

Legacy Completions#

• prompt — stringa o array con una sola stringa; la risposta è in choices[].text. Più prompt o token al posto del testo — errore 400.
• suffix viene passato al modello come suggerimento nel prompt: la rete non supporta davvero il riempimento centrale.
• Nella risposta logprobs: null; best_of viene ignorato; echo funziona.

La chiave si passa nell'header Authorization: Bearer jg-… oppure x-api-key: jg-… — su tutti gli indirizzi. La chiave si crea dopo la registrazione nella pagina gate.joingonka.ai/keys.

• A ogni chiave nell'area personale si può assegnare un limite di spesa giornaliero, mensile e totale; se lo superi — 402 child_key_limit_exceeded.
• Il numero di richieste al minuto per chiave è limitato — i valori sono nella sezione Limiti.
• Senza chiave funziona solo la chat demo sul sito: una richiesta dal tuo codice senza chiave riceverà 402 con is_demo.
• Le chiavi si gestiscono solo nell'area personale: /api/keys con API key non è accessibile. Saldo e spesa per chiave — API dell'account.

La stessa richiesta in quattro SDK. Il modello è quello consigliato (MiniMaxAI/MiniMax-M2.7), la chiave proviene dalla variabile d'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)

Risposta in 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)

I parametri di POST /v1/chat/completions che il gateway garantisce da sé — la lista supported_parameters nella risposta capabilities:

• Senza temperature il gateway inserisce 0.7.
• Senza max_tokens il gateway inserisce il default del modello: senza stream — più corto, in streaming — il tetto del modello. I numeri per modello sono nella sezione Limiti.

Trasmessi alla rete così come sono#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. Il gateway non li verifica: un valore fuori dalla lista della rete — errore 400 con tipo api_error.

Non trasmessi alla rete#

Gli altri campi il gateway li accetta e non li trasmette alla rete — per esempio user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage in streaming arriva sempre.

• stream: true — risposta come eventi SSE; l'ultimo evento — data: [DONE].
• Prima della conclusione arriva un chunk con usage — sempre, anche senza stream_options.
• Nelle pause il gateway invia ogni 15 s un commento : keep-alive — i client SSE lo saltano.
• Finché lo stream non è aperto, il rifiuto arriva come normale codice di risposta; dopo l'apertura — come chunk joingonka-error.
• In delta.tool_calls — una chiamata per chunk: le chiamate unite dalla rete il gateway le 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]

Chunk di servizio del gateway#

Si riconoscono dal campo id:

Stream in altri protocolli#

• Anthropic Messages: eventi da message_start a message_stop, nelle pause event: ping, errore — event: error.
• OpenAI Responses: eventi response.*, errore — response.failed.
• Legacy Completions: in caso di errore — data: {"error": …}, poi [DONE].

• Formato OpenAI: tools e tool_choice. Anche il vecchio formato functions e function_call è accettato — la risposta arriverà nello stesso.
• In streaming — una chiamata per chunk: i client che leggono solo il primo elemento non perdono le chiamate.
• La cronologia su cui la rete risponderebbe con errore 400 il gateway la corregge: il ruolo developer diventa system, gli id di chiamata vuoti e duplicati ricevono id univoci, arguments come oggetto diventa una stringa JSON, il type mancante viene aggiunto, la chiamata senza nome viene rimossa insieme al risultato.
• La chiamata che il modello ha scritto come markup nel testo il gateway la sposta in tool_calls; le chiamate false nella risposta a una richiesta senza strumenti le rimuove.
• La generazione si è interrotta a metà degli argomenti — arriverà finish_reason: length, non tool_calls: aumenta il limite della risposta.

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

Limitazioni di JSON-Schema#

Gli schemi degli strumenti e response_format la rete li compila in una grammatica; le espressioni regolari — con il motore RE2. Il gateway porta lo schema alla forma che la rete accetta:

• I $ref vengono espansi sul posto, le sezioni $defs e definitions vengono rimosse; un riferimento ricorsivo diventa uno schema senza vincoli.
• I pattern con costrutti assenti in RE2 (lookahead e lookbehind, backreference, gruppi atomici, quantificatori possessivi) vengono rimossi; le ripetizioni superiori a 1000 vengono ridotte a 1000.
• anyOf e oneOf di costanti vengono compattati in enum; se i rami non compattabili sono più di 16, l'unione viene rimossa.

response_format: {"type": "json_object"} — risposta come JSON valido, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} — secondo il tuo schema con le limitazioni sopra. Il JSON troncato senza stream viene corretto dal 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"]
      }
    }
  }
}

• Il ragionamento del modello arriva separato dalla risposta: message.reasoning_content, in streaming — delta.reasoning_content. Il campo reasoning il gateway lo rinomina in questo formato.
• Il ragionamento consuma max_tokens: con un limite piccolo la risposta si interrompe (finish_reason: length) ancora prima del testo.
• Se il testo della risposta manca ma il ragionamento c'è, il gateway lo sposta in content — tranne le risposte con chiamata di strumento.
• reasoning_effort e reasoning.effort vengono trasmessi alla rete. Se il modello ha solo due modalità, il gateway adegua il valore: none e minimal — a low, quelli più alti — al ragionamento predefinito.
• Se il nodo rifiuta il valore, il gateway lo abbassa (max e xhigh → high, minimal → low, altrimenti rimuove il campo) e ripete la richiesta.
• In /v1/messages il ragionamento non viene trasmesso — non ci sono blocchi thinking.

I plugin si attivano con il campo plugins — come array di stringhe o di oggetti con opzioni. La lista — GET /v1/plugins.

Ricerca web#

• Opzioni: max_results — da 1 a 10, predefinito 5; engine — suggerimento del motore; search_prompt — testo personalizzato prima dei risultati; enabled: false — disattiva la ricerca.
• Le fonti — in message.annotations[].url_citation; in streaming — come chunk joingonka-citations prima della conclusione.
• mode: "agent" — il modello decide da sé se cercare e cosa; max_searches — da 1 a 5, predefinito 3.
• Pagamento: in modalità normale — solo token (i risultati di ricerca rientrano nei token di input); in modalità agente — i token di tutti i passaggi più 1000 nGNK per ogni ricerca eseguita (x_joingonka.web_search_surcharge_ngonka).
• In Anthropic Messages e OpenAI Responses lo strumento integrato web_search esegue lo stesso plugin in modalità 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 risposta non in streaming riporta il costo della richiesta in usage:

• Nello streaming usage contiene solo token; il costo è nel chunk joingonka-meta.
• Con l'header x-joingonka-meta: 1 la risposta POST /v1/chat/completions riceve il blocco x_joingonka: costo (cost_ngonka), saldo dopo l'addebito (balance_ngonka, solo senza streaming) e tempi (ttft_ms). Gli altri protocolli non restituiscono questo blocco.
• x-request-id — identificatore della richiesta: allegalo alla richiesta di assistenza.
• Retry-After arriva con 429: quanti secondi attendere prima di riprovare.
• Gli header X-Title e HTTP-Referer (come su OpenRouter) aiutano il gateway a riconoscere la tua applicazione; il loro testo non viene salvato.

• Immagini: le parti image_url vengono sostituite da un segnaposto testuale — il modello non vede l'immagine (vision: false nelle capacità).
• Dal browser l'API è accessibile solo dai domini JoinGonka (controllo Origin): chiamala dal tuo server, non mettere la chiave nel frontend.
• Embedding: POST /v1/embeddings risponde 501 — nella rete non ci sono modelli di embedding.
• Codici di errore, limiti e timeout — nella sezione Errori e limiti.