API Grok 4 : Un guide étape par étape avec des exemples

Premiers pas avec l'API Grok 4

Avant d'effectuer notre première requête utilisateur, nous avons besoin d'une clé API et d'un environnement Python capable de se connecter à l'API Grok.

Création de votre clé API

Pour créer une clé API que vous pourrez utiliser pour authentifier le client auprès de l'API, veuillez suivre les étapes suivantes :

1. Veuillez consulter le site officiel de documentation xAI. site de documentation xAI.
2. Veuillez vous connecter à l'aide de votre compte X, xAI ou Google. Si vous n'avez pas encore de compte, vous pouvez créer un nouveau compte xAI.
3. Recherchez l'option « Créer une clé API ». Veuillez saisir un nom pour votre clé, puis cliquez sur « Enregistrer ».
4. Une fois que votre clé apparaît, veuillez la copier immédiatement. Vous ne pourrez plus le consulter ultérieurement, mais vous pourrez toujours en générer un nouveau si nécessaire.
5. Dans le répertoire de votre projet, veuillez créer un fichier nommé .env. Veuillez vérifier que le fichier contient les informations suivantes : .env. Veuillez coller votre clé API à l'intérieur, en utilisant le format suivant :

XAI_API_KEY=<your_api_key_here>

Tarification de l'API Grok 4

Bien que l'utilisation de l'API puisse être plus abordable qu'un abonnement premium, elle n'est pas gratuite. Contrairement à l'offre SuperGrok, qui commence à 30 $ par mois pour un abonnement fixe, les coûts de l'API sont entièrement basés sur votre utilisation du service. Toutefois, si vous souhaitez accéder à Grok 4 Heavy, la procédure est différente : vous devrez disposer d'un abonnement SuperGrok Heavy actif (300 $ par mois), même si vous utilisez l'API.

Pour obtenir une liste détaillée des dépenses possibles, veuillez consulter la page des tarifs. page des tarifs sur xAI.

Source : xAI

La tarification de l'API Grok est basée sur l'utilisation, mesurée par million de jetons. À titre indicatif, un million de jetons équivaut approximativement à 750 000 mots anglais, qu'il s'agisse d'entrée ou de sortie. Bien que la taille de sa fenêtre contextuelle ait presque doublé par rapport à son prédécesseur, Grok 4 est proposé au même prix que le modèle Grok 3 standard. Vous paierez 3 $ pour chaque million de jetons entrants et 15 $ pour chaque million de jetons sortants.

Pour accéder à l'API, vous devrez acheter des crédits. Au début, il est préférable d'utiliser des crédits prépayés plutôt que la facturation automatique, ce qui vous évitera des frais imprévus. Vous pouvez acheter des jetons et suivre votre utilisation dans la console xAI, sous Factures > Crédits.

Configuration de l'environnement Python

Une fois que vous disposez de votre clé API et de vos crédits, l'étape suivante consiste à préparer votre environnement Python. Vous aurez besoin de deux paquets pour une intégration API fluide :

• python-dotenv pour charger votre clé API à partir du fichier .env en tant que variable d'environnement.
• Client de l'openai e pour interagir avec l'API Grok 4.

Afin de maintenir les dépendances de votre projet à jour, il est recommandé d'utiliser Anaconda. Après avoir installé Anaconda, configurez un nouvel environnement appelé « grok4 » avec Python 3.10 en exécutant :

conda create -n grok4 python=3.10
conda activate grok4

Une fois votre environnement activé, veuillez installer les paquets requis :

pip install python-dotenv openai

Derniers préparatifs

Commençons par écrire notre premier script. Commencez par importer les fonctions nécessaires à partir des paquets que vous avez installés, ainsi que l'os e pour accéder à votre clé API :

import os
from dotenv import load_dotenv
from openai import OpenAI

Ensuite, veuillez utiliser load_dotenv() à partir du package dotenv pour charger vos variables d'environnement, rendant ainsi votre clé API accessible au script :

# Load environment variables
load_dotenv()

Maintenant, veuillez initialiser le client API en transmettant votre clé API (provenant du fichier .env ) et l'URL du serveur Grok à la classe OpenAI (nous utiliserons le SDK OpenAI dans ce tutoriel, mais Grok 4 dispose également d'un SDK Python natif xAI). SDK xAI Python natif, qui est également compatible avec le SDK d'Antrhopic). Veuillez assigner ceci à la variable client:

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Une fois ces étapes effectuées, votre script est prêt à envoyer des requêtes à Grok 4.

Reconnaissance d'images avec Grok 4

Maintenant que le contexte est établi, testons la reconnaissance d'images, l'une des nouvelles fonctionnalités de Grok 4. Nous allons vous le démontrer en téléchargeant la photo ci-dessous d'une lasagne végétarienne et en demandant à Grok d'identifier les ingrédients visibles.

Pour analyser une image avec l'API Grok 4, nous devons envoyer une requête qui comprend à la fois une image et une invite. Il est recommandé d'utiliser un client Python compatible avec OpenAI, en spécifiant le modèle comme grok-4 et en incluant l'URL de l'image et votre question dans le tableau des messages. L'API renvoie une réponse détaillée décrivant le contenu de l'image, accessible dans l'objet de réponse.

Avant d'envoyer la demande, nous devons nous assurer que l'image répond aux exigences de l'API. Seuls les formats JPEG et PNG sont acceptés, et la taille du fichier ne doit pas dépasser 20 Mo. L'image doit être accessible via un lien direct et le serveur doit envoyer l'en-tête Content-Type correct ( image/jpeg ou image/png).

Après avoir importé les paquets nécessaires, chargé vos variables d'environnement et configuré le client, nous pouvons envoyer notre requête comme suit :

# Sending the query
response = client.chat.completions.create(
    model="grok-4",
    messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://shorturl.at/mVDEh",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Which ingredients do you notice on the picture?"
        }
      ]
    }
  ],
    max_tokens=2000,
    temperature=0.2,  # lower temperature for more deterministic answers
)

# Print the response
print(response.choices[0].message.content)

Based on the picture, it looks like a delicious slice of vegetarian lasagna! Here's what I can clearly see in terms of ingredients (I'm basing this purely on visual cues, so it's not a full recipe—just what's noticeable):
### Main Visible Ingredients:
- **Pasta sheets/lasagna noodles**: The flat, layered pasta that's the base structure of the dish.
- **Tomato sauce**: A red, chunky sauce (likely marinara or similar) that's spread between layers and on top.
- **Cheese**:
  - Melted, bubbly cheese on top (probably mozzarella or Parmesan, given the golden-brown spots).
  - White, creamy cheese in the filling layers (looks like ricotta or cottage cheese).
- **Spinach (or similar greens)**: Dark green leaves mixed into the layers, giving it a veggie-packed look (this seems like a spinach lasagna variant).
- **Basil leaf**: A fresh green leaf garnishing the top for decoration and flavor.
It doesn't appear to have any meat (like ground beef or sausage), so it's likely a vegetarian version. If this is from a specific recipe or if you have more context, I could refine my observations! What do you think it is? 😊

Dans ce cas, Grok a même reconnu qu'il s'agissait d'une version végétarienne rien qu'à partir de la photo, ce qui est assez impressionnant.

Raisonnement avec Grok 4

Grok 4 est conçu pour le raisonnement avancé et peut résoudre des problèmes complexes étape par étape. Cependant, contrairement à certains modèles précédents, Grok 4 n'expose pas ses traces de raisonnement interne, vous ne pouvez donc pas extraire un « processus de réflexion » détaillé ou une chaîne de pensée en tant que champ distinct de la réponse API. Le résultat que vous recevez est la réponse finale, et non les étapes intermédiaires du modèle ou le contenu brut du raisonnement.

De plus, Grok 4 ne prend pas en charge le paramètre d'reasoning_effort utilisé, par exemple, dans Grok 3 mini (pour savoir comment utiliser ce paramètre, veuillez consulter ce tutoriel sur l'API Grok 3). Cela signifie que vous ne pouvez pas ajuster la quantité de « réflexion » effectuée par le modèle avant qu'il ne parvienne à une conclusion finale. Par conséquent, toute requête de raisonnement est construite exactement comme une requête normale.

Mettons Grok à l'épreuve avec une autre tâche de raisonnement liée aux lasagnes et demandons-lui d'afficher son raisonnement dans la sortie.

# Send a basic reasoning query
response = client.chat.completions.create(
    model="grok-4",
    messages=[
        {"role": "user", "content": (
            "You want to cook lasagna for a dinner party, but several guests have dietary restrictions. One is vegetarian, one is lactose-intolerant, and another cannot eat gluten. You have six different lasagna recipes (classic, vegetarian, vegan, gluten-free, cheese-heavy, and meat-based). Which recipe or combination of recipes would best satisfy everyone, and what specific ingredient substitutions would you need to make? Explain your reasoning step by step."
        )}
    ],
    max_tokens=5000,
    temperature=0.2,  # lower randomness
)
# Print the final answer
print(response.choices[0].message.content)

Below, I'll explain my reasoning step by step for selecting the best recipe (or combination of recipes) to satisfy all guests at your dinner party, including the vegetarian, the lactose-intolerant person, the gluten-intolerant person, and everyone else (who presumably have no restrictions). I'll base this on logical inferences about what each recipe likely contains, since the problem doesn't provide exact ingredient lists. Then, I'll recommend specific ingredient substitutions and why this approach works.
(...)
### Step 3: Selecting the Best Recipe or Combination
- **Recommended approach**: Use a **combination of the vegan and gluten-free recipes** to create a single modified lasagna that everyone can eat. Start with the vegan recipe as your base (it already handles no meat and no lactose/dairy), then incorporate elements from the gluten-free recipe (e.g., ingredient swaps to eliminate gluten). This results in a **vegan, gluten-free lasagna**.
  - Why not multiple lasagnas? Preparing separate dishes (e.g., one vegetarian, one gluten-free) could work but might not fully satisfy everyone in a shared meal—e.g., the lactose-intolerant guest couldn't eat a dairy-based vegetarian version. A single inclusive dish promotes unity at the party and simplifies cooking/serving. If you have time and oven space, you could make a small "classic" version on the side for unrestricted guests who prefer meat and cheese, but the modified vegan/gluten-free one would still be the core option.
  - Why this combination over others? Vegan + gluten-free covers all restrictions without needing to add meat or dairy (which would violate rules). Starting with gluten-free and making it vegan would require more substitutions (e.g., removing meat and cheese), while vegan is already "80% there." Other combos (e.g., vegetarian + gluten-free) would still need dairy removals for lactose intolerance, making them less efficient.
This approach ensures:
- The vegetarian can eat it (no meat).
- The lactose-intolerant can eat it (no dairy/lactose).
- The gluten-intolerant can eat it (no gluten).
- Others can eat it (it's still a flavorful lasagna, though it won't have "real" meat or cheese—unrestricted guests might find it less indulgent, but it's a fair compromise).
(...)

J'ai raccourci la réponse de Grok afin de mettre en évidence les points essentiels, mais même dans cette version abrégée, il est évident que le modèle a bien fonctionné. Grok a procédé étape par étape pour

• Comprendre les restrictions alimentaires
• Évaluer les recettes disponibles
• Sélectionnez la meilleure combinaison de recettes.
• Veuillez suggérer des substituts pour certains ingrédients.
• Veuillez fournir un aperçu complet de la recette modifiée.
• Revenez sur les raisons pour lesquelles cela satisfait tout le monde.
• Discutez des inconvénients potentiels et des alternatives.

Appel de fonction avec Grok 4

À l'instar de son prédécesseur, Grok 4 prend en charge l'appel de fonctions. Il permet au modèle d'interagir directement avec des outils et des services externes. Cela signifie que Grok ne se limite pas à générer du texte, mais qu'il peut également effectuer des actions telles que récupérer les dernières prévisions météorologiques, vérifier les horaires d'événements, analyser des enregistrements de bases de données ou même contrôler des appareils domestiques intelligents.

Lorsque vous soumettez une requête, Grok peut déterminer si des données supplémentaires sont nécessaires et demandera qu'une fonction spécifique soit appelée avec les paramètres appropriés. Le client Python se charge d'exécuter cette fonction localement, renvoie le résultat à Grok, et vous recevez alors une réponse complète et bien argumentée.

Préparation

Pour utiliser les appels de fonction, nous devons importer le package json, qui nous permet d'accéder à la structure des arguments de toute fonction appelée par Grok. Ensuite, nous définissons une fonction de rappel que Grok invoquera lorsqu'il demandera des données spécifiques.

Dans cet exemple, la fonction « suggest_lasagna_recipe » est une simple fonction Python qui renvoie une suggestion de recette fixe. Cette approche codée en dur permet de simplifier la démonstration et d'éviter toute dépendance à des services externes.

import json

# Define the callback function
def suggest_lasagna_recipe(ingredients: list) -> dict:
    # Very simplified logic for demo purposes
    if "zucchini" in ingredients:
        return {"recipe": "Vegetarian Zucchini Lasagna"}
    if "beef" in ingredients:
        return {"recipe": "Classic Beef Lasagna"}
    if "tofu" in ingredients:
        return {"recipe": "Vegan Tofu Lasagna"}
    return {"recipe": "Basic Cheese Lasagna"}

Nous devons également définir l'outil que Grok peut appeler. Il s'agit de spécifier le nom de l'outil, son objectif et les paramètres requis dans un schéma JSON. Ce schéma est envoyé à Grok avec la requête, l'informant qu'il peut faire appel à cet outil chaque fois qu'il a besoin d'informations supplémentaires pour étayer son raisonnement.

# Define the JSON schema for the tool
tools = [
    {
        "type": "function",
        "function": {
            "name": "suggest_lasagna_recipe",
            "description": "Suggests a lasagna recipe based on available ingredients.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ingredients": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "List of available ingredients"
                    }
                },
                "required": ["ingredients"]
            }
        }
    }
]

Enfin, le dictionnaire d'tools_map s relie les noms de fonctions utilisés par Grok aux fonctions Python réelles dans votre code. Ce mappage permet au client d'exécuter correctement les appels de fonction demandés.

# link the function names to the functions
tools_map = {
    "suggest_lasagna_recipe": suggest_lasagna_recipe
}

Bien que la définition manuelle des schémas d'outils fonctionne bien pour les projets simples, l'utilisation d'une bibliothèque de validation des données telle que Pydantic est fortement recommandée à mesure que votre projet prend de l'ampleur. Pydantic assure la validation automatique des entrées de fonction, améliore la gestion des erreurs et permet d'obtenir un code plus propre et plus facile à maintenir.

Exécution

Vérifions si Grok utilise notre fonction lorsqu'on lui demande une recette de lasagnes. Voici comment se déroule le flux de travail d'appel de fonction :

1. toolsTout d'abord, nous envoyons une question utilisateur (« Quelle lasagne puis-je préparer avec les ingrédients dont je dispose ? ») à Grok, accompagnée des ingrédients disponibles. 
2. Grok examine ensuite la demande et, s'il détermine qu'un appel de fonction est nécessaire, il demande la recette en déclenchant notre fonction locale. Si aucun appel d'outil n'est effectué, nous utilisons simplement la réponse initiale de Grok.
3. Lorsqu'un appel d'outil est demandé, nous exécutons la fonction locale correspondante et ajoutons le résultat à l'historique des messages en cours.
4. Cet historique mis à jour est ensuite renvoyé à Grok, qui peut alors terminer son raisonnement et fournir une réponse finale adaptée au contexte.

# Step 1: Send the initial user request
messages = [
    {"role": "user", "content": "I have beef, ricotta, and tomato sauce. Which lasagna can I make?"}
]

response = client.chat.completions.create(
    model="grok-4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

# Step 2: Check if a tool call was requested
tool_calls = getattr(response.choices[0].message, "tool_calls", [])


if tool_calls:
    for tool_call in tool_calls:
        function_name = tool_call.function.name
        print(f"{function_name} successfully called")
        function_args = json.loads(tool_call.function.arguments)

        # Find and call the matching local function
        if function_name in tools_map:
            function_result = tools_map[function_name](**function_args)

            # Step 3: Add the function result back to the message history
            messages.append(response.choices[0].message)  # Assistant's tool call message
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(function_result)
            })

            # Step 4: Send a new request including the tool response
            final_response = client.chat.completions.create(
                model="grok-4",
                messages=messages,
                tools=tools,
                tool_choice="auto"
            )

            # Print the final answer
            print("\nFinal Answer:")
            print(final_response.choices[0].message.content)
   
else:
    # No tool call: respond directly
    print("\nNo tool call was requested. Final Answer:")
    print(response.choices[0].message.content)

suggest_lasagna_recipe successfully called

Final Answer:
Based on your available ingredients (beef, ricotta, and tomato sauce), you can make a **Classic Beef Lasagna**! (...)

Comme nous pouvons le constater, Grok a appelé notre fonction et a suggéré la recette correspondante.

Vous remarquerez peut-être également l'argument tool_choice dans la requête initiale. Par défaut, « auto » permet à Grok de décider s'il convient d'appeler une fonction et, le cas échéant, laquelle. Si vous souhaitez davantage de contrôle, vous pouvez forcer l'appel d'une fonction spécifique, spécifier exactement quelle fonction utiliser ou désactiver complètement l'appel de fonction en modifiant ce paramètre.

Sorties structurées avec Grok 4

À l'instar des appels de fonction, les sorties structurées sont une fonctionnalité introduite avec Grok 3. Ils permettent à Grok de fournir des réponses dans un format strict tel que JSON plutôt que du texte brut. Cette approche facilite considérablement l'analyse, la validation et l'utilisation des réponses du modèle dans vos applications ou vos flux de travail.

En configurant un schéma à l'avance, vous pouvez être certain que les résultats fournis par Grok sont toujours cohérents, lisibles par une machine et prêts à être traités ultérieurement. Cette fonctionnalité est particulièrement utile lorsque vous devez extraire des données structurées de documents ou envoyer du contenu généré par l'IA directement vers des bases de données, des tableaux de bord ou des outils d'automatisation, sans vous soucier de l'inefficacité de l'analyse syntaxique du texte.

Pour définir le schéma de sortie, nous utilisons Pydantic, qui simplifie la structuration des données complexes et les rend plus lisibles (ceci tutoriel Pydantic vous aidera à en savoir plus). Pour cela, vous devrez importer les fichiers BaseModel et Field depuis pydantic. Étant donné que notre sortie contient une liste d'ingrédients, nous importons également List depuis le module typing de Python afin de spécifier clairement le type de chaque élément de la liste.

Bien que nous puissions configurer le schéma à l'aide de JSON simple, Grok renvoie parfois des résultats qui ne correspondent pas exactement à la structure attendue. La signification peut être la même, mais le schéma peut différer, ce qui peut poser des problèmes si votre application nécessite un format spécifique. Ceci est particulièrement vrai pour les éléments imbriqués tels que les listes. C'est pourquoi je recommande l'utilisation de Pydantic, qui permet de s'assurer que la sortie structurée est validée et analysée de manière fiable à chaque fois.

Dans notre exemple, le schéma, appelé « Recipe», comprend son nom, le nombre de portions et une liste d'ingrédients. Ingredient Chaque ingrédient est défini par son nom, la quantité nécessaire pour la recette, sa disponibilité, son prix au kilogramme et des informations indiquant s'il est végétarien, végétalien ou sans gluten. Il est pratique de définir des valeurs par défaut dans le schéma lui-même, comme nous le faisons pour le nombre de portions.

# import additionally needed packages
from pydantic import BaseModel, Field
from typing import List

# Define the schema for the structured output
class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient")
    amount: int = Field(description="Amount in g needed for recipe")
    is_at_home: bool = Field(description="Is the item already at home?")
    price: float = Field(description="Price of the ingredient in USD per kg")
    is_vegetarian: bool = Field(description="Is the ingredient vegetarian?")
    is_vegan: bool = Field(description="Is the ingredient vegan?")
    is_gluten_free: bool = Field(description="Is the ingredient gluten-free?")

class Recipe(BaseModel):
    name: str = Field(description="The name of the recipe")
    portions: int = Field(default=4, description="Amount of portions")
    ingredients: List[Ingredient] = Field(description="List of ingredients for the recipe")

Il y a quelques détails à prendre en compte lors de la demande. Au lieu d'utiliser « client.chat.completions.create() », nous souhaitons appeler « client.beta.chat.completions.parse() ». Cela indique à Grok que nous attendons une sortie dans un format spécifique, et notre schéma d'Recipes est transmis en tant qu'argument response_format.

Il est également utile de saisir toutes les instructions clés relatives à la tâche dans l'invite du système. Cela permet à Grok 4 de rester concentré et cohérent tout au long de la conversation. Comme le schéma est défini séparément, l'invite utilisateur peut se concentrer sur la tâche elle-même, sans avoir à répertorier les champs requis pour le JSON de sortie.

Par exemple, vous pourriez configurer Grok pour qu'il joue le rôle d'un chef italien, en veillant à ce que toutes les recettes qu'il propose soient authentiquement italiennes, afin que vous ne trouviez pas d'ananas dans votre pizza.

# Send a prompt and request structured output
completion = client.beta.chat.completions.parse(
    model="grok-4",
    messages=[
        {"role": "system", "content": (
        "You are a master chef specialized in italian cuisine."
        "When asked about recipes, return the output in structured JSON format following the provided schema, without any extra text."
        )},
        {"role": "user", "content": (
        "I have beef, ricotta, and tomato sauce, and want to cook for 4 persons. Which lasagna can I make?"
        )}
    ],
    response_format=Recipe,
)

Une fois que nous avons analysé la sortie structurée de Grok 4, ses avantages par rapport au texte brut apparaissent clairement. Nous pouvons facilement réorganiser et personnaliser les informations en fonction de nos besoins, voire intégrer directement des données spécifiques dans des flux de travail automatisés. Dans notre exemple, cela signifie que nous pouvons rapidement multiplier le prix des ingrédients au kilogramme par les quantités requises, additionner les coûts en fonction de ce qui se trouve déjà dans le garde-manger et calculer le prix final par portion en quelques étapes seulement.

# Access the parsed result
recipe = completion.choices[0].message.parsed


price = 0 # initialize price variable
print(f"Recipe: {recipe.name}")
print("Ingredients:")
for i in recipe.ingredients:
    print("- " + i.name + " " + str(i.amount) + " g")
    if not i.is_at_home:
        price += (i.price * i.amount / 1000)
print(f"Price per portion: USD {round((price/recipe.portions), 2)}")

Recipe: Classic Beef Lasagna
Ingredients:
- Ground beef 500 g
- Ricotta cheese 400 g
- Tomato sauce 800 g
- Lasagna noodles 300 g
- Mozzarella cheese 300 g
- Parmesan cheese 100 g
- Onion 200 g
- Garlic 20 g
- Olive oil 30 g
- Egg 50 g
Price per portion: USD 1.7625

Conclusion

Grok 4 offre de nouvelles fonctionnalités telles qu'une fenêtre contextuelle plus grande et de meilleures capacités de raisonnement. Sa reconnaissance d'images et son appel de fonctions ouvrent des possibilités intéressantes pour combiner l'IA avec des données et des actions du monde réel, tandis que ses résultats structurés garantissent des réponses fiables et lisibles par les machines. La configuration de l'API est simple, ce qui permet une intégration rapide dans vos projets Python avec seulement quelques dépendances.

Et si tous ces exemples de lasagnes vous ont donné faim, vous n'êtes pas le seul. Je vais peut-être me servir une part moi-même !