Comment utiliser l'API de génération d'images Grok Image 2.0 ? Première image en 5 minutes

Comment utiliser l'API de génération d'images Grok Image 2.0 ? Trois étapes : POST /v1/tasks pour créer une tâche, récupérer le taskId puis interroger en boucle (ou configurer un callback), et télécharger l'image générée depuis data.output[0].url. Une image pour $0.052, même prix en 1K et en 2K.

Grok Image 2.0 est déjà disponible sur HiAPI, ouvrez la page du modèle pour générer directement ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription, de quoi produire une première image pour voir le résultat.

TL;DR

• De quoi s'agit-il : grok-imagine-image-2.0/text-to-image, un modèle de génération d'images par xAI, accessible via l'interface de tâches asynchrones unifiée de HiAPI.
• Combien ça coûte : $0.052 par image, que ce soit en 1K / 2K, en low / medium, ou pour n'importe quel format ; facturation à l'image générée avec succès, remboursement automatique en cas d'échec. $10 permettent d'obtenir environ 192 images.
• Comment l'appeler au plus vite : un simple prompt suffit pour générer une image ; trois paramètres optionnels : aspect_ratio, resolution, quality.

Quels sont les paramètres de la génération d'images Grok Image 2.0 ?

input ne contient que quatre champs :

Champ	Obligatoire	Valeurs	Description
prompt	Oui	Chaîne de caractères	Description de l'image
aspect_ratio	Non	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto	Par défaut 1:1
resolution	Non	1k, 2k	Par défaut 1k
quality	Non	low, medium	Par défaut medium ; medium offre plus de détails, low est plus rapide

Chaque tâche produit 1 image ; pour un traitement par lots, soumettez plusieurs tâches en parallèle. Les champs ou valeurs hors de ce tableau renvoient une erreur 400, avec un message indiquant le champ concerné.

Deux approches : essai en ligne et API

Essai en ligne (1 minute)

1. Ouvrez la page du modèle de génération d'images et connectez-vous.
2. Saisissez un prompt, choisissez le format et la résolution.
3. Cliquez sur « Exécuter », puis consultez et téléchargez l'image une fois la tâche réussie.

Intégration API (5 minutes)

1. Créez une API Key dans la console.
2. Soumettez une tâche avec POST /v1/tasks.
3. Interrogez en boucle GET /v1/tasks/<taskId>, ou configurez un callback.
4. En cas de succès, téléchargez immédiatement data.output[0].url.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Commencez par un prompt qui fonctionne : celui ci-dessous produit une photo produit en 3:2, générez avec ce prompt → (choisissez le ratio 3:2 et la résolution 2K)

curl et Python : générer sa première image

Commencez par définir l'API Key :

export HIAPI_API_KEY="sk-..."

Toutes les requêtes incluent Authorization: Bearer sk-<key>. La génération d'images est asynchrone et partage la même interface de tâches que les autres modèles HiAPI.

Étape 1, créer la tâche :

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Renvoie immédiatement le taskId :

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67" }
}

Étape 2, interroger jusqu'à l'état final :

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Consultez data.status : success indique un succès, fail un échec ; pour les autres états, continuez d'attendre. Exemple de réponse réussie :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Attention à storage: "temp" et expireAt : l'adresse de l'image générée est temporaire, téléchargez-la dès la fin de la tâche ou transférez-la vers votre propre stockage objet.

Version Python :

Installez d'abord requests (python3 -m pip install requests) et définissez la variable HIAPI_API_KEY ci-dessus. Le script interroge pendant 10 minutes maximum ; en cas de dépassement, conservez le taskId pour continuer à interroger.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

À quoi faire attention avant la mise en production ?

• Pour le traitement par lots, utilisez un callback plutôt qu'une boucle d'interrogation serrée. Ajoutez callback lors de la création de la tâche, et HiAPI enverra une notification à votre adresse à la fin de la tâche :

  {
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": { "prompt": "..." },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" notifie lorsque la tâche atteint l'état final de succès ou d'échec ; le récepteur déduplique par taskId. Utilisez l'interrogation pour les pages interactives et le callback pour le traitement par lots.

• Transférez immédiatement l'image générée. data.output[0].url est une adresse temporaire, qui expire selon expireAt.

• Ne soumettez une tâche qu'une seule fois. Après réception de la réponse, enregistrez la correspondance entre le taskId et votre tâche métier ; une soumission en double peut créer plusieurs tâches et être facturée séparément. Si la requête de création expire sans renvoyer d'ID, vérifiez d'abord l'historique des tâches avant de décider de resoumettre.

• Spécifiez explicitement resolution. La valeur par défaut est 1k ; à prix égal en 1K et 2K, passez directement "resolution": "2k" pour la version finale.

• Utilisez quality: low pour itérer sur le prompt. Même prix, retour plus rapide ; repassez en medium pour la version définitive.

• Gestion des erreurs. Vérifiez d'abord le statut HTTP et les champs code et message de la réponse, puis lisez data. Corrigez les erreurs de paramètres ou d'authentification avant de resoumettre ; si la tâche renvoie fail, enregistrez l'erreur et arrêtez l'interrogation.

À lire également

• Combien coûte l'API Grok Image 2.0 ? Génération d'images à $0.052 l'image, sans surcoût en 2K
• Prompts de génération d'images Grok Image 2.0 : 5 scénarios à copier directement
• Intégration de l'API image-à-image Grok Image 2.0 : modifier une image à partir d'une seule image de référence
• Grok Image 2.0 vs GPT Image 2 : comparaison à prompt identique
• Authentification et démarrage rapide

Questions fréquentes

Comment écrire l'ID du modèle ? Écrivez le nom complet grok-imagine-image-2.0/text-to-image, en conservant le numéro de version 2.0 et le suffixe /text-to-image.

Que faire en cas d'erreur « additional properties not allowed » ? input n'accepte que les quatre champs prompt, aspect_ratio, resolution et quality ; les champs courants d'autres modèles comme size, n, seed, negative_prompt ou output_format ne sont pas disponibles ici, supprimez-les.

Peut-on générer plusieurs images à la fois ? Non, chaque tâche produit 1 image. Pour en obtenir plusieurs, soumettez plusieurs tâches en parallèle.

Combien de temps l'adresse de sortie reste-t-elle valide ? Le stockage est temporaire ; le champ expireAt de la réponse est un horodatage Unix. Téléchargez ou transférez l'image dès la fin de la tâche.

Faut-il attendre le résultat de façon synchrone ? Non. L'interface de création renvoie immédiatement après la mise en file de la tâche ; pour les petits scripts, interrogez GET /v1/tasks/<taskId>, en production configurez callback.

Les tâches échouées sont-elles facturées ? Non, la facturation se fait à l'image générée avec succès, avec remboursement automatique en cas d'échec. Arrêtez l'interrogation lorsque data.status vaut fail.

Générez votre première image dès maintenant

Définissez d'abord HIAPI_API_KEY, créez une tâche avec le curl ci-dessus, puis interrogez avec le data.taskId renvoyé ; une fois la tâche réussie, téléchargez depuis data.output[0].url. Pour voir le résultat d'abord, ouvrez la page du modèle de génération d'images ; les 200 crédits offerts à l'inscription suffisent pour 1 image.