Comment utiliser l'API text-to-image grok-imagine-quality : curl, Python et une requête exécutable

Résumé

• De quoi s'agit-il : une solution exécutable pour utiliser l'API grok-imagine-quality/text-to-image sur hiapi — créez une tâche via POST /v1/tasks, interrogez GET /v1/tasks/<taskId> (ou utilisez un callback), puis téléchargez l'image depuis output[0].url.
• Un schéma strict et minimal : prompt (obligatoire), aspect_ratio (13 ratios, par défaut 1:1), resolution (1k | 2k, en minuscules, par défaut 1k), output_format (jpeg | png | webp, par défaut jpeg). Tout autre champ est rejeté avec un code 400.
• « Quality » désigne un palier, pas un réglage. Il n'existe aucun paramètre quality ou rich_detail — des détails, des textures et un éclairage plus riches sont précisément ce que cette variante de modèle offre par défaut. Si vous avez besoin de brouillons économiques en masse, le modèle frère de palier standard grok-imagine/text-to-image est disponible sur le même endpoint.
• Les URL de sortie comportent une échéance expireAt — téléchargez rapidement ou stockez de façon persistante.

Ce que vous allez construire, et ce qu'il faut préparer

Objectif : envoyer une invite textuelle à grok-imagine-quality/text-to-image et récupérer un fichier image final utilisable comme visuel principal — d'abord avec curl, puis sous forme d'un petit script Python intégrable dans une file de tâches.

Il vous faut une seule chose : une clé d'API hiapi. Obtenez-la depuis votre console hiapi et exportez-la :

export HIAPI_API_KEY="sk-..."

Chaque requête s'authentifie avec l'en-tête bearer standard : Authorization: Bearer sk-<key>.

Requête minimale exécutable (curl)

La génération d'images sur hiapi est uniquement asynchrone. Vous n'attendez pas un appel HTTP de longue durée ; vous créez une tâche puis récupérez le résultat une fois terminée.

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

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "Visuel principal produit d'une machine à espresso noir mat posée sur un plan de travail en ardoise, éclairage directionnel dramatique, faible profondeur de champ, rendu commercial haut de gamme",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Pendant que le modèle travaille en arrière-plan, vous recevez immédiatement un taskId :

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

Étape 2 — interroger jusqu'à l'état terminal :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

La tâche passe par queued → handling → archiving, puis atteint success ou fail. Seul success contient des sorties :

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Étape 3 — télécharger avant expireAt :

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Le même processus en Python

Un script complet — créer, interroger, enregistrer. Copiez, définissez HIAPI_API_KEY, exécutez.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "Visuel principal produit d'une machine à espresso noir mat posée sur un plan de travail en ardoise, "
            "éclairage directionnel dramatique, faible profondeur de champ, rendu commercial haut de gamme"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # en minuscules ! "2K" est rejeté avec un code 400
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # un 4xx ici = la requête elle-même est rejetée
task_id = resp.json()["data"]["taskId"]
print("Tâche créée :", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png enregistré")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Échec de la tâche : {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving —— continuer à interroger

La génération au palier 2k se termine généralement en une ou deux minutes ; un intervalle d'interrogation de 5 secondes suffit.

Les paramètres qui existent réellement

Le schéma d'entrée est strict — les champs inconnus échouent avec 400 INVALID_REQUEST: additional properties not allowed, au lieu d'être ignorés silencieusement. C'est une bonne chose : les fautes de frappe ne passeront pas en production. Voici la surface complète de l'interface :

Champ	Obligatoire	Valeurs	Valeur par défaut
input.prompt	Oui	texte libre	—
input.aspect_ratio	Non	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1
input.resolution	Non	1k, 2k (minuscules uniquement)	1k
input.output_format	Non	jpeg, png, webp	jpeg

Trois choses méritent d'être connues avant de construire dessus :

• « quality » dans le nom désigne un palier, pas un paramètre. Vous verrez peut-être ce modèle décrit comme offrant des détails, des textures et un éclairage plus riches — c'est la variante de modèle elle-même. Aucun champ rich_detail, quality ou style activable.
• 1k et 2k sont facturés selon des paliers différents. Schéma courant : itérer sur l'invite en 1k, puis relancer l'invite gagnante en 2k pour produire l'asset final. Le prix actuel par image figure sur la page de tarification hiapi.
• Pas de n, pas de seed, pas de negative_prompt. Une tâche génère une image. Pour des variantes, soumettez plusieurs tâches en parallèle — elles sont indépendantes et mises en file de façon concurrente.

Considérations de production : callbacks, idempotence et erreurs

En production, privilégiez les callbacks à l'interrogation. Passez callback au niveau supérieur du corps de la requête (pas dans input) ; hiapi appellera votre service lorsque la tâche atteint un état terminal :

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

Avec when: "final", success et fail déclenchent tous deux une notification ; dédupliquez donc de votre côté par taskId. Conservez une interrogation à basse fréquence comme filet de sécurité au cas où un callback serait perdu — l'endpoint de détail de tâche reste toujours la source de vérité.

Rendez les réessais sûrs avec Idempotency-Key. La création de tâche accepte l'en-tête Idempotency-Key (255 octets maximum). Un réessai avec la même clé ne créera jamais de tâche en double — la relecture renvoie le taskId d'origine :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Distinguez et traitez trois formes d'échec :

1. Échec d'authentification — HTTP 401 et {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Vérifiez la clé et ses droits sur ce modèle ; ne réessayez pas à l'aveugle.
2. Entrée invalide — HTTP 400 et "error_code": "INVALID_REQUEST", le message indiquant le champ précis (par exemple resolution: value must be one of '1k', '2k'). Corrigez le payload ; réessayer avec le même corps échouera de la même façon.
3. Échec au niveau de la tâche — l'appel de création réussit, mais la tâche se termine avec status: "fail" et un objet data.error. Vérifiez error.code avant de soumettre à nouveau.

Surveillez expireAt. Les URL de sortie sont temporaires. Téléchargez le fichier immédiatement après le succès de la tâche, ou passez storage: "persistent" à la création pour conserver les sorties à long terme.

Pages connexes

• Page du modèle grok-imagine-quality/text-to-image — aire de test et tarification par palier
• Référence complète des paramètres dans la documentation
• Référence de l'API de création de tâche — en-têtes, idempotence, callbacks
• Comment utiliser grok-imagine-quality image-to-image — même palier, pour modifier une image existante
• Tous les modèles d'image, de vidéo et de musique

Questions fréquentes

Quelle est la différence entre grok-imagine-quality et grok-imagine/text-to-image ? Même endpoint, même structure de requête, paliers différents. Le palier quality vise les visuels principaux et les assets commerciaux, avec des détails et un éclairage plus riches, et est facturé selon les paliers de résolution 1k/2k ; la version standard grok-imagine/text-to-image est une option plus rapide et moins chère pour le volume et l'idéation.

Pourquoi "resolution": "2K" renvoie-t-il une erreur 400 ? L'énumération est sensible à la casse et en minuscules : 1k ou 2k. Les valeurs en majuscules sont rejetées avec INVALID_REQUEST.

Peut-on définir une taille exacte en pixels comme 1920x1080 ? Non. Vous contrôlez la forme avec aspect_ratio (13 options, de 2:1 ultra-large à 9:20 ultra-haut), et la netteté avec les paliers 1k/2k. Ce modèle n'a pas de champ size libre.

Peut-on générer plusieurs images en une seule requête ? Non — il n'y a pas de paramètre n. Soumettez plusieurs tâches en parallèle ; chaque tâche renvoie son propre taskId et est traitée de façon concurrente.

grok-imagine-quality prend-il en charge l'image-to-image ? Oui, avec un identifiant de modèle distinct : grok-imagine-quality/image-to-image. Son schéma est décrit dans la solution image-to-image — il diffère de celui du text-to-image.

Combien de temps les URL de résultat sont-elles valides ? Chaque entrée output[] comporte un horodatage Unix expireAt. Téléchargez avant cette échéance, ou utilisez storage: "persistent" à la création de la tâche (ou promouvez la sortie plus tard) pour la conserver.

À quoi ressemble une tâche en file d'attente mais non terminée ? GET /v1/tasks/<taskId> renvoie un status égal à queued, handling ou archiving, sans output encore. Seul success contient une sortie téléchargeable ; fail contient data.error.