Démarrage rapide de l’API Flatkey : effectuez votre premier appel via router.flatkey.ai

Si vous utilisez déjà le SDK OpenAI, le moyen le plus simple d’effectuer un premier appel à l’API Flatkey est simple : créez une clé Flatkey, pointez votre client vers https://router.flatkey.ai/v1, envoyez une requête chat-completions et confirmez l’appel dans la console.

Ce guide de démarrage rapide parcourt ce cycle complet. Il montre également comment ajouter une séquence de fallback de base après le premier modèle fonctionnel, sans masquer les erreurs ni créer une chaîne de retries illimitée.

Ce que vous allez accomplir

À la fin de ce guide, vous aurez :

1. Un compte Flatkey et une clé API.
2. Un client compatible avec OpenAI utilisant le routeur Flatkey.
3. Une requête réussie et une réponse lisible.
4. Un point de contrôle dans la console pour l’utilisation, le coût et le dépannage des requêtes.
5. Un petit pattern de fallback que vous pouvez tester avant la production.

Vous n’avez pas besoin de remanier votre application autour d’un nouveau SDK pour ce test rapide. La documentation publique de Flatkey expose un endpoint compatible avec OpenAI à https://router.flatkey.ai/v1, de sorte que les workflows courants de chat, d’outils, de streaming et de sortie structurée peuvent conserver la forme familière du client.

Avant de commencer

Vous avez besoin de :

• Un compte Flatkey.
• Une clé API Flatkey commençant par sk-fk-.
• Python 3.9+ ou Node.js 18+ si vous souhaitez utiliser un exemple de SDK.
• Un nom de modèle actuellement disponible pour votre compte.

Les catalogues de modèles et leur disponibilité peuvent changer. Utilisez le catalogue de modèles actuel ou la console plutôt que de copier un ancien nom de modèle en production.

Étape 1 : créez votre compte Flatkey

Ouvrez le flux d’inscription Flatkey et créez un compte. Après vous être connecté, utilisez la console pour créer l’identifiant que votre application enverra avec chaque requête.

Référence de la console

Allez dans Console → API Keys.

Créez une clé pour ce guide de démarrage rapide et copiez-la immédiatement. Traitez la clé comme un mot de passe : ne la collez pas dans du code côté client, ne la validez pas dans Git, ne l’incluez pas dans des captures d’écran et ne l’envoyez pas dans des messages de support.

Pour un environnement d’équipe, créez des clés distinctes pour chaque développeur ou service. La documentation de Flatkey décrit également des contrôles par clé, comme un plafond mensuel et une liste d’autorisation de modèles facultative. Ces contrôles facilitent l’isolation d’un test, la rotation d’un identifiant ou l’arrêt d’une charge de travail sans affecter toutes les applications.

Définissez la clé dans votre shell :

export FLATKEY_API_KEY="sk-fk-your-key-here"

Si vous utilisez un fichier .env, conservez-le hors du contrôle de version :

FLATKEY_API_KEY=sk-fk-your-key-here

Étape 2 : modifiez l’URL de base

L’URL de base Flatkey compatible avec OpenAI est :

https://router.flatkey.ai/v1

C’est la modification de configuration la plus importante de ce guide de démarrage rapide. Votre clé API authentifie la requête, tandis que l’URL de base l’envoie via le routeur Flatkey plutôt que directement vers un autre endpoint de fournisseur.

Conservez ces deux valeurs dans la configuration d’environnement afin de pouvoir les modifier sans éditer la logique de l’application :

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

Utilisez les noms de variables attendus par votre framework. Certaines bibliothèques lisent OPENAI_BASE_URL ; d’autres exigent une option base_url ou baseURL lors de la création du client.

Étape 3 : envoyez votre première requête

Commencez par un prompt court et déterministe. L’objectif est de prouver l’authentification, la connectivité, l’accès au modèle et l’analyse de la réponse avant d’ajouter le streaming, les outils, la sortie structurée ou le comportement de repli.

Option A : cURL

Remplacez YOUR_CURRENT_MODEL par un modèle disponible dans le catalogue Flatkey actuel :

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

Option B : Python

Installez le client OpenAI :

pip install openai

Créez quickstart.py :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

print(response.choices[0].message.content)
print(response.usage)

Exécutez-le :

python quickstart.py

Option C : JavaScript

Installez le client :

npm install openai

Créez quickstart.mjs :

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "Reply with exactly: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Exécutez-le :

node quickstart.mjs

Étape 4 : lisez la réponse

Pour une requête standard de chat completions, commencez par quatre champs :

Une réponse simplifiée ressemble à ceci :

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

Les identifiants exacts et les comptes de tokens différeront. Votre condition de réussite du premier appel n’est pas une correspondance octet par octet ; il s’agit d’une réponse HTTP valide, d’un message d’assistant pouvant être analysé, et d’informations d’utilisation que votre application peut enregistrer.

Étape 5 : Vérifiez l’utilisation après l’appel

Ne vous arrêtez pas à 200 OK. Un quickstart utile prouve aussi que la requête est visible par les personnes qui exploiteront l’intégration.

Référence de la console

Ouvrez Console → Usage & Logs après la requête.

Recherchez le nouvel appel et confirmez les détails disponibles pour votre compte, tels que :

• L’heure de la requête.
• Le modèle ou la route.
• Le statut.
• L’utilisation des tokens.
• L’impact sur le coût ou le solde.
• Les détails d’erreur lorsqu’une requête échoue.

Si l’application a reçu une réponse mais que l’entrée de journal attendue est absente, vérifiez d’abord que vous consultez le même compte, le même espace de travail et la même clé API que ceux utilisés par la requête. Notez également l’ID de réponse et l’heure de la requête avant de réessayer ; ces deux informations facilitent grandement le dépannage.

Consultez la page de tarification Flatkey actuelle avant de passer d’un test de validation à une charge de travail soutenue. Comparez le modèle, le volume de requêtes, le mélange de tokens et le comportement de repli que vous prévoyez d’utiliser — pas seulement le coût d’un seul appel réussi.

Étape 6 : Ajoutez une séquence de repli sécurisée

Le routage de repli doit intervenir après que le premier modèle fonctionne. Sinon, une route de secours peut masquer le vrai problème : une clé invalide, une mauvaise URL de base, un modèle indisponible, une requête mal formée ou une limite de compte.

Commencez par une courte liste ordonnée de modèles que vous avez testés pour la même tâche :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Return JSON with one key named status and value ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("All approved model routes failed") from last_error

Cet exemple est volontairement minimal. Avant de l’utiliser en production, ajoutez :

• Une liste restreinte d’erreurs pouvant être retentées.
• Un délai d’attente par tentative et une échéance totale de la requête.
• Un backoff pour les défaillances transitoires.
• Des journaux structurés contenant le modèle tenté et l’ID de réponse.
• Une validation de la sortie pour le JSON, les appels d’outils ou d’autres schémas requis.
• Un plafond de coût afin que le fallback ne sélectionne pas silencieusement un itinéraire inadapté.

Ne retentez pas les erreurs d’authentification avec plusieurs modèles. Ne retentez pas les requêtes malformées tant que la requête n’a pas été corrigée. Ne considérez pas tous les modèles comme interchangeables simplement parce qu’ils acceptent une charge utile de chat-completions.

Une politique de fallback pratique

Utilisez ce tableau de décision comme point de départ :

La règle de base est simple : retentez les échecs de transport transitoires ; corrigez les échecs de configuration et de schéma ; utilisez un fallback uniquement lorsque ce fallback est approuvé pour la même tâche produit.

Erreurs courantes au premier appel

401 ou échec d’authentification

Vérifiez que la requête utilise Authorization: Bearer <key>, que la clé est active et qu’aucun espace superflu n’a été copié. Vérifiez que l’application lit la variable d’environnement attendue.

404 ou mauvais endpoint

Utilisez l’URL de base compatible OpenAI https://router.flatkey.ai/v1 et le chemin chat /chat/completions. Évitez d’ajouter accidentellement /v1 deux fois.

Modèle introuvable ou indisponible

Choisissez un modèle actuellement disponible dans le catalogue en direct ou la console. Ne supposez pas qu’un nom de modèle provenant d’un ancien tutoriel est encore activé pour votre compte.

Réponse HTTP réussie mais erreur applicative

Consignez une fois la réponse brute dans un environnement de développement sûr. Confirmez que votre code lit choices[0].message.content pour les chat completions et n’attend pas le schéma de réponse d’un autre endpoint.

Dépense inattendue pendant le fallback

Enregistrez le modèle tenté à chaque appel, limitez la liste des routes et consultez Usage & Logs. Une politique de fallback sans échéance ni plafond de coût peut transformer une action utilisateur en plusieurs requêtes facturables.

Checklist de production

Avant d’envoyer du trafic réel via l’intégration, confirmez :

• [ ] La clé API est stockée dans un gestionnaire de secrets ou dans un environnement côté serveur.
• [ ] Les environnements de développement, de préproduction et de production utilisent des clés séparées.
• [ ] L’URL de base est une configuration, et non codée en dur dans toute la base de code.
• [ ] Le modèle sélectionné est disponible et testé pour la charge de travail réelle.
• [ ] Les délais d’attente, les erreurs réessayables et les délais totaux sont explicites.
• [ ] Les modèles de secours utilisent le même contrat de sortie requis.
• [ ] Les journaux d’utilisation et d’erreur sont visibles pour l’équipe d’exploitation.
• [ ] Les attentes en matière de coût ont été vérifiées par rapport aux tarifs actuels.
• [ ] Les plafonds de clé ou les listes d’autorisation sont configurés le cas échéant.
• [ ] Un chemin de retour arrière peut restaurer rapidement la route précédente.

Faites le premier appel, puis optimisez

Le moyen le plus rapide d’évaluer Flatkey est de garder le premier test ciblé. Créez une clé, modifiez une seule URL de base, envoyez une requête, lisez une réponse et retrouvez le même appel dans Usage & Logs.

Une fois ce parcours validé, ajoutez le routage de secours comme une politique observable plutôt que comme une boucle de relance cachée. Gardez la liste des modèles approuvés courte, conservez les preuves d’erreur, validez la sortie et vérifiez les tarifs actuels avant d’augmenter le trafic.

Lorsque vous êtes prêt, créez un compte Flatkey, effectuez le premier appel via router.flatkey.ai et utilisez l’enregistrement de la console comme test d’acceptation pour votre intégration.