API Grok Imagine pour les images : génération texte-image, image-image et Quality

Points essentiels

• L'API Grok Imagine pour les images sur HiAPI compte quatre points de terminaison : standard et Quality, chaque version proposant la génération texte-image et image-image. La structure des requêtes est identique pour les quatre, seul l'identifiant du modèle change.
• La version standard coûte $0.03 par image, que ce soit en résolution 1K ou 2K. Quality coûte $0.07 en 1K et $0.10 en 2K. La génération image-image facture un léger supplément par image de référence (1 à 3 références).
• Avec le même prompt, la version standard a dessiné un cône ordinaire sans poignée ni nervures de guidage ; Quality a dessiné un dripper à café à infusion lente reconnaissable. Utilisez la version standard pour les brouillons et les traitements en grande série, et Quality pour les rendus finaux. Ouvrez la page du modèle texte-image pour essayer ; les nouveaux comptes reçoivent 200 crédits gratuits.

Quel point de terminaison choisir

Identifiant du modèle	Entrée	Prix par image	Cas d'usage
grok-imagine/text-to-image	Prompt	$0.03 (1K et 2K)	Brouillons, génération en masse, bannières ultra-larges
grok-imagine-quality/text-to-image	Prompt	$0.07 (1K) / $0.10 (2K)	Visuels produits finaux, détails et matières
grok-imagine/image-to-image	Prompt + 1 à 3 images	$0.03 + $0.003 par image de référence	Intégrer un produit dans une scène, retouche en masse
grok-imagine-quality/image-to-image	Prompt + 1 à 3 images	$0.08 (1K) / $0.10 (2K) + $0.015 par image de référence	Relighting et changement de style en conservant un sujet parfaitement identique

Tarifs HiAPI en temps réel, consultés le 19 octobre 2026. Les tâches échouées ne sont pas facturées.

La retouche d'une seule image de référence coûte $0.033 en standard et $0.095 en Quality 1K. Pour découvrir la gamme complète, y compris la vidéo et Grok Imagine Image 2.0, consultez Tarification de l'API Grok Imagine.

Un même prompt, standard vs Quality

1:1, 2K, PNG, une exécution pour chaque :

matte ceramic pour-over coffee dripper on a pure white seamless background, studio softbox lighting, centered, no shadow gradient beyond a soft contact shadow, no text, no watermark, no props, e-commerce product photography, sharp focus

Standard :

grok-imagine/text-to-image, 1:1, 2K, 2048×2048, $0.03, environ 80 secondes.

Quality :

Générer ce prompt sur Quality →

grok-imagine-quality/text-to-image, 1:1, 2K, 2048×2048, $0.10, environ 78 secondes.

Les différences :

• L'objet lui-même : la version standard a rendu un cône propre mais générique, qui ressemble plus à un bol qu'à un dripper. Quality a dessiné les éléments qui en font un dripper à infusion lente : les nervures hélicoïdales internes, la poignée et la base percée d'un orifice d'écoulement.
• Les deux ont respecté les consignes de fond : blanc pur, centré, une seule ombre de contact douce, sans accessoires ni texte.
• Même taille et même vitesse : les deux renvoient une image 2048×2048 en environ 80 secondes. Le palier change le niveau de détail, pas la taille de sortie.

Pour un produit connu, Quality vaut les $0.07 supplémentaires. Pour des cas où l'objet lui-même est générique, comme une planche d'ambiance ou une mise en page, la version standard suffit.

Image-image : placez votre produit dans une scène

Passez 1 à 3 URL d'images publiques dans image_urls et décrivez les modifications souhaitées. Lorsque aspect_ratio est défini sur auto (valeur par défaut en image-image), la sortie adopte la forme de la première image de la liste. Même prompt, mêmes deux images, seul l'ordre change, et l'on obtient deux recadrages différents :

grok-imagine/image-to-image, photo produit en premier, renvoie 1248×832 (3:2).

Même requête, photo de scène en premier, renvoie 1024×1024 (1:1).

Pour contrôler le recadrage, placez en premier l'image dont vous voulez la forme, ou définissez explicitement aspect_ratio.

Avec Quality, son point fort est de changer une seule chose tout en gardant tout le reste inchangé. Ce relighting a conservé le visage, la veste, la tasse et la composition :

Relight this photo as late golden hour: warm low sun coming from the left,
long soft shadows across the table, amber rim light on her hair and jacket.
Keep her face, expression, pose, the corduroy jacket, the marble table, the
coffee cup and the entire composition exactly the same. Photorealistic, same
camera angle, same framing.

grok-imagine-quality/image-to-image, 1K, auto (entrée 3:2, sortie 1248×832), une image de référence, $0.095, 39 secondes.

Le schéma qui fonctionne : une phrase pour indiquer ce qui doit changer, puis la liste de tout ce qui doit rester inchangé. Pour d'autres recettes, consultez Prompts image-image Grok Imagine Quality.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "A lighthouse on a rocky cliff at golden hour, waves crashing below, photorealistic",
      "aspect_ratio": "2:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Vous recevez un taskId. Interrogez GET https://api.hiapi.ai/v1/tasks/{taskId} jusqu'à ce que data.status vaille success, puis téléchargez data.output[0].url. Ce lien expire, enregistrez le fichier immédiatement.

Python : les quatre points de terminaison

# pip install requests; export HIAPI_KEY=your-key first
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, prompt, image_urls=None, timeout_s=300, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    if image_urls:
        body["input"]["image_urls"] = image_urls
    # Reuse the same Idempotency-Key if you retry a submit, so a retry never bills twice
    r = requests.post(API, json=body, headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)  # 400s list every invalid field
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

# Draft on standard, then re-run the keeper on Quality
draft = generate("grok-imagine/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="1k")
final = generate("grok-imagine-quality/text-to-image", "matte ceramic pour-over dripper, white background",
                 aspect_ratio="1:1", resolution="2k")

# Composite a product into a scene; the first image sets the shape
edit = generate("grok-imagine/image-to-image",
                "Place the product from the first image on the desk in the second image, matching its light",
                image_urls=["https://your-cdn.example.com/product.jpg",
                            "https://your-cdn.example.com/scene.jpg"])

Paramètres

Champ	Obligatoire	Valeurs	Description
prompt	Oui	Texte	Tout ce que vous voulez obtenir ou éviter s'écrit ici
image_urls	Image-image uniquement	1 à 3 URL	jpeg, png ou webp ; SVG non pris en charge ; chaque image de référence augmente le prix
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 ; l'image-image accepte aussi auto	auto suit la première image
resolution	Non	1k (par défaut), 2k	En minuscules ; n'affecte le prix qu'avec Quality
output_format	Non	jpeg (par défaut), png, webp

Les formats ultra-larges 2:1 et 20:9 conviennent aux bannières. Il n'y a pas de 21:9 ; utilisez 20:9.

Erreurs que vous rencontrerez

Toutes les erreurs ci-dessous renvoient un HTTP 400 à la soumission, donc aucune tâche n'est créée et aucun frais n'est engagé :

• resolution: value must be one of '1k', '2k' : vous avez envoyé 2K. Utilisez les minuscules.
• aspect_ratio: value must be one of ... : généralement 21:9. Utilisez 20:9.
• additional properties 'n' not allowed (ou seed, negative_prompt, size) : ces champs n'existent pas. Une tâche génère une image ; pour plusieurs images, envoyez plusieurs tâches.
• image_urls: missing required field : l'image-image nécessite au moins une image.

Une clé invalide renvoie 401. Les échecs survenant après la création de la tâche apparaissent lors de l'interrogation avec status: "fail", donc vérifiez data.status, pas seulement le code de statut HTTP.

FAQ

Standard ou Quality ?

Utilisez la version standard à $0.03 pour les brouillons. Une fois que le prompt et la mise en page fonctionnent, relancez le rendu final avec Quality. En standard, le 2K coûte le même prix que le 1K, donc demandez toujours 2k dans ce cas.

Est-ce la même chose que Grok Imagine Image 2.0 ?

Non. grok-imagine-image-2.0 est un modèle distinct et plus récent, à $0.052 par image. Consultez Guide de génération texte-image Grok Imagine Image 2.0.

Peut-on obtenir plusieurs images en une seule requête ?

Non. Il n'y a pas de champ n. Envoyez une tâche par image ; elles s'exécutent en parallèle.

Combien de temps les sorties restent-elles disponibles ?

Les liens output[0].url expirent. Téléchargez et stockez vous-même les fichiers dès que la tâche réussit.

D'autres sorties réelles : visuels de catalogue produits en version standard et composition de scènes à partir de photos produits. Pour la vidéo, consultez Guide de l'API vidéo Grok Imagine.