Guide d’intégration

Se connecter à BestRelay, en un préambule et six chapitres

Tout repose sur deux paramètres : l’adresse à laquelle votre client envoie ses requêtes et la clé qui les accompagne. Ce guide indique les valeurs exactes à utiliser pour chaque protocole.

Préface : ce que couvre ce guide

Quel que soit votre client, la configuration repose sur deux paramètres : l’adresse à laquelle envoyer les requêtes et la clé qui les accompagne. Les chapitres suivants donnent les valeurs à utiliser pour chaque protocole, puis expliquent la facturation des appels et les codes de statut que vous pourrez rencontrer.

Lisez le premier chapitre quel que soit votre outil, puis passez au chapitre qui lui est consacré.

I. La clé et l’adresse de base

Créez une clé dans la rubrique Clés API du tableau de bord. Tout le trafic API passe par un hôte unique, distinct du site web :

https://api.bestapirelay.com

La manière de renseigner l’adresse de cet hôte dépend du protocole utilisé par votre client :

Clients et SDK compatibles OpenAI : l’adresse de l’hôte suivie de /v1, avec la clé envoyée comme jeton Bearer.
Clients Anthropic tels que Claude Code et Claude Desktop : l’adresse de l’hôte seule, avec la clé dans x-api-key ou ANTHROPIC_AUTH_TOKEN.
Clients Gemini : l’adresse de l’hôte seule, avec la clé dans x-goog-api-key.

II. Appels compatibles OpenAI : cURL, SDK et Codex

Les requêtes de chat sont envoyées à /v1/chat/completions, et celles de l’API Responses à /v1/responses. Un premier appel depuis un terminal permet de vérifier que la clé fonctionne :

curl https://api.bestapirelay.com/v1/chat/completions \
  -H "Authorization: Bearer bsr_your_key_here" -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Describe a well-made fountain pen in one sentence."}]}'

Dans votre code, configurez n’importe quel SDK OpenAI avec la même URL de base. Avec le client Python asynchrone, cela donne :

import asyncio
from openai import AsyncOpenAI

bestrelay_client = AsyncOpenAI(base_url="https://api.bestapirelay.com/v1", api_key="bsr_your_key_here")

async def ask_the_atelier():
    fountain_pen = await bestrelay_client.chat.completions.create(
        model="gpt-6.1-sol",
        messages=[{"role": "user", "content": "Describe a well-made fountain pen in one sentence."}],
    )
    print(fountain_pen.choices[0].message.content)

asyncio.run(ask_the_atelier())

Codex lit les paramètres de son fournisseur dans un fichier de configuration :

# ~/.codex/config.toml (BestRelay as the provider)
model = "gpt-6.1-sol"            # any GPT id from the rate card
model_provider = "bestrelay"

[model_providers.bestrelay]
name = "BestRelay"
base_url = "https://api.bestapirelay.com/v1"
env_key = "BESTRELAY_API_KEY"      # export BESTRELAY_API_KEY=bsr_your_key_here
wire_api = "responses"             # Codex speaks the Responses API

Identifiants GPT recommandés : gpt-6.1-sol, gpt-6-astra, gpt-5.6-sol

III. La route native de Gemini

Gemini CLI utilise l’adresse de l’hôte seule comme URL de base (sans ajouter /v1beta) et votre clé BestRelay comme valeur de GEMINI_API_KEY :

export GOOGLE_GEMINI_BASE_URL=https://api.bestapirelay.com
export GEMINI_API_KEY=bsr_your_key_here
gemini

Les appels directs utilisent la route native generateContent, avec la clé dans un en-tête x-goog-api-key :

curl "https://api.bestapirelay.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: bsr_your_key_here" -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Which printing press came first?"}]}]}'

Les modèles Gemini ne prennent en charge que leur protocole natif. Pour le streaming, utilisez :streamGenerateContent?alt=sse ; la route /v1/chat/completions au format OpenAI ne permet pas d’y accéder.

Identifiants des modèles Gemini à transmettre : gemini-3.1-pro, gemini-4-argon, gemini-3.8-flash, gemini-2.5-flash

IV. Claude Code et Claude Desktop

Définissez deux variables d’environnement, puis lancez Claude Code comme d’habitude. L’URL de base est l’adresse de l’hôte seule, sans /v1 :

export ANTHROPIC_BASE_URL=https://api.bestapirelay.com
export ANTHROPIC_AUTH_TOKEN=bsr_your_key_here
claude

Sous Windows (PowerShell ou cmd), définissez ces deux mêmes variables avec setx, puis ouvrez un nouveau terminal :

setx ANTHROPIC_BASE_URL https://api.bestapirelay.com
setx ANTHROPIC_AUTH_TOKEN bsr_your_key_here

Les modèles Claude sont accessibles uniquement depuis les clients officiels Claude Code et Claude Desktop, et le fournisseur exige Claude Code 2.1.285 ou une version ultérieure. GPT, Gemini et les autres familles fonctionnent avec tout client ou SDK compatible.

V. Comment un appel est facturé

Chaque appel est facturé une seule fois, une fois la réponse terminée, selon les tokens d’entrée, de sortie et de cache déclarés par le fournisseur, aux prix de la grille tarifaire. Aucun montant n’est réservé à l’avance.

Si un appel aboutit sans données d’utilisation, il est facturé sur une estimation de 2,000 tokens d’entrée et 2,000 tokens de sortie ; cette estimation est signalée dans l’historique des opérations. Si votre client se déconnecte en cours de streaming, l’appel reste facturé selon les données déclarées par le fournisseur.

Les requêtes rejetées par le fournisseur et les requêtes de comptage de tokens sont enregistrées avec un montant nul. Un dernier appel peut faire passer le solde légèrement sous zéro ; les requêtes renvoient alors le code 402 jusqu’à ce que vous rechargiez votre compte.

VI. Les codes de statut que vous pouvez rencontrer

Les erreurs sont renvoyées dans la structure JSON habituelle, avec un message rédigé par BestRelay :

400: La requête ne précise aucun modèle, indique un modèle inconnu ou utilise une route incompatible avec le protocole du modèle.
401: Aucune clé n’a été envoyée, ou la clé est inconnue ou n’est plus valide.
402: Le solde est épuisé ; rechargez votre compte pour continuer.
403: Le compte associé à la clé est suspendu.
404: Aucune route n’existe à ce chemin.
413: Le corps de la requête dépasse 25 MB.
429: Plus de 120 requêtes par minute avec une même clé, ou déjà huit appels en cours sur un même compte.
502: Le fournisseur n’a pas pu être joint ; rien n’a été facturé.
503: La connexion au fournisseur pour ce modèle n’est pas encore configurée.