Chat Completions avec cURL sur plusieurs modèles d’IA

Vous pouvez en apprendre davantage sur une passerelle d’IA en une seule commande de terminal qu’avec une longue liste de fonctionnalités. Si la passerelle est réellement compatible OpenAI, la même requête curl doit fonctionner sur les familles de modèles prises en charge, tandis que l’URL de base, l’en-tête d’autorisation, le format des messages et l’analyse de la réponse restent stables.

Ce tutoriel montre la méthode pratique avec Flatkey : commencez par une requête de chat-completions, placez le nom du modèle dans une variable et testez plusieurs familles de modèles actuelles sans réécrire l’intégration. Il est conçu pour les développeurs qui souhaitent valider une API depuis un terminal avant d’ajouter un SDK ou de valider du code applicatif.

Note sur la sélection du modèle : Les catalogues de modèles changent. Les identifiants de modèle ci-dessous reflètent la documentation publique de Flatkey vérifiée le 24 juillet 2026. Confirmez la ligne du modèle et sa disponibilité actuelles avant d’utiliser un identifiant en production.

The shortest working chat-completions cURL request

Créez une clé API Flatkey, exportez-la dans votre shell et envoyez une requête vers le point de terminaison chat-completions compatible OpenAI :

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Rédigez une description produit en une phrase pour un sac à dos de jour imperméable."
      }
    ]
  }'

Quatre éléments importent :

Pour les modèles de chat compatibles, le principal champ que vous changez est model.

Use the same cURL shape across model families

Placez l’ID du modèle dans une variable de shell afin que le corps de la requête n’ait pas besoin d’être modifié :

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Renvoyez un texte e-commerce concis.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Rédigez un titre de produit pour un sac à dos de jour léger et imperméable.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Relancez maintenant la commande avec un autre identifiant de modèle documenté :

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

La requête utilise toujours le même endpoint, les mêmes en-têtes, les mêmes messages et le même parseur jq. Cette forme d’appel stable est l’avantage opérationnel : vous pouvez comparer des familles de modèles prises en charge sans maintenir un script de terminal distinct pour chaque fournisseur.

Note sur la sélection du modèle : Une forme de requête partagée ne signifie pas que chaque modèle se comporte de manière identique. Les paramètres pris en charge, les limites de contexte, le comportement des outils, le comportement en matière de sécurité, la latence et le style de sortie peuvent différer. Considérez la compatibilité comme une surface d’intégration plus simple, et non comme une preuve que les modèles sont interchangeables.

Exécuter une petite boucle de test multi-modèles

Pour une comparaison rapide dans le terminal, définissez une courte liste et envoyez le même prompt à chaque modèle :

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Définissez d’abord FLATKEY_API_KEY}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Utiliser jq -n pour construire du JSON est plus sûr que d’échapper manuellement une longue chaîne shell. Cela rend aussi le script plus facile à étendre avec des variables, des messages supplémentaires ou des paramètres facultatifs.

Enregistrez le script sous le nom compare-models.sh, rendez-le exécutable, puis lancez-le :

chmod +x compare-models.sh
./compare-models.sh

Que comparer dans la sortie

Un test multi-modèles n’est utile que si le prompt et la méthode d’évaluation sont cohérents. Pour une tâche de rédaction e-commerce, comparez :

Ajoutez les champs de timing cURL lorsque la latence compte :

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Write a five-word product tagline."}
    ]
  }'

jq . response.json

Cela sépare les mesures de transport de la sortie du modèle. Le terminal affiche le statut HTTP et le temps total de la requête, tandis que la réponse JSON reste disponible pour inspection.

Note sur la sélection du modèle : Ne choisissez pas un modèle de production à partir d’une seule réponse. Exécutez un ensemble de prompts représentatifs, répétez les requêtes et évaluez les sorties selon les exigences qui comptent pour votre application.

Gardez la requête comparable

De petites modifications du prompt ou des paramètres peuvent rendre un test de modèle trompeur. Utilisez ces contrôles :

1. Gardez les messages identiques. N’améliorez pas le prompt pour un modèle mais pas pour les autres.
2. Utilisez la même température. Des valeurs plus basses rendent généralement les comparaisons plus faciles à examiner.
3. Capturez le JSON brut. Stockez la réponse complète, et pas seulement le texte rendu.
4. Enregistrez l’ID du modèle. Un nom d’affichage n’est pas assez précis pour des tests reproductibles.
5. Séparez les erreurs des mauvaises réponses. Une erreur de transport ou de disponibilité n’est pas un score de qualité de sortie.
6. Vérifiez la disponibilité actuelle. Un modèle documenté peut malgré tout avoir un statut opérationnel changeant.

Ajoutez une gestion de base des échecs

Utilisez --fail-with-body pour que cURL quitte en cas d’erreurs HTTP tout en conservant le corps de la réponse :

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Return the word ready."}
    ]
  }'; then
  jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

Dans le code applicatif, ajoutez également des délais d’attente explicites, des tentatives limitées pour les échecs réessayables, et une journalisation qui n’expose pas les clés secrètes ni le contenu sensible des prompts.

Une politique pratique de sélection de modèle

La politique la plus simple consiste à choisir en fonction de la charge de travail plutôt que du nom du fournisseur :

Commencez avec le plus petit modèle qui franchit de manière fiable votre seuil de qualité. Passez à un modèle plus puissant lorsque la tâche l’exige. Si vous ajoutez un routage de secours, testez le secours avec le même contrat de réponse plutôt que de supposer qu’il peut remplacer le modèle principal sans modification de l’application.

Vous pouvez consulter l’accès actuel aux modèles et la tarification sur la page tarifaire de Flatkey avant de sélectionner les identifiants pour un test en production.

Quand passer de cURL à un SDK

cURL est idéal pour vérifier rapidement quatre choses :

• la clé API fonctionne
• l’URL de base est correcte
• le modèle sélectionné accepte la requête
• la forme de la réponse correspond à votre analyseur

Passez à un SDK lorsque vous avez besoin d’aides au streaming, d’une logique de réessai structurée, de réponses typées, de clients réutilisables ou d’une observabilité au niveau de l’application. Conservez la requête cURL réussie dans votre runbook : elle reste le moyen le plus rapide de distinguer les problèmes d’accès à la passerelle des problèmes de configuration du SDK.

Liste de contrôle finale d’implémentation

• Exportez la clé API au lieu de la placer directement dans les scripts.
• Utilisez https://router.flatkey.ai/v1 comme URL de base.
• Envoyez des requêtes de chat compatibles à /chat/completions.
• Déplacez l’identifiant du modèle dans la configuration.
• Générez le JSON avec jq lorsque l’échappement dans le shell devient complexe.
• Capturez le statut HTTP, la latence, le contenu de la réponse et les données d’utilisation.
• Comparez les modèles avec des prompts et des paramètres identiques.
• Vérifiez la disponibilité actuelle du catalogue avant le déploiement en production.
• Ajoutez des délais d’expiration, des réessais bornés et une journalisation sûre pour les secrets dans le code applicatif.

Une requête cURL stable vous donne un point de départ propre. Une fois qu’elle fonctionne, la modification du champ model transforme cette requête en un banc de test pratique pour plusieurs familles de modèles d’IA — sans changer à chaque fois l’authentification, l’URL de base ou l’analyseur de réponse.

Questions fréquemment posées

Puis-je utiliser la même requête cURL chat-completions pour chaque modèle d’IA ?

Utilisez-la pour les modèles que Flatkey expose via la route chat-completions compatible. D’autres modalités ou des fonctionnalités spécifiques au protocole peuvent nécessiter des points de terminaison ou des champs de requête différents.

Quel est l’ensemble minimal de champs pour une requête chat-completions ?

Pour une requête de base, fournissez un model pris en charge et un tableau messages. Vous avez également besoin de l’en-tête d’autorisation Bearer et du type de contenu JSON.

Pourquoi mettre le nom du modèle dans une variable d’environnement ?

Elle maintient la structure de la requête stable, réduit les erreurs de modification et facilite l’exécution des scripts dans les configurations de préproduction, d’évaluation et de production.

Dois-je utiliser cURL en production ?

cURL est excellent pour la vérification, les scripts et les runbooks. La plupart des applications de production tirent parti d’un SDK ou d’un client HTTP avec prise en charge explicite des délais d’attente, des tentatives, de la télémétrie et du traitement des types.

Comment choisir entre les modèles GPT, Claude, Gemini et DeepSeek ?

Choisissez à l’aide d’un ensemble d’évaluation représentatif. Comparez le suivi des instructions, la qualité des résultats, la latence, l’utilisation des jetons, le comportement en cas d’erreur et les fonctionnalités spécifiques requises par votre charge de travail. Vérifiez la disponibilité actuelle avant le déploiement.