Pour les agents IA : guide de configuration étape par étape — /docs/agents.md, index de la documentation — /llms.txt.

Référence API

Tout sur les requêtes adressées à la passerelle : protocoles, adresses, clés et paramètres. Ci-dessous — streaming, appel d'outils, raisonnement, plugins et coût de la requête dans la réponse.

La passerelle accepte les formats OpenAI et Anthropic. L'URL de base pour le SDK OpenAI est https://gate.joingonka.ai/v1Copier, pour le SDK Anthropic — https://gate.joingonka.aiCopier. Tous les protocoles fonctionnent avec une seule clé et un seul solde : une requête dans n'importe quel format emprunte le même chemin.

Adresses de référence#

Répondent sans clé. Le tableau des modèles avec contexte et statut se trouve dans la section Modèles.

Anthropic Messages#

• URL de base — https://gate.joingonka.aiCopier : le SDK ajoutera /v1/messages lui-même.
• Clé — dans l'en-tête x-api-key (comme l'envoie le SDK Anthropic) ou Authorization: Bearer.
• Les modèles claude-* sont remplacés par la passerelle par le modèle recommandé (MiniMaxAI/MiniMax-M2.7) ; le champ model de la réponse conserve le nom envoyé par le client.
• max_tokens est obligatoire, comme dans l'API Anthropic ; au-delà du plafond du modèle — la valeur est tronquée.
• Stream — événements Anthropic ; pendant les pauses, la passerelle envoie event: ping, une erreur arrive via l'événement event: error.
• Les raisonnements du modèle n'apparaissent pas dans la réponse : pas de blocs thinking.
• L'outil intégré web_search est exécuté par le plugin de recherche web de la passerelle — voir la section Plugins.
• Pas de comptage de tokens (/v1/messages/count_tokens) — réponse 404.

Claude Code se configure plus simplement avec l'installateur — connexion des outils. Manuellement — via des variables d'environnement ; ANTHROPIC_MODEL fixe le modèle du réseau.

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#

• La passerelle ne stocke pas les réponses : envoyez tout l'historique dans input. Les champs previous_response_id et conversation — erreur 400 avec code.
• store est accepté sans rien changer.
• Outils : function et web_search — ce dernier est exécuté par le plugin de recherche web. Les autres outils intégrés sont ignorés par la passerelle et la requête s'exécute sans eux ; exiger un tel outil via tool_choice — erreur 400.
• Les parties input_image et input_file — erreur 400 : les modèles du réseau travaillent avec du texte.
• Les adresses d'état (GET /v1/responses/{id}, DELETE /v1/responses/{id}, GET /v1/responses/{id}/input_items, POST /v1/responses/{id}/cancel, POST /v1/responses/compact) répondent 404 avec code — la passerelle ne stocke pas les réponses.
• Codex CLI : définissez votre propre id de fournisseur dans model_provider (pas openai) — Codex compresse alors l'historique lui-même, sans /v1/responses/compact.

Legacy Completions#

• prompt — une chaîne ou un tableau d'une seule chaîne ; la réponse est dans choices[].text. Plusieurs prompts ou des tokens à la place du texte — erreur 400.
• suffix est transmis au modèle comme indice dans le prompt : le réseau ne fait pas de vrai remplissage du milieu (fill-in-the-middle).
• La réponse contient logprobs: null ; best_of est ignoré ; echo fonctionne.

La clé se transmet dans l'en-tête Authorization: Bearer jg-… ou x-api-key: jg-… — sur toutes les adresses. La clé se crée après inscription sur la page gate.joingonka.ai/keys.

• Chaque clé peut avoir une limite de dépenses par jour, par mois et au total dans l'espace client ; dépassement — 402 child_key_limit_exceeded.
• Le nombre de requêtes par minute par clé est limité — les valeurs se trouvent dans la section Limites.
• Sans clé, seul le chat démo du site fonctionne : une requête sans clé depuis votre code recevra 402 avec is_demo.
• Les clés se gèrent uniquement dans l'espace client : /api/keys avec une clé API est inaccessible. Solde et dépenses par clé — API du compte.

Une même requête dans quatre SDK. Modèle recommandé (MiniMaxAI/MiniMax-M2.7), clé issue de la variable d'environnement 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)

Réponse 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)

Paramètres de POST /v1/chat/completions que la passerelle garantit elle-même — la liste supported_parameters dans la réponse de capacités :

• Sans temperature, la passerelle applique 0.7.
• Sans max_tokens, la passerelle applique la valeur par défaut du modèle : plus courte hors streaming, plafond du modèle en streaming. Les valeurs chiffrées par modèle sont dans la section Limites.

Transmis au réseau tel quel#

reasoning_effort, reasoning, enable_thinking, chat_template_kwargs, thinking_token_budget, min_tokens, logit_bias, n, parallel_tool_calls, extra_body. La passerelle ne les vérifie pas : une valeur hors de la liste du réseau renvoie une erreur 400 de type api_error.

Non transmis au réseau#

Les autres champs sont acceptés par la passerelle mais non transmis au réseau — par exemple user, metadata, store, logprobs, top_logprobs, thinking, stream_options, web_search_options. usage arrive toujours en streaming.

• stream: true — réponse sous forme d'événements SSE ; le dernier événement est data: [DONE].
• Avant la fin, un chunk contenant usage arrive — toujours, même sans stream_options.
• Pendant les pauses, la passerelle envoie toutes les 15 s un commentaire : keep-alive — les clients SSE l'ignorent.
• Tant que le flux n'est pas ouvert, un refus arrive via un code de réponse classique ; une fois ouvert, via un chunk joingonka-error.
• Dans delta.tool_calls — un appel par chunk : les appels fusionnés par le réseau sont découpés par la passerelle.

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 de service de la passerelle#

On les reconnaît au champ id :

Streaming dans d'autres protocoles#

• Anthropic Messages : événements de message_start à message_stop, event: ping pendant les pauses, échec — event: error.
• OpenAI Responses : événements response.*, échec — response.failed.
• Legacy Completions : en cas d'échec — data: {"error": …}, puis [DONE].

• Format OpenAI : tools et tool_choice. L'ancien format functions et function_call est aussi accepté — la réponse arrivera dans ce même format.
• En streaming — un appel par chunk : les clients qui ne lisent que le premier élément ne perdent pas d'appels.
• L'historique sur lequel le réseau renverrait une erreur 400 est corrigé par la passerelle : le rôle developer devient system, les id d'appels vides ou en doublon reçoivent des identifiants uniques, arguments sous forme d'objet est converti en chaîne JSON, le type manquant est complété, un appel sans nom est supprimé avec son résultat.
• Un appel que le modèle a écrit en balisage dans le texte est déplacé par la passerelle dans tool_calls ; les faux appels dans une réponse à une requête sans outils sont supprimés.
• La génération s'est interrompue au milieu des arguments — c'est finish_reason: length qui arrive, pas tool_calls : augmentez la limite de réponse.

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

Contraintes JSON-Schema#

Les schémas d'outils et response_format sont compilés en grammaire par le réseau ; les expressions régulières par le moteur RE2. La passerelle ramène le schéma à une forme acceptable par le réseau :

• Les $ref sont développées sur place, les sections $defs et definitions sont supprimées ; une référence récursive devient un schéma sans contraintes.
• pattern contenant des constructions absentes de RE2 (lookahead, lookbehind, rétroréférences, groupes atomiques, quantificateurs possessifs) est retiré ; les répétitions supérieures à 1000 sont réduites à 1000.
• anyOf et oneOf composés de constantes sont repliés en enum ; si les branches non repliables dépassent 16, l'union est supprimée.

response_format : {"type": "json_object"} — réponse en JSON valide, {"type": "json_schema", "json_schema": {"name": …, "schema": …}} — selon votre schéma avec les contraintes ci-dessus. Le JSON tronqué hors streaming est corrigé par le 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"]
      }
    }
  }
}

• Le raisonnement du modèle arrive séparément de la réponse : message.reasoning_content, en streaming — delta.reasoning_content. Le champ reasoning est renommé par la passerelle dans ce format.
• Le raisonnement consomme max_tokens : avec une limite basse, la réponse se coupe (finish_reason: length) avant même le texte.
• Si la réponse ne contient pas de texte mais que le raisonnement est présent, la passerelle le reporte dans content — sauf pour les réponses avec appel d'outil.
• reasoning_effort et reasoning.effort sont transmis au réseau. Si le modèle n'a que deux modes, la passerelle y ramène la valeur : none et minimal → low, les valeurs plus élevées → raisonnement par défaut.
• Si un nœud rejette la valeur, la passerelle la rétrograde (max et xhigh → high, minimal → low, sinon elle retire le champ) et relance la requête.
• Dans /v1/messages, le raisonnement n'est pas transmis — pas de blocs thinking.

Les plugins s'activent via le champ plugins — tableau de chaînes ou d'objets avec options. La liste — GET /v1/plugins.

Recherche web#

• Options : max_results — de 1 à 10, par défaut 5 ; engine — indication du moteur ; search_prompt — texte personnalisé avant les résultats ; enabled: false — désactiver la recherche.
• Sources — dans message.annotations[].url_citation ; en streaming — via le chunk joingonka-citations avant la fin.
• mode: "agent" — le modèle décide lui-même s'il faut chercher et quoi ; max_searches — de 1 à 5, par défaut 3.
• Facturation : en mode normal — uniquement les tokens (les résultats de recherche sont inclus dans les tokens d'entrée) ; en mode agent — les tokens de toutes les étapes plus 1000 nGNK par recherche effectuée (x_joingonka.web_search_surcharge_ngonka).
• Dans Anthropic Messages et OpenAI Responses, l'outil intégré web_search exécute ce même plugin en mode 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}]
}

Une réponse non-streaming indique le coût de la requête dans usage :

• En streaming, usage ne contient que les tokens ; le coût se trouve dans le chunk joingonka-meta.
• Avec l'en-tête x-joingonka-meta: 1, la réponse POST /v1/chat/completions inclut un bloc x_joingonka : coût (cost_ngonka), solde après débit (balance_ngonka, uniquement hors streaming) et timings (ttft_ms). Les autres protocoles ne renvoient pas ce bloc.
• x-request-id — identifiant de la requête : joignez-le à toute demande au support.
• Retry-After accompagne un 429 : nombre de secondes à attendre avant de réessayer.
• Les en-têtes X-Title et HTTP-Referer (comme chez OpenRouter) aident la passerelle à identifier votre application ; leur contenu n'est pas conservé.

• Images : les parties image_url sont remplacées par un texte de substitution — le modèle ne voit pas l'image (vision: false dans les capacités).
• Depuis un navigateur, l'API n'est accessible que depuis les domaines JoinGonka (vérification Origin) : appelez-la depuis votre serveur, ne placez jamais la clé dans le frontend.
• Embeddings : POST /v1/embeddings renvoie 501 — aucun modèle d'embedding n'est disponible sur le réseau.
• Codes d'erreur, limites et timeouts — dans la section Erreurs et limites.