Endpoint /v1/images/generations : premiers pas

Générer votre première image avec l’API Grok

L’API xAI propose un endpoint dédié à la génération d’images : POST /v1/images/generations. Ce point d’entrée vous permet de créer des images à partir d’une description textuelle, en exploitant les modèles Grok Imagine. Que vous souhaitiez produire des illustrations, des visuels marketing ou des prototypes créatifs, tout commence par cet endpoint.

Dans cette leçon, vous allez découvrir comment structurer une requête de génération d’image et comprendre les paramètres fondamentaux.

Structure d’une requête de génération

Deux paramètres suffisent à générer une image : le modèle et le prompt. Tous les autres ont une valeur par défaut, ce qui permet d’obtenir un premier résultat en trois lignes — et c’est exactement ce qu’il faut faire avant de lire le reste, pour avoir une image sous les yeux à laquelle rapporter chaque paramètre.

from openai import OpenAI
import os

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

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Un phare breton sous un ciel étoilé, style aquarelle"
)

image_url = response.data[0].url
print(image_url)

L’API xAI est compatible avec le SDK OpenAI pour la génération d’images : vous pointez la base_url vers https://api.x.ai/v1, vous fournissez votre clé xAI, et le reste de votre code demeure inchangé. Retenez bien la portée de cette compatibilité — elle vaut pour la génération, mais pas pour l’édition, qui attend un format différent. La leçon 5 y revient.

Paramètres de la requête

Voici les paramètres que vous pouvez inclure dans votre requête :

• model (obligatoire) : le modèle de génération à utiliser
• prompt (obligatoire) : la description textuelle de l’image souhaitée
• n : le nombre d’images à générer (1 à 10, défaut : 1)
• aspect_ratio : le ratio d’aspect de l’image
• resolution : la résolution (1k ou 2k)
• response_format : url (défaut) ou b64_json pour recevoir l’image en Base64

Exemple avec tous les paramètres

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Une forêt enchantée avec des lucioles, style digital art",
    n=2,
    aspect_ratio="16:9",
    resolution="2k",
    response_format="url"
)

for image in response.data:
    print(image.url)

Format de la réponse

La réponse est toujours un tableau, même pour une seule image — parcourez-le plutôt que de lire data[0], sans quoi votre code cassera le jour où vous passerez n=4. Chaque objet contient :

• url : l’URL temporaire de l’image (si response_format est url)
• b64_json : les données Base64 de l’image (si response_format est b64_json)

Le type MIME retourné peut être image/png, image/jpeg ou image/webp.

Mise en pratique

Essayez de générer votre première image en adaptant le prompt à votre contexte professionnel. Par exemple, pour un visuel de présentation :

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Graphique minimaliste montrant la croissance d'une startup, "
           "couleurs bleu et blanc, fond sombre, style flat design",
    resolution="2k",
    aspect_ratio="16:9"
)

Points clés à retenir

• L’endpoint de génération est POST /v1/images/generations
• Deux paramètres sont obligatoires : model et prompt
• L’API est compatible avec le SDK OpenAI Python en changeant la base_url
• Vous pouvez générer jusqu’à 10 images par requête
• Les résolutions disponibles sont 1k et 2k