Comment utiliser l'API image-to-image de Grok Image 2.0 ? Une image de référence, une phrase, et l'image est modifiée

Comment utiliser l'API image-to-image de Grok Image 2.0 ? Envoyez une image de référence accessible publiquement accompagnée d'une instruction d'édition, soumettez via POST /v1/tasks, puis récupérez par polling data.output[0].url pour obtenir l'image modifiée. Chaque image coûte 0,065 $, avec un prix identique en 1K et 2K, sans masque ni calque.

Grok Image 2.0 est déjà disponible sur HiAPI. Ouvrez la page du modèle image-to-image pour modifier une image en en téléversant une ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription, de quoi générer 1 image-to-image (130 crédits).

TL;DR

• De quoi s'agit-il : grok-imagine-image-2.0/image-to-image, développé par xAI, modifie une image à partir d'une seule image de référence et d'une instruction en langage naturel : changer l'arrière-plan, ajouter de petits objets, modifier la couleur ou la matière, tout est possible.
• Combien ça coûte : 0,065 $ par image, prix identique en 1K / 2K et pour low / medium ; facturation à la génération réussie, remboursement automatique en cas d'échec. Environ 153 images pour 10 $.
• Comment appeler au plus vite : seuls prompt et image sont obligatoires ; image est une chaîne URL, pas un tableau.

Quels sont les paramètres de l'image-to-image de Grok Image 2.0 ?

Champ	Obligatoire	Valeurs	Description
prompt	Oui	Chaîne	Instruction d'édition
image	Oui	Chaîne	URL d'une image JPG / JPEG / PNG / WebP accessible publiquement, pas un tableau
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
aspect_ratio	Non	Les mêmes 14 valeurs que le text-to-image	Peut être envoyé, mais sans effet : le format de sortie suit l'image de référence

Une seule image de référence peut être modifiée à la fois, une tâche produit une image ; pour plusieurs images, soumettez plusieurs tâches exécutées en parallèle. Les requêtes contenant des noms de champs ou des valeurs hors de ce tableau renvoient une erreur 400.

Deux approches : essai en ligne et API

Essai en ligne (1 minute)

1. Ouvrez la page du modèle image-to-image, connectez-vous et téléversez une image de référence.
2. Saisissez l'instruction d'édition et choisissez la résolution.
3. Cliquez sur « Exécuter », puis comparez l'image de référence et l'image générée une fois la tâche réussie.

Intégration API (5 minutes)

1. Créez une clé API dans la console.
2. Placez l'image de référence à une adresse accessible publiquement (votre CDN ou un stockage objet).
3. Soumettez la tâche via POST /v1/tasks, puis faites du polling ou configurez un callback.
4. Dès le succès, téléchargez immédiatement data.output[0].url.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Essayez directement un prompt d'édition : déplacer le vieux luthier de son atelier de copeaux de bois vers un marché ensoleillé, sans toucher au personnage. Générer avec ce prompt → (le lien ne préremplit que le prompt ; téléversez l'image de référence sur la page du modèle et choisissez la résolution 2K)

Image de référence	Image générée

curl et Python : réussir sa première édition d'image

Commencez par définir la clé API :

export HIAPI_API_KEY="sk-..."

Toutes les requêtes incluent Authorization: Bearer sk-<key>. L'édition d'image est asynchrone et partage la même interface de tâches que les autres modèles HiAPI. L'image de référence est récupérée côté serveur : un chemin de fichier local ne fonctionne pas, il faut une URL accessible publiquement.

É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/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Renvoie immédiatement un taskId :

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

Étape 2 : faire du polling jusqu'à l'état final :

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

Vérifiez data.status : success indique un succès, fail un échec ; les autres états signifient qu'il faut continuer à attendre. Exemple de réponse en cas de succès :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "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 copiez-la vers votre propre stockage objet. Le format de sortie suit l'image de référence ; l'exemple omet aspect_ratio qui n'a pas d'effet.

Version Python :

Installez d'abord requests (python3 -m pip install requests) et définissez la variable HIAPI_API_KEY ci-dessus. Le script fait du polling 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 edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "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 = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

À quoi faire attention avant la mise en production ?

• Placez d'abord l'image de référence sur le réseau public. Si l'image téléversée par l'utilisateur se trouve dans un bucket privé ou sur localhost, la plateforme ne peut pas la récupérer et la tâche échoue de manière asynchrone ; avant de soumettre, vérifiez que le lien est accessible publiquement et utilisez une adresse à longue durée de validité (pas de lien signé qui expire).

• Formulez l'instruction comme « ce qui reste, ce qui change ». Écrivez d'abord ce qui doit rester inchangé, puis ce qui doit être modifié : plus le périmètre de modification est étroit, plus le résultat est stable. Pour d'autres formulations, voir les modèles de prompts image-to-image.

• Pour le traitement en lot, utilisez les callbacks plutôt qu'une boucle de polling serrée.

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

  when: "final" notifie lorsque la tâche atteint un état final de succès ou d'échec ; le récepteur déduplique selon taskId.

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

• Ne soumettez qu'une seule fois par tâche. Après réception de la réponse, conservez la correspondance entre le taskId et votre tâche métier ; une soumission répétée peut créer plusieurs tâches et être facturée séparément. Si la requête de création dépasse le délai sans renvoyer d'ID, vérifiez d'abord l'enregistrement de la tâche avant de décider de soumettre à nouveau.

• Indiquez explicitement resolution. La valeur par défaut est 1k ; 1K et 2K étant au même prix (0,065 $), envoyez directement "2k" pour les rendus finaux.

• Gestion des erreurs. Vérifiez d'abord le statut HTTP et les champs code, message de la réponse, puis lisez data. Les erreurs de paramètres ou d'authentification doivent être corrigées avant de resoumettre ; lorsque la tâche renvoie fail, journalisez l'erreur et arrêtez le polling.

À lire également

• Page du modèle text-to-image de Grok Image 2.0 : même série, génère de nouvelles images à partir de texte uniquement.
• Combien coûte l'API Grok Image 2.0 ?
• Intégration de l'API text-to-image de Grok Image 2.0
• Modèles de prompts image-to-image de Grok Image 2.0
• Authentification et Démarrage rapide

Questions fréquentes

image prend une URL ou un tableau ? Une seule chaîne URL. Passer un tableau provoque une erreur de type. Pour fusionner plusieurs images, utilisez un modèle prenant en charge plusieurs images de référence.

Que faire en cas d'erreur "additional properties not allowed" ? input n'accepte que prompt, image, aspect_ratio, resolution, quality. Les champs courants d'autres modèles d'édition comme image_urls, strength, mask, seed ou negative_prompt ne sont pas disponibles ici : supprimez-les.

L'image de référence s'ouvre dans le navigateur, pourquoi la tâche peut-elle quand même échouer ? La plateforme récupère l'image côté serveur : l'image de référence doit être accessible sans connexion et depuis le réseau public ; les liens signés doivent rester valides jusqu'à la fin de la récupération. Vérifiez les autorisations d'accès, le format et la durée de validité du lien avant de soumettre.

Peut-on modifier plusieurs images à la fois ? Non, une image en entrée, une image en sortie. Pour du volume, soumettez plusieurs tâches exécutées en parallèle.

Pourquoi l'image-to-image coûte-t-il plus cher que le text-to-image ? L'image-to-image coûte 0,065 $, le text-to-image 0,052 $, soit 25 % de plus, ce qui correspond à la capacité de « modifier une image en fournissant une image de référence ».

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

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 un petit script, faites du polling sur GET /v1/tasks/<taskId> ; en production, configurez un callback.

Modifiez votre première image dès maintenant

Définissez d'abord HIAPI_API_KEY, puis remplacez l'adresse image des exemples curl et Python par l'URL publique de votre propre image. Pour voir le résultat d'abord, ouvrez la page du modèle image-to-image, téléversez une image puis collez le prompt ci-dessus.