Documentation

BreignHUB parle le protocole OpenAI. Pointez n’importe quel client vers l’URL de base ci-dessous, utilisez une clé BreignHUB comme clé API, et le reste de votre code ne bouge pas.

URL de base et authentification

La clé se transmet dans l’en-tête Authorization, en bearer token. Les clés se créent dans le tableau de bord et ne s’affichent qu’une fois — BreignHUB ne stocke pas le secret et ne peut pas vous le remontrer.

URL de base: https://hub.breign.eu/api/v1
Clé API: Une clé du tableau de bord, commençant par bh-

À appeler depuis votre serveur, pas depuis un navigateur

/api/v1 n'envoie aucun en-tête CORS : une page servie par une autre origine ne peut pas l'atteindre. C'est volontaire — une clé BreignHUB placée dans du code front-end est une clé publiée. Gardez-la sur votre serveur, ou derrière un proxy que vous contrôlez.

Votre premier appel

Les identifiants de modèles portent le provider qui les sert, sous la forme providerId/modelName. Listez-les avec GET /models, ou lisez-les dans le catalogue.

first-call.sh

curl https://hub.breign.eu/api/v1/chat/completions \
  -H "Authorization: Bearer $BREIGNHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<providerId>/<modelName>",
    "messages": [{ "role": "user", "content": "Say hello." }]
  }'

Depuis le SDK OpenAI

Seule l’URL de base change. Le streaming fonctionne à l’identique.

python

from openai import OpenAI

client = OpenAI(
    base_url="https://hub.breign.eu/api/v1",
    api_key=os.environ["BREIGNHUB_API_KEY"],
)

stream = client.chat.completions.create(
    model="<providerId>/<modelName>",
    messages=[{"role": "user", "content": "Say hello."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

typescript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hub.breign.eu/api/v1",
  apiKey: process.env.BREIGNHUB_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "<providerId>/<modelName>",
  messages: [{ role: "user", content: "Say hello." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Lister les modèles

Renvoie les modèles accessibles à l’organisation de la clé. La disponibilité vient de l’organisation, pas de la clé.

models.sh

curl https://hub.breign.eu/api/v1/models \
  -H "Authorization: Bearer $BREIGNHUB_API_KEY"

Embeddings

Un lot est accepté puis éclaté : la passerelle Breign traite une chaîne par appel, donc BreignHUB plafonne un lot à 64 et réassemble les résultats dans l’ordre.

embeddings.sh

curl https://hub.breign.eu/api/v1/embeddings \
  -H "Authorization: Bearer $BREIGNHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<providerId>/<modelName>",
    "input": ["premier texte", "second texte"]
  }'

Ce que la passerelle ne prend pas en charge

La passerelle Breign n’accepte qu’un sous-ensemble restreint de la requête OpenAI. Les champs qui changeraient la réponse sont refusés par un 400 qui les nomme, plutôt qu’ignorés — honorer une requête en écartant ses tools ou son response_format vous rendrait une mauvaise réponse qui a l’air juste.

Champ	Comportement
model, messages, max_tokens, temperature, stream, stream_options	Transmis
user, metadata, store, service_tier, n: 1	Accepté et ignoré, listé dans l’en-tête de réponse X-BreignHub-Ignored-Fields
tools, tool_choice, functions, response_format, top_p, seed, stop, logprobs, presence_penalty, frequency_penalty, logit_bias	Refusé par un 400 nommant le champ
temperature > 1	Refusé au-dessus de 1. OpenAI va jusqu’à 2 ; brider silencieusement changerait vos résultats
image / audio content parts	Refusé — la passerelle ne traite que du texte
role: developer	Converti en system

Utiliser BreignHUB depuis un agent de code

Tout outil permettant de définir une URL de base compatible OpenAI convient. Deux exemples.

opencode

Ajoutez un provider dans opencode.json. Utilisez @ai-sdk/openai-compatible, qui vise /v1/chat/completions. Lancez ensuite /models et sélectionnez-le.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "breignhub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BreignHUB",
      "options": {
        "baseURL": "https://hub.breign.eu/api/v1",
        "apiKey": "{env:BREIGNHUB_API_KEY}"
      },
      "models": {
        "<providerId>/<modelName>": {
          "name": "Qwen3.6 35B"
        }
      }
    }
  }
}

export BREIGNHUB_API_KEY=bh-… · opencode · /models

Tous les autres

Continue, Cline, aider, LangChain, le SDK AI de Vercel — tous acceptent une URL de base et une clé API. Renseignez ces deux valeurs et c’est terminé. Si un outil envoie tools ou response_format par défaut, BreignHUB refusera l’appel avec un message nommant le champ ; désactivez la fonctionnalité côté outil.

Erreurs

Les échecs utilisent l’enveloppe OpenAI. Une erreur venant du cluster d’inférence est déballée plutôt qu’imbriquée : le message que vous lisez est celui que le backend a produit.

error.json

{
  "error": {
    "message": ""tools" is not supported: tool calling is not exposed by the Breign gateway.",
    "type": "invalid_request_error",
    "param": "tools",
    "code": "unsupported_parameter"
  }
}

# 401 missing_api_key · 401 invalid_api_key · 400 · 5xx

Créer une clé

Les clés se créent et se révoquent depuis le tableau de bord.

Créer une clé